Preview
curl --request POST \
--url https://api.revenuebase.ai/v2/contact/preview \
--header 'Content-Type: application/json' \
--header 'X-Key: <api-key>' \
--data '
{
"filter": {
"type": "group",
"op": "AND",
"children": [
{
"type": "condition",
"column": "COUNTRY_NAME_PER",
"operator": "eq",
"value": "United States"
},
{
"type": "condition",
"column": "JOB_LEVEL_PER",
"operator": "eq",
"value": "VP"
}
]
},
"columns": [
"RBID_PAO",
"FULL_NAME_PER",
"JOB_TITLE_PER",
"COMPANY_NAME_ORG",
"EMAIL_ADDRESS_PER"
],
"limit": 2,
"reveal": [
"email"
]
}
'import requests
url = "https://api.revenuebase.ai/v2/contact/preview"
payload = {
"filter": {
"type": "group",
"op": "AND",
"children": [
{
"type": "condition",
"column": "COUNTRY_NAME_PER",
"operator": "eq",
"value": "United States"
},
{
"type": "condition",
"column": "JOB_LEVEL_PER",
"operator": "eq",
"value": "VP"
}
]
},
"columns": ["RBID_PAO", "FULL_NAME_PER", "JOB_TITLE_PER", "COMPANY_NAME_ORG", "EMAIL_ADDRESS_PER"],
"limit": 2,
"reveal": ["email"]
}
headers = {
"X-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
filter: {
type: 'group',
op: 'AND',
children: [
{
type: 'condition',
column: 'COUNTRY_NAME_PER',
operator: 'eq',
value: 'United States'
},
{type: 'condition', column: 'JOB_LEVEL_PER', operator: 'eq', value: 'VP'}
]
},
columns: [
'RBID_PAO',
'FULL_NAME_PER',
'JOB_TITLE_PER',
'COMPANY_NAME_ORG',
'EMAIL_ADDRESS_PER'
],
limit: 2,
reveal: ['email']
})
};
fetch('https://api.revenuebase.ai/v2/contact/preview', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.revenuebase.ai/v2/contact/preview",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'filter' => [
'type' => 'group',
'op' => 'AND',
'children' => [
[
'type' => 'condition',
'column' => 'COUNTRY_NAME_PER',
'operator' => 'eq',
'value' => 'United States'
],
[
'type' => 'condition',
'column' => 'JOB_LEVEL_PER',
'operator' => 'eq',
'value' => 'VP'
]
]
],
'columns' => [
'RBID_PAO',
'FULL_NAME_PER',
'JOB_TITLE_PER',
'COMPANY_NAME_ORG',
'EMAIL_ADDRESS_PER'
],
'limit' => 2,
'reveal' => [
'email'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.revenuebase.ai/v2/contact/preview"
payload := strings.NewReader("{\n \"filter\": {\n \"type\": \"group\",\n \"op\": \"AND\",\n \"children\": [\n {\n \"type\": \"condition\",\n \"column\": \"COUNTRY_NAME_PER\",\n \"operator\": \"eq\",\n \"value\": \"United States\"\n },\n {\n \"type\": \"condition\",\n \"column\": \"JOB_LEVEL_PER\",\n \"operator\": \"eq\",\n \"value\": \"VP\"\n }\n ]\n },\n \"columns\": [\n \"RBID_PAO\",\n \"FULL_NAME_PER\",\n \"JOB_TITLE_PER\",\n \"COMPANY_NAME_ORG\",\n \"EMAIL_ADDRESS_PER\"\n ],\n \"limit\": 2,\n \"reveal\": [\n \"email\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.revenuebase.ai/v2/contact/preview")
.header("X-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"filter\": {\n \"type\": \"group\",\n \"op\": \"AND\",\n \"children\": [\n {\n \"type\": \"condition\",\n \"column\": \"COUNTRY_NAME_PER\",\n \"operator\": \"eq\",\n \"value\": \"United States\"\n },\n {\n \"type\": \"condition\",\n \"column\": \"JOB_LEVEL_PER\",\n \"operator\": \"eq\",\n \"value\": \"VP\"\n }\n ]\n },\n \"columns\": [\n \"RBID_PAO\",\n \"FULL_NAME_PER\",\n \"JOB_TITLE_PER\",\n \"COMPANY_NAME_ORG\",\n \"EMAIL_ADDRESS_PER\"\n ],\n \"limit\": 2,\n \"reveal\": [\n \"email\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.revenuebase.ai/v2/contact/preview")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"filter\": {\n \"type\": \"group\",\n \"op\": \"AND\",\n \"children\": [\n {\n \"type\": \"condition\",\n \"column\": \"COUNTRY_NAME_PER\",\n \"operator\": \"eq\",\n \"value\": \"United States\"\n },\n {\n \"type\": \"condition\",\n \"column\": \"JOB_LEVEL_PER\",\n \"operator\": \"eq\",\n \"value\": \"VP\"\n }\n ]\n },\n \"columns\": [\n \"RBID_PAO\",\n \"FULL_NAME_PER\",\n \"JOB_TITLE_PER\",\n \"COMPANY_NAME_ORG\",\n \"EMAIL_ADDRESS_PER\"\n ],\n \"limit\": 2,\n \"reveal\": [\n \"email\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"rows": [
{
"RBID_PAO": "rb-pab23456t-rb-oadkxzpcq",
"FULL_NAME_PER": "Matthew Tobin",
"JOB_TITLE_PER": "Senior Vice President Business Development",
"COMPANY_NAME_ORG": "Ecapital Corp",
"EMAIL_ADDRESS_PER": "mtobin@ecapital.com"
},
{
"RBID_PAO": "rb-pab2346sr-rb-oacopeifk",
"FULL_NAME_PER": "Katherine Collins",
"JOB_TITLE_PER": "AVP of Claim Operations",
"COMPANY_NAME_ORG": "Travelers",
"EMAIL_ADDRESS_PER": "katherine.collins@travelers.com"
}
],
"columns": [
"RBID_PAO",
"FULL_NAME_PER",
"JOB_TITLE_PER",
"COMPANY_NAME_ORG",
"EMAIL_ADDRESS_PER"
],
"columnLabels": {
"RBID_PAO": "Rbid Person And Organization",
"FULL_NAME_PER": "Person Full Name",
"JOB_TITLE_PER": "Job Title",
"COMPANY_NAME_ORG": "Company Name",
"EMAIL_ADDRESS_PER": "Email Address"
},
"rowCount": 2,
"limit": 2
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Contact Endpoints
Preview matching contacts
Get matching contact records as JSON in the same response.
POST
/
preview
Preview
curl --request POST \
--url https://api.revenuebase.ai/v2/contact/preview \
--header 'Content-Type: application/json' \
--header 'X-Key: <api-key>' \
--data '
{
"filter": {
"type": "group",
"op": "AND",
"children": [
{
"type": "condition",
"column": "COUNTRY_NAME_PER",
"operator": "eq",
"value": "United States"
},
{
"type": "condition",
"column": "JOB_LEVEL_PER",
"operator": "eq",
"value": "VP"
}
]
},
"columns": [
"RBID_PAO",
"FULL_NAME_PER",
"JOB_TITLE_PER",
"COMPANY_NAME_ORG",
"EMAIL_ADDRESS_PER"
],
"limit": 2,
"reveal": [
"email"
]
}
'import requests
url = "https://api.revenuebase.ai/v2/contact/preview"
payload = {
"filter": {
"type": "group",
"op": "AND",
"children": [
{
"type": "condition",
"column": "COUNTRY_NAME_PER",
"operator": "eq",
"value": "United States"
},
{
"type": "condition",
"column": "JOB_LEVEL_PER",
"operator": "eq",
"value": "VP"
}
]
},
"columns": ["RBID_PAO", "FULL_NAME_PER", "JOB_TITLE_PER", "COMPANY_NAME_ORG", "EMAIL_ADDRESS_PER"],
"limit": 2,
"reveal": ["email"]
}
headers = {
"X-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
filter: {
type: 'group',
op: 'AND',
children: [
{
type: 'condition',
column: 'COUNTRY_NAME_PER',
operator: 'eq',
value: 'United States'
},
{type: 'condition', column: 'JOB_LEVEL_PER', operator: 'eq', value: 'VP'}
]
},
columns: [
'RBID_PAO',
'FULL_NAME_PER',
'JOB_TITLE_PER',
'COMPANY_NAME_ORG',
'EMAIL_ADDRESS_PER'
],
limit: 2,
reveal: ['email']
})
};
fetch('https://api.revenuebase.ai/v2/contact/preview', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.revenuebase.ai/v2/contact/preview",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'filter' => [
'type' => 'group',
'op' => 'AND',
'children' => [
[
'type' => 'condition',
'column' => 'COUNTRY_NAME_PER',
'operator' => 'eq',
'value' => 'United States'
],
[
'type' => 'condition',
'column' => 'JOB_LEVEL_PER',
'operator' => 'eq',
'value' => 'VP'
]
]
],
'columns' => [
'RBID_PAO',
'FULL_NAME_PER',
'JOB_TITLE_PER',
'COMPANY_NAME_ORG',
'EMAIL_ADDRESS_PER'
],
'limit' => 2,
'reveal' => [
'email'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.revenuebase.ai/v2/contact/preview"
payload := strings.NewReader("{\n \"filter\": {\n \"type\": \"group\",\n \"op\": \"AND\",\n \"children\": [\n {\n \"type\": \"condition\",\n \"column\": \"COUNTRY_NAME_PER\",\n \"operator\": \"eq\",\n \"value\": \"United States\"\n },\n {\n \"type\": \"condition\",\n \"column\": \"JOB_LEVEL_PER\",\n \"operator\": \"eq\",\n \"value\": \"VP\"\n }\n ]\n },\n \"columns\": [\n \"RBID_PAO\",\n \"FULL_NAME_PER\",\n \"JOB_TITLE_PER\",\n \"COMPANY_NAME_ORG\",\n \"EMAIL_ADDRESS_PER\"\n ],\n \"limit\": 2,\n \"reveal\": [\n \"email\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.revenuebase.ai/v2/contact/preview")
.header("X-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"filter\": {\n \"type\": \"group\",\n \"op\": \"AND\",\n \"children\": [\n {\n \"type\": \"condition\",\n \"column\": \"COUNTRY_NAME_PER\",\n \"operator\": \"eq\",\n \"value\": \"United States\"\n },\n {\n \"type\": \"condition\",\n \"column\": \"JOB_LEVEL_PER\",\n \"operator\": \"eq\",\n \"value\": \"VP\"\n }\n ]\n },\n \"columns\": [\n \"RBID_PAO\",\n \"FULL_NAME_PER\",\n \"JOB_TITLE_PER\",\n \"COMPANY_NAME_ORG\",\n \"EMAIL_ADDRESS_PER\"\n ],\n \"limit\": 2,\n \"reveal\": [\n \"email\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.revenuebase.ai/v2/contact/preview")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"filter\": {\n \"type\": \"group\",\n \"op\": \"AND\",\n \"children\": [\n {\n \"type\": \"condition\",\n \"column\": \"COUNTRY_NAME_PER\",\n \"operator\": \"eq\",\n \"value\": \"United States\"\n },\n {\n \"type\": \"condition\",\n \"column\": \"JOB_LEVEL_PER\",\n \"operator\": \"eq\",\n \"value\": \"VP\"\n }\n ]\n },\n \"columns\": [\n \"RBID_PAO\",\n \"FULL_NAME_PER\",\n \"JOB_TITLE_PER\",\n \"COMPANY_NAME_ORG\",\n \"EMAIL_ADDRESS_PER\"\n ],\n \"limit\": 2,\n \"reveal\": [\n \"email\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"rows": [
{
"RBID_PAO": "rb-pab23456t-rb-oadkxzpcq",
"FULL_NAME_PER": "Matthew Tobin",
"JOB_TITLE_PER": "Senior Vice President Business Development",
"COMPANY_NAME_ORG": "Ecapital Corp",
"EMAIL_ADDRESS_PER": "mtobin@ecapital.com"
},
{
"RBID_PAO": "rb-pab2346sr-rb-oacopeifk",
"FULL_NAME_PER": "Katherine Collins",
"JOB_TITLE_PER": "AVP of Claim Operations",
"COMPANY_NAME_ORG": "Travelers",
"EMAIL_ADDRESS_PER": "katherine.collins@travelers.com"
}
],
"columns": [
"RBID_PAO",
"FULL_NAME_PER",
"JOB_TITLE_PER",
"COMPANY_NAME_ORG",
"EMAIL_ADDRESS_PER"
],
"columnLabels": {
"RBID_PAO": "Rbid Person And Organization",
"FULL_NAME_PER": "Person Full Name",
"JOB_TITLE_PER": "Job Title",
"COMPANY_NAME_ORG": "Company Name",
"EMAIL_ADDRESS_PER": "Email Address"
},
"rowCount": 2,
"limit": 2
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Credits and plans
PAYG is Pay-as-you-go. AYCE is All-you-can-eat.| Usage | PAYG | AYCE |
|---|---|---|
| Contact row | 1 credit per returned row | Unlimited 0 credits |
| Revealed email | +1 credit per populated email | Unlimited 0 credits |
| Revealed mobile | +10 credits per populated mobile | Unlimited 0 credits |
| SmartSearch filter node | +10 credits per node per request | Included 0 credits |
| Rows per request | 50,000 maximum | 50,000 maximum |
reveal. A SmartSearch node is a
semantic or lookalike filter; ordinary field conditions add no search fee.
When to use Preview
Use Preview when your application needs the matching records immediately. It accepts the same audience filter as Count and View.
Preview is paid retrieval on PAYG. For a free sample with email and
mobile values masked, use View. On AYCE, contact retrieval is included;
the per-request and rate limits still apply.
Example: retrieve two matching contacts
Set your API key asREVENUEBASE_API_KEY. This reuses the audience
from the Count and View examples. It requests email, excludes mobile
charges, and limits the response to two records.
On PAYG, this request consumes credits. Omitting
reveal, or sending
null, selects both email and mobile. Removing those fields from
columns does not remove their reveal charges.curl --include --request POST 'https://api.revenuebase.ai/v2/contact/preview' \
--header "X-Key: $REVENUEBASE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"filter": {
"type": "group",
"op": "AND",
"children": [
{
"type": "condition",
"column": "COUNTRY_NAME_PER",
"operator": "eq",
"value": "United States"
},
{
"type": "condition",
"column": "JOB_LEVEL_PER",
"operator": "eq",
"value": "VP"
}
]
},
"columns": [
"RBID_PAO",
"FULL_NAME_PER",
"JOB_TITLE_PER",
"COMPANY_NAME_ORG",
"EMAIL_ADDRESS_PER"
],
"limit": 2,
"reveal": [
"email"
]
}'
{
"rows": [
{
"RBID_PAO": "rb-pab23456t-rb-oadkxzpcq",
"FULL_NAME_PER": "Matthew Tobin",
"JOB_TITLE_PER": "Senior Vice President Business Development",
"COMPANY_NAME_ORG": "Ecapital Corp",
"EMAIL_ADDRESS_PER": "mtobin@ecapital.com"
},
{
"RBID_PAO": "rb-pab2346sr-rb-oacopeifk",
"FULL_NAME_PER": "Katherine Collins",
"JOB_TITLE_PER": "AVP of Claim Operations",
"COMPANY_NAME_ORG": "Travelers",
"EMAIL_ADDRESS_PER": "katherine.collins@travelers.com"
}
],
"columns": [
"RBID_PAO",
"FULL_NAME_PER",
"JOB_TITLE_PER",
"COMPANY_NAME_ORG",
"EMAIL_ADDRESS_PER"
],
"columnLabels": {
"RBID_PAO": "Rbid Person And Organization",
"FULL_NAME_PER": "Person Full Name",
"JOB_TITLE_PER": "Job Title",
"COMPANY_NAME_ORG": "Company Name",
"EMAIL_ADDRESS_PER": "Email Address"
},
"rowCount": 2,
"limit": 2
}
| Field | What it means |
|---|---|
rows | The contact records returned by this request. Each row represents a person at a company. |
RBID_PAO | The person-at-company identifier. Request it if you need to retrieve a selected record later with Enrich. |
columns, columnLabels | Returned field names and display labels. |
rowCount | Records returned, rather than the audience’s total size. Use Count for that total. |
limit | The applied row cap. Fewer rows can return if fewer contacts match. |
warnings | Optional information about adjustments made to the filter. |
scoresOmitted | When true, requested similarity scores could not be added; the records still return. |
Control the credit hold
A PAYG request reserves enough credits for every row inlimit to
contain every selected detail, plus any SmartSearch filter fees.
Your balance must cover that amount before the query runs, even when
Count reports fewer matches.
reveal | Maximum PAYG hold per requested row, before SmartSearch |
|---|---|
[] | 1 credit |
["email"] | 2 credits |
["mobile"] | 11 credits |
["email", "mobile"] | 12 credits |
402 INSUFFICIENT_CREDITS. The API does not automatically return a
smaller affordable subset. Reduce limit or your reveal choices.
Options and limits
| Option | Behavior |
|---|---|
filter | Reuse the filter from Count or View. Omitted or null selects the whole dataset. |
limit | Defaults to 1,000 when omitted or null; values are clamped to 1 through 50,000. Set a positive cap explicitly. |
columns | Fields to return. Omitted or null uses the default set; ["*"] requests all fields. Available company fields on a contact row add no separate company-row charge. |
reveal | On PAYG, select email, mobile, both, or neither. Omitted or null selects both. Removing columns does not reduce reveal charges. |
includeScores | Adds available similarity fields for SmartSearch results. Defaults to false; it does not change unit credit prices. |
reveal selection becomes a hasEmail or hasMobile availability
boolean. On AYCE, columns controls the returned fields; reveal
does not mask them.
Preview has no pagination cursor. Repeating the request does not
fetch the next page. Normal results have no guaranteed ordering;
similarity scores can order the returned SmartSearch rows when available.
Use Export for a larger file or Enrich for particular records.
Errors and retries
| Response | What to do |
|---|---|
402 INSUFFICIENT_CREDITS | Reduce the row cap or selected details, or add credits. creditsRequired is the needed hold; creditsAvailable is your balance. |
400 or 422 | Correct the request, filter, or requested columns before retrying. |
429 | Follow Retry-After or wait until X-RateLimit-Reset. |
503 CREDITS_UNAVAILABLE | Credit metering is unavailable. Follow Retry-After before retrying. |
Next step
Use the returned records in your application. For a downloadable file, reuse the audience filter with Estimate and Export. For a selected set ofRBID_PAO values, use Enrich.Body
application/json
On PAYG, select email (+1 per populated value), mobile (+10), both, or neither ([]), in addition to 1 per contact row. Omitted or null selects both; columns do not change those charges. Unselected requested details become availability booleans. On AYCE, columns controls returned fields and reveal does not mask them.
Response
Successful Response
The response is of type Response Preview V1 Preview Post · object.
Was this page helpful?
