Preview matching contacts

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": {}
    }
  ]
}

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

PAYG prices add together. Email and mobile charges apply only to populated details selected by 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.

You need	Use
Check the audience without paying for contact details	Count, then View
Retrieve a filtered list as JSON, up to 50,000 rows	Preview
Retrieve only the contacts you selected in View	Enrich with their `RBID_PAO` values
Download a file, up to 1,000,000 rows	Estimate, then Export

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 as REVENUEBASE_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"
    ]
  }'

Response captured from the local test API on October 13, 2026 using an AYCE account. Results can change as the dataset or account changes.

{
  "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.

A missing selected email or mobile adds no detail charge. In this captured response, two returned contact rows and two populated emails would cost 4 PAYG credits. The AYCE call used 0 credits.

Control the credit hold

A PAYG request reserves enough credits for every row in limit 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

For the captured response, both returned contacts have an email. On PAYG, the request would hold 4 credits and charge 4 credits. This response was captured with an AYCE account and used 0 credits. If the balance cannot cover the hold, the request returns 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.

On PAYG, an email or mobile column requested without its corresponding 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.

An unsuccessful request releases its hold. An empty successful result has no row or detail charge, but SmartSearch filter fees can still apply. A repeated paid request can charge again, even for the same rows or a cached result. After an ambiguous timeout, the first request may have completed and charged your account. Do not assume retries are free.

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 of RBID_PAO values, use Enrich.

Authorizations

X-Key

string

header

required

Body

application/json

filter

GroupNode · object | null

Audience filter, shared with Count and View. Omitted or null selects the entire dataset. PAYG Preview adds 10 credits per semantic or lookalike filter node per request; ordinary field conditions add no search fee.

Show child attributes

columns

string[] | null

Fields to return. On Preview, omitted or null uses the default set; ["*"] requests all fields. Removing email or mobile columns does not reduce PAYG charges for details selected by reveal. Request RBID_PAO if you need a stable person-at-company identifier.

limit

integer | null

On Preview, maximum rows returned and the basis of the PAYG credit hold. Defaults to 1,000 when omitted or null; clamped to 1 through 50,000. Set a positive cap explicitly. This is not a pagination cursor.

includeSql

boolean

default:false

includeScores

boolean

default:false

Include available similarity fields for semantic or lookalike results. Defaults to false. Adds no separate credit fee; the paid SmartSearch filter-node charge still applies on PAYG.

reveal

string[] | null

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.

Getting Started

Contact API

Contact Endpoints

Company Endpoints

Email API

Utilities

Preview matching contacts

Credits and plans

When to use Preview

Example: retrieve two matching contacts

Control the credit hold

Options and limits

Errors and retries

Next step

Authorizations

Body

Response

​Credits and plans

​When to use Preview

​Example: retrieve two matching contacts

​Control the credit hold

​Options and limits

​Errors and retries

​Next step

Authorizations

Body

Response

Credits and plans

When to use Preview

Example: retrieve two matching contacts

Control the credit hold

Options and limits

Errors and retries

Next step