Insights
curl --request POST \
--url https://api.revenuebase.ai/v2/contact/insights \
--header 'Content-Type: application/json' \
--header 'X-Key: <api-key>' \
--data '
{
"filter": {
"type": "group",
"op": "AND",
"children": [
{
"type": "condition",
"column": "COUNTRY_CODE_PER",
"operator": "eq",
"value": "US"
}
]
},
"section": "reachability"
}
'import requests
url = "https://api.revenuebase.ai/v2/contact/insights"
payload = {
"filter": {
"type": "group",
"op": "AND",
"children": [
{
"type": "condition",
"column": "COUNTRY_CODE_PER",
"operator": "eq",
"value": "US"
}
]
},
"section": "reachability"
}
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_CODE_PER', operator: 'eq', value: 'US'}]
},
section: 'reachability'
})
};
fetch('https://api.revenuebase.ai/v2/contact/insights', 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/insights",
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_CODE_PER',
'operator' => 'eq',
'value' => 'US'
]
]
],
'section' => 'reachability'
]),
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/insights"
payload := strings.NewReader("{\n \"filter\": {\n \"type\": \"group\",\n \"op\": \"AND\",\n \"children\": [\n {\n \"type\": \"condition\",\n \"column\": \"COUNTRY_CODE_PER\",\n \"operator\": \"eq\",\n \"value\": \"US\"\n }\n ]\n },\n \"section\": \"reachability\"\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/insights")
.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_CODE_PER\",\n \"operator\": \"eq\",\n \"value\": \"US\"\n }\n ]\n },\n \"section\": \"reachability\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.revenuebase.ai/v2/contact/insights")
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_CODE_PER\",\n \"operator\": \"eq\",\n \"value\": \"US\"\n }\n ]\n },\n \"section\": \"reachability\"\n}"
response = http.request(request)
puts response.read_body{
"section": "reachability",
"reachability": {
"total": 106956086,
"withEmail": 24409894,
"withMobile": 45333156,
"withBoth": 13864920
}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Contact Endpoints
Insights
Analyze contact availability, freshness, audience composition, and field coverage before retrieval.
POST
/
insights
Insights
curl --request POST \
--url https://api.revenuebase.ai/v2/contact/insights \
--header 'Content-Type: application/json' \
--header 'X-Key: <api-key>' \
--data '
{
"filter": {
"type": "group",
"op": "AND",
"children": [
{
"type": "condition",
"column": "COUNTRY_CODE_PER",
"operator": "eq",
"value": "US"
}
]
},
"section": "reachability"
}
'import requests
url = "https://api.revenuebase.ai/v2/contact/insights"
payload = {
"filter": {
"type": "group",
"op": "AND",
"children": [
{
"type": "condition",
"column": "COUNTRY_CODE_PER",
"operator": "eq",
"value": "US"
}
]
},
"section": "reachability"
}
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_CODE_PER', operator: 'eq', value: 'US'}]
},
section: 'reachability'
})
};
fetch('https://api.revenuebase.ai/v2/contact/insights', 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/insights",
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_CODE_PER',
'operator' => 'eq',
'value' => 'US'
]
]
],
'section' => 'reachability'
]),
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/insights"
payload := strings.NewReader("{\n \"filter\": {\n \"type\": \"group\",\n \"op\": \"AND\",\n \"children\": [\n {\n \"type\": \"condition\",\n \"column\": \"COUNTRY_CODE_PER\",\n \"operator\": \"eq\",\n \"value\": \"US\"\n }\n ]\n },\n \"section\": \"reachability\"\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/insights")
.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_CODE_PER\",\n \"operator\": \"eq\",\n \"value\": \"US\"\n }\n ]\n },\n \"section\": \"reachability\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.revenuebase.ai/v2/contact/insights")
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_CODE_PER\",\n \"operator\": \"eq\",\n \"value\": \"US\"\n }\n ]\n },\n \"section\": \"reachability\"\n}"
response = http.request(request)
puts response.read_body{
"section": "reachability",
"reachability": {
"total": 106956086,
"withEmail": 24409894,
"withMobile": 45333156,
"withBoth": 13864920
}
}{
"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 |
|---|---|---|
| Analysis, including SmartSearch | Free 0 credits | Free 0 credits |
When to use Insights
- Check how many contacts have the details you need before paying to retrieve them.
- Compare audience composition or freshness while adjusting a filter.
- Measure how often selected fields are populated.
Example
SetREVENUEBASE_API_KEY to your API key.
curl --request POST 'https://api.revenuebase.ai/v2/contact/insights' \
--header "X-Key: $REVENUEBASE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"filter": {
"type": "group",
"op": "AND",
"children": [
{
"type": "condition",
"column": "COUNTRY_CODE_PER",
"operator": "eq",
"value": "US"
}
]
},
"section": "reachability"
}'
{
"section": "reachability",
"reachability": {
"total": 106956086,
"withEmail": 24409894,
"withMobile": 45333156,
"withBoth": 13864920
}
}
Choose one section
| section | What you learn | Where to read it |
|---|---|---|
reachability | Contact rows with an email, mobile, or both. | reachability: total, withEmail, withMobile, withBoth. |
freshness | How recently emails and profiles were checked. | freshness.email and freshness.updated: nonNull, withinSla, medianDays, and buckets. |
coverage | The audience grouped by a field. | coverage: groupField and rows with value, total, withEmail, withMobile. |
fillRate | Availability of the fields you select. | fillRates: field, total, and populated counts. |
Options and limits
| Input | How to use it |
|---|---|
filter | Reuse the audience filter from Count. Omitted or null analyzes all contact rows. |
fields | For fillRate, supply up to 12 recognized distinct fields. With no usable fields, the result is an empty list. |
groupField | For coverage, choose a supported column. The default is JOB_LEVEL_PER. |
Errors and retries
An unsupported section returns 400. Correct invalid fields or filters before retrying 400 or 422. Contact and company routes share the default 10 requests per second per user. Wait for the reset time or Retry-After when rate limited; coordinate requests across your workers and API keys.Next steps
Inspect a free masked View, retrieve a bounded Preview, or estimate an export. Company-only analysis uses Company Insights.Authorizations
Body
application/json
One case-sensitive section: reachability, freshness, coverage, or fillRate.
Audience filter shared with Count and View. Omitted or null analyzes all contact rows.
Show child attributes
Show child attributes
For fillRate, up to 12 recognized distinct fields. An empty usable selection returns an empty list.
For coverage, a supported field. Defaults to JOB_LEVEL_PER.
Response
Successful Response
The response is of type Response Insights V1 Insights Post · object.
Was this page helpful?
