Start Export
curl --request POST \
--url https://api.revenuebase.ai/v2/contact/exports \
--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": [
"FULL_NAME_PER",
"JOB_TITLE_PER",
"COMPANY_NAME_ORG",
"EMAIL_ADDRESS_PER"
],
"maxRows": 100,
"reveal": [
"email"
],
"format": "csv",
"compression": "gz"
}
'import requests
url = "https://api.revenuebase.ai/v2/contact/exports"
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": ["FULL_NAME_PER", "JOB_TITLE_PER", "COMPANY_NAME_ORG", "EMAIL_ADDRESS_PER"],
"maxRows": 100,
"reveal": ["email"],
"format": "csv",
"compression": "gz"
}
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: ['FULL_NAME_PER', 'JOB_TITLE_PER', 'COMPANY_NAME_ORG', 'EMAIL_ADDRESS_PER'],
maxRows: 100,
reveal: ['email'],
format: 'csv',
compression: 'gz'
})
};
fetch('https://api.revenuebase.ai/v2/contact/exports', 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/exports",
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' => [
'FULL_NAME_PER',
'JOB_TITLE_PER',
'COMPANY_NAME_ORG',
'EMAIL_ADDRESS_PER'
],
'maxRows' => 100,
'reveal' => [
'email'
],
'format' => 'csv',
'compression' => 'gz'
]),
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/exports"
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 \"FULL_NAME_PER\",\n \"JOB_TITLE_PER\",\n \"COMPANY_NAME_ORG\",\n \"EMAIL_ADDRESS_PER\"\n ],\n \"maxRows\": 100,\n \"reveal\": [\n \"email\"\n ],\n \"format\": \"csv\",\n \"compression\": \"gz\"\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/exports")
.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 \"FULL_NAME_PER\",\n \"JOB_TITLE_PER\",\n \"COMPANY_NAME_ORG\",\n \"EMAIL_ADDRESS_PER\"\n ],\n \"maxRows\": 100,\n \"reveal\": [\n \"email\"\n ],\n \"format\": \"csv\",\n \"compression\": \"gz\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.revenuebase.ai/v2/contact/exports")
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 \"FULL_NAME_PER\",\n \"JOB_TITLE_PER\",\n \"COMPANY_NAME_ORG\",\n \"EMAIL_ADDRESS_PER\"\n ],\n \"maxRows\": 100,\n \"reveal\": [\n \"email\"\n ],\n \"format\": \"csv\",\n \"compression\": \"gz\"\n}"
response = http.request(request)
puts response.read_body{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Contact Endpoints
Export matching contacts
Download a filtered contact list with the row cap, contact details, and file format you choose.
POST
/
exports
Start Export
curl --request POST \
--url https://api.revenuebase.ai/v2/contact/exports \
--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": [
"FULL_NAME_PER",
"JOB_TITLE_PER",
"COMPANY_NAME_ORG",
"EMAIL_ADDRESS_PER"
],
"maxRows": 100,
"reveal": [
"email"
],
"format": "csv",
"compression": "gz"
}
'import requests
url = "https://api.revenuebase.ai/v2/contact/exports"
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": ["FULL_NAME_PER", "JOB_TITLE_PER", "COMPANY_NAME_ORG", "EMAIL_ADDRESS_PER"],
"maxRows": 100,
"reveal": ["email"],
"format": "csv",
"compression": "gz"
}
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: ['FULL_NAME_PER', 'JOB_TITLE_PER', 'COMPANY_NAME_ORG', 'EMAIL_ADDRESS_PER'],
maxRows: 100,
reveal: ['email'],
format: 'csv',
compression: 'gz'
})
};
fetch('https://api.revenuebase.ai/v2/contact/exports', 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/exports",
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' => [
'FULL_NAME_PER',
'JOB_TITLE_PER',
'COMPANY_NAME_ORG',
'EMAIL_ADDRESS_PER'
],
'maxRows' => 100,
'reveal' => [
'email'
],
'format' => 'csv',
'compression' => 'gz'
]),
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/exports"
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 \"FULL_NAME_PER\",\n \"JOB_TITLE_PER\",\n \"COMPANY_NAME_ORG\",\n \"EMAIL_ADDRESS_PER\"\n ],\n \"maxRows\": 100,\n \"reveal\": [\n \"email\"\n ],\n \"format\": \"csv\",\n \"compression\": \"gz\"\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/exports")
.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 \"FULL_NAME_PER\",\n \"JOB_TITLE_PER\",\n \"COMPANY_NAME_ORG\",\n \"EMAIL_ADDRESS_PER\"\n ],\n \"maxRows\": 100,\n \"reveal\": [\n \"email\"\n ],\n \"format\": \"csv\",\n \"compression\": \"gz\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.revenuebase.ai/v2/contact/exports")
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 \"FULL_NAME_PER\",\n \"JOB_TITLE_PER\",\n \"COMPANY_NAME_ORG\",\n \"EMAIL_ADDRESS_PER\"\n ],\n \"maxRows\": 100,\n \"reveal\": [\n \"email\"\n ],\n \"format\": \"csv\",\n \"compression\": \"gz\"\n}"
response = http.request(request)
puts response.read_body{
"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.| Export usage | PAYG | AYCE |
|---|---|---|
| Contact row | 1 credit per 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 |
- PAYG prices add together. Email/mobile charges apply only to populated details selected by
reveal. - AYCE includes unlimited contact retrieval. The 1,000,000-row limit per export and rate limits still apply.
maxRows to retrieve a
subset or to cap a larger pull.
Choose Export or another endpoint
Before starting, use Count, View, and Estimate, then confirm the
hold fits your balance.
The examples use
REVENUEBASE_API_KEY for your API key.
Start a bounded export
This exports up to 100 US VPs with email selected and mobile excluded. It is the same request body as the Estimate example.Running this POST spends credits on PAYG when the export completes.
Omitting
reveal, or sending null, selects both email and mobile.
Choosing fewer columns does not remove reveal charges.curl --include --request POST 'https://api.revenuebase.ai/v2/contact/exports' \
--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": [
"FULL_NAME_PER",
"JOB_TITLE_PER",
"COMPANY_NAME_ORG",
"EMAIL_ADDRESS_PER"
],
"maxRows": 100,
"reveal": [
"email"
],
"format": "csv",
"compression": "gz"
}'
exportId as REVENUEBASE_EXPORT_ID for the status and cancellation calls below.
For a metered account, this example reserves up to 200 credits.
Read the X-Credits-Held response header. Acceptance is not completion,
and held credits are not the final charge.
| Field | What it means |
|---|---|
exportId | Save this identifier to poll or cancel the same job. |
status | The current job state; QUEUED is still pending. |
format, compression | The file format and compression selected. |
maxRows | The applied row cap, rather than a promise that this many rows match. |
Poll the existing export
SetEXPORT_ID to the identifier returned by the start request.
Poll every 5–10 seconds initially; back off for longer jobs and respect
X-RateLimit-Reset after a 429. Status requests cost 0 credits.
curl 'https://api.revenuebase.ai/v2/contact/exports/'"$EXPORT_ID" \
--header "X-Key: $REVENUEBASE_API_KEY"
| Status | What to do |
|---|---|
QUEUED | Wait and poll; the job has been accepted. |
PROCESSING | Wait and poll; the file is being written. |
CANCELLING | Wait and poll until cancellation finishes. |
COMPLETED | Stop polling and download using downloadUrl. |
ERROR | Stop polling. Read code and error; an unfinished failed job releases its hold. |
CANCELLED | Stop polling. No file is produced; the unfinished job releases its hold. |
rowCount is the number actually written. The completed status response
does not include a final charged-credit field. The credit rules below
explain how that amount is calculated.
Download the file
SetDOWNLOAD_URL to the signed URL from the completed response.
The signed URL authorizes the download; no API-key header is required.
Treat it as a credential and share it only with intended recipients.
curl --fail --location --output contacts.csv.gz "$DOWNLOAD_URL"
expiresInSeconds (normally one hour). Poll
the same export again for a fresh link. Downloading that completed file
again does not start another charged export. Starting a new POST can
charge again, even for the same filter and records.
Credits and options
Final PAYG charge: returned contact rows + populated revealed emails + 10 × populated revealed mobiles + 10 × SmartSearch filter nodes. For 100 contacts with 80 emails,reveal: ["email"] costs 180 credits
without SmartSearch. With both details selected, 20 mobiles, and one
SmartSearch node, the charge is 390 credits. A successful empty export
has no row/detail charge but can still incur the SmartSearch amount.
| Option | Effect |
|---|---|
maxRows | Positive row cap, up to 1,000,000. With an explicit cap, the hold assumes all selected details are populated on every capped row. |
reveal | [], ["email"], ["mobile"], or ["email", "mobile"]. Omitted/null defaults to both. Unselected requested details become availability booleans. |
columns | Fields included in the file. A contact row’s available company fields have no separate company-row surcharge. Direct dial has no separate field surcharge. |
format | csv, json (default), or parquet. |
compression | gz (default), zip, or none. |
filename | Optional base name, up to 150 characters. Letters, digits, spaces, and . _ ( ) - are allowed; the API adds the format/compression extension. |
maxRows limits quantity; it does not identify particular chosen rows
or provide pagination. Use Enrich for selected IDs. An omitted/null
filter means the entire dataset; an omitted row cap uses the service
maximum. Send a positive cap and explicit reveal choices to bound spend.
Cancel or recover
To cancel an unfinished job, use the existing export ID:curl --request DELETE 'https://api.revenuebase.ai/v2/contact/exports/'"$EXPORT_ID" \
--header "X-Key: $REVENUEBASE_API_KEY"
CANCELLED; the hold is released when the unfinished job ends.
Cancelling an already completed job returns its terminal state and
does not refund the completed export.
| Response or error | Action |
|---|---|
402 INSUFFICIENT_CREDITS | No job starts. Lower maxRows, reduce reveal, or add credits, then estimate again. creditsRequired reports the needed hold and creditsAvailable your available balance. |
400 / 422 | Correct the format, filename, filter, or columns before retrying. |
429 | Wait for the rate-limit reset. |
503 ESTIMATE_UNAVAILABLE on a start without maxRows | Retry with an explicit affordable positive row cap; the uncapped start’s count timed out. |
503 CREDITS_UNAVAILABLE | Metering is temporarily unavailable. Follow Retry-After before retrying. |
Export state ERROR with EXPORT_TIMEOUT | Narrow the audience or reduce the row cap before starting another job. |
Export state ERROR with EXPORT_FAILED | Read error; contact support with the export ID if the failure persists. |
Status/cancel 403 / 404 | Use the export owner’s API key and verify the export ID. |
Do not automatically repeat a start POST after an ambiguous timeout:
the original job may have been accepted. When you have an export ID,
check its status. The API does not promise that repeating a customer
start POST will return the same job or avoid another charge.
Next step
Use Export Status to follow the job, or Cancel Export to stop it before completion. For another audience, begin with Count.Authorizations
Body
application/json
Audience filter, shared with Count and View. Omitted/null selects the entire dataset. Each semantic/lookalike node adds 10 credits on a paid export.
Show child attributes
Show child attributes
Fields written to the file. Omitted/null uses the default set; ["*"] requests all. Removing email/mobile columns does not remove reveal charges.
File format: csv, json (default), or parquet. Does not change unit credit prices.
gz (default), zip, or none. Does not change unit credit prices.
Positive row cap, up to 1,000,000. With an explicit cap, the hold assumes every selected contact detail is populated on every capped row. Omitted/null or 0 uses the maximum; 0 does not mean zero rows.
Optional base filename: 1–150 letters, digits, spaces, or . _ ( ) -. The API adds the selected file/compression extension.
Buy email (+1 per populated value), mobile (+10), both, or neither ([]), in addition to 1 per contact row. Omitted/null buys both. Columns do not change these charges. Unselected requested fields become availability booleans.
Response
Export accepted. Save exportId and poll the existing job.
Was this page helpful?