Enrich leads

curl --request POST \
  --url https://app.bettercontact.rocks/api/v2/async \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "data": [
    {
      "first_name": "Elon",
      "last_name": "Musk",
      "company": "Tesla",
      "company_domain": "tesla.com",
      "linkedin_url": "https://www.linkedin.com/in/elonmusk",
      "custom_fields": {
        "uuid": "crm-8821",
        "list_name": "Q3 outbound"
      }
    }
  ],
  "enrich_email_address": true,
  "enrich_phone_number": false,
  "enrich_profile": false,
  "verify_catch_all": false,
  "webhook": "https://example.com/bettercontact/results",
  "push_contact_individually": false,
  "contact_webhook": "<string>",
  "process_flow": "<string>",
  "timeout_seconds": 240
}
'

import requests

url = "https://app.bettercontact.rocks/api/v2/async"

payload = {
    "data": [
        {
            "first_name": "Elon",
            "last_name": "Musk",
            "company": "Tesla",
            "company_domain": "tesla.com",
            "linkedin_url": "https://www.linkedin.com/in/elonmusk",
            "custom_fields": {
                "uuid": "crm-8821",
                "list_name": "Q3 outbound"
            }
        }
    ],
    "enrich_email_address": True,
    "enrich_phone_number": False,
    "enrich_profile": False,
    "verify_catch_all": False,
    "webhook": "https://example.com/bettercontact/results",
    "push_contact_individually": False,
    "contact_webhook": "<string>",
    "process_flow": "<string>",
    "timeout_seconds": 240
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    data: [
      {
        first_name: 'Elon',
        last_name: 'Musk',
        company: 'Tesla',
        company_domain: 'tesla.com',
        linkedin_url: 'https://www.linkedin.com/in/elonmusk',
        custom_fields: {uuid: 'crm-8821', list_name: 'Q3 outbound'}
      }
    ],
    enrich_email_address: true,
    enrich_phone_number: false,
    enrich_profile: false,
    verify_catch_all: false,
    webhook: 'https://example.com/bettercontact/results',
    push_contact_individually: false,
    contact_webhook: '<string>',
    process_flow: '<string>',
    timeout_seconds: 240
  })
};

fetch('https://app.bettercontact.rocks/api/v2/async', 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://app.bettercontact.rocks/api/v2/async",
  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([
    'data' => [
        [
                'first_name' => 'Elon',
                'last_name' => 'Musk',
                'company' => 'Tesla',
                'company_domain' => 'tesla.com',
                'linkedin_url' => 'https://www.linkedin.com/in/elonmusk',
                'custom_fields' => [
                                'uuid' => 'crm-8821',
                                'list_name' => 'Q3 outbound'
                ]
        ]
    ],
    'enrich_email_address' => true,
    'enrich_phone_number' => false,
    'enrich_profile' => false,
    'verify_catch_all' => false,
    'webhook' => 'https://example.com/bettercontact/results',
    'push_contact_individually' => false,
    'contact_webhook' => '<string>',
    'process_flow' => '<string>',
    'timeout_seconds' => 240
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-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://app.bettercontact.rocks/api/v2/async"

	payload := strings.NewReader("{\n  \"data\": [\n    {\n      \"first_name\": \"Elon\",\n      \"last_name\": \"Musk\",\n      \"company\": \"Tesla\",\n      \"company_domain\": \"tesla.com\",\n      \"linkedin_url\": \"https://www.linkedin.com/in/elonmusk\",\n      \"custom_fields\": {\n        \"uuid\": \"crm-8821\",\n        \"list_name\": \"Q3 outbound\"\n      }\n    }\n  ],\n  \"enrich_email_address\": true,\n  \"enrich_phone_number\": false,\n  \"enrich_profile\": false,\n  \"verify_catch_all\": false,\n  \"webhook\": \"https://example.com/bettercontact/results\",\n  \"push_contact_individually\": false,\n  \"contact_webhook\": \"<string>\",\n  \"process_flow\": \"<string>\",\n  \"timeout_seconds\": 240\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-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://app.bettercontact.rocks/api/v2/async")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"data\": [\n    {\n      \"first_name\": \"Elon\",\n      \"last_name\": \"Musk\",\n      \"company\": \"Tesla\",\n      \"company_domain\": \"tesla.com\",\n      \"linkedin_url\": \"https://www.linkedin.com/in/elonmusk\",\n      \"custom_fields\": {\n        \"uuid\": \"crm-8821\",\n        \"list_name\": \"Q3 outbound\"\n      }\n    }\n  ],\n  \"enrich_email_address\": true,\n  \"enrich_phone_number\": false,\n  \"enrich_profile\": false,\n  \"verify_catch_all\": false,\n  \"webhook\": \"https://example.com/bettercontact/results\",\n  \"push_contact_individually\": false,\n  \"contact_webhook\": \"<string>\",\n  \"process_flow\": \"<string>\",\n  \"timeout_seconds\": 240\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.bettercontact.rocks/api/v2/async")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"data\": [\n    {\n      \"first_name\": \"Elon\",\n      \"last_name\": \"Musk\",\n      \"company\": \"Tesla\",\n      \"company_domain\": \"tesla.com\",\n      \"linkedin_url\": \"https://www.linkedin.com/in/elonmusk\",\n      \"custom_fields\": {\n        \"uuid\": \"crm-8821\",\n        \"list_name\": \"Q3 outbound\"\n      }\n    }\n  ],\n  \"enrich_email_address\": true,\n  \"enrich_phone_number\": false,\n  \"enrich_profile\": false,\n  \"verify_catch_all\": false,\n  \"webhook\": \"https://example.com/bettercontact/results\",\n  \"push_contact_individually\": false,\n  \"contact_webhook\": \"<string>\",\n  \"process_flow\": \"<string>\",\n  \"timeout_seconds\": 240\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "id": "your-request-id",
  "message": "Processing..."
}

{
  "success": false,
  "error": "Bad request. Please check documentation"
}

{
  "success": false,
  "error": "Your are not authorized. Please check your api_key."
}

{
  "success": false,
  "message": "You ran out of credits"
}

{
  "success": false,
  "error": "An error occured"
}

POST

async

Enrich leads

curl --request POST \
  --url https://app.bettercontact.rocks/api/v2/async \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "data": [
    {
      "first_name": "Elon",
      "last_name": "Musk",
      "company": "Tesla",
      "company_domain": "tesla.com",
      "linkedin_url": "https://www.linkedin.com/in/elonmusk",
      "custom_fields": {
        "uuid": "crm-8821",
        "list_name": "Q3 outbound"
      }
    }
  ],
  "enrich_email_address": true,
  "enrich_phone_number": false,
  "enrich_profile": false,
  "verify_catch_all": false,
  "webhook": "https://example.com/bettercontact/results",
  "push_contact_individually": false,
  "contact_webhook": "<string>",
  "process_flow": "<string>",
  "timeout_seconds": 240
}
'

import requests

url = "https://app.bettercontact.rocks/api/v2/async"

payload = {
    "data": [
        {
            "first_name": "Elon",
            "last_name": "Musk",
            "company": "Tesla",
            "company_domain": "tesla.com",
            "linkedin_url": "https://www.linkedin.com/in/elonmusk",
            "custom_fields": {
                "uuid": "crm-8821",
                "list_name": "Q3 outbound"
            }
        }
    ],
    "enrich_email_address": True,
    "enrich_phone_number": False,
    "enrich_profile": False,
    "verify_catch_all": False,
    "webhook": "https://example.com/bettercontact/results",
    "push_contact_individually": False,
    "contact_webhook": "<string>",
    "process_flow": "<string>",
    "timeout_seconds": 240
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    data: [
      {
        first_name: 'Elon',
        last_name: 'Musk',
        company: 'Tesla',
        company_domain: 'tesla.com',
        linkedin_url: 'https://www.linkedin.com/in/elonmusk',
        custom_fields: {uuid: 'crm-8821', list_name: 'Q3 outbound'}
      }
    ],
    enrich_email_address: true,
    enrich_phone_number: false,
    enrich_profile: false,
    verify_catch_all: false,
    webhook: 'https://example.com/bettercontact/results',
    push_contact_individually: false,
    contact_webhook: '<string>',
    process_flow: '<string>',
    timeout_seconds: 240
  })
};

fetch('https://app.bettercontact.rocks/api/v2/async', 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://app.bettercontact.rocks/api/v2/async",
  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([
    'data' => [
        [
                'first_name' => 'Elon',
                'last_name' => 'Musk',
                'company' => 'Tesla',
                'company_domain' => 'tesla.com',
                'linkedin_url' => 'https://www.linkedin.com/in/elonmusk',
                'custom_fields' => [
                                'uuid' => 'crm-8821',
                                'list_name' => 'Q3 outbound'
                ]
        ]
    ],
    'enrich_email_address' => true,
    'enrich_phone_number' => false,
    'enrich_profile' => false,
    'verify_catch_all' => false,
    'webhook' => 'https://example.com/bettercontact/results',
    'push_contact_individually' => false,
    'contact_webhook' => '<string>',
    'process_flow' => '<string>',
    'timeout_seconds' => 240
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-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://app.bettercontact.rocks/api/v2/async"

	payload := strings.NewReader("{\n  \"data\": [\n    {\n      \"first_name\": \"Elon\",\n      \"last_name\": \"Musk\",\n      \"company\": \"Tesla\",\n      \"company_domain\": \"tesla.com\",\n      \"linkedin_url\": \"https://www.linkedin.com/in/elonmusk\",\n      \"custom_fields\": {\n        \"uuid\": \"crm-8821\",\n        \"list_name\": \"Q3 outbound\"\n      }\n    }\n  ],\n  \"enrich_email_address\": true,\n  \"enrich_phone_number\": false,\n  \"enrich_profile\": false,\n  \"verify_catch_all\": false,\n  \"webhook\": \"https://example.com/bettercontact/results\",\n  \"push_contact_individually\": false,\n  \"contact_webhook\": \"<string>\",\n  \"process_flow\": \"<string>\",\n  \"timeout_seconds\": 240\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-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://app.bettercontact.rocks/api/v2/async")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"data\": [\n    {\n      \"first_name\": \"Elon\",\n      \"last_name\": \"Musk\",\n      \"company\": \"Tesla\",\n      \"company_domain\": \"tesla.com\",\n      \"linkedin_url\": \"https://www.linkedin.com/in/elonmusk\",\n      \"custom_fields\": {\n        \"uuid\": \"crm-8821\",\n        \"list_name\": \"Q3 outbound\"\n      }\n    }\n  ],\n  \"enrich_email_address\": true,\n  \"enrich_phone_number\": false,\n  \"enrich_profile\": false,\n  \"verify_catch_all\": false,\n  \"webhook\": \"https://example.com/bettercontact/results\",\n  \"push_contact_individually\": false,\n  \"contact_webhook\": \"<string>\",\n  \"process_flow\": \"<string>\",\n  \"timeout_seconds\": 240\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.bettercontact.rocks/api/v2/async")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"data\": [\n    {\n      \"first_name\": \"Elon\",\n      \"last_name\": \"Musk\",\n      \"company\": \"Tesla\",\n      \"company_domain\": \"tesla.com\",\n      \"linkedin_url\": \"https://www.linkedin.com/in/elonmusk\",\n      \"custom_fields\": {\n        \"uuid\": \"crm-8821\",\n        \"list_name\": \"Q3 outbound\"\n      }\n    }\n  ],\n  \"enrich_email_address\": true,\n  \"enrich_phone_number\": false,\n  \"enrich_profile\": false,\n  \"verify_catch_all\": false,\n  \"webhook\": \"https://example.com/bettercontact/results\",\n  \"push_contact_individually\": false,\n  \"contact_webhook\": \"<string>\",\n  \"process_flow\": \"<string>\",\n  \"timeout_seconds\": 240\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "id": "your-request-id",
  "message": "Processing..."
}

{
  "success": false,
  "error": "Bad request. Please check documentation"
}

{
  "success": false,
  "error": "Your are not authorized. Please check your api_key."
}

{
  "success": false,
  "message": "You ran out of credits"
}

{
  "success": false,
  "error": "An error occured"
}

Provide first_name, last_name and either company or company_domain. company_domain gives materially better results than a company name. Add linkedin_url whenever you have it, and always when you request enrich_phone_number.

This endpoint is asynchronous. A 201 means the batch was accepted, not that it was enriched. Keep the returned id and read Request statuses before you build your polling loop.Submissions are not idempotent: retrying a POST that had actually succeeded enriches the same leads twice and consumes credits twice.

Anything you put in custom_fields comes back untouched in the results, which is the simplest way to reconcile enriched leads with your own records.

Authorizations

X-API-Key

string

header

required

Body

application/json

Data to enrich

data

object[]

required

Leads to enrich. Between 1 and 100 per call. Sending more than 100 is rejected with 400.

Required array length: 1 - 100 elements

Show child attributes

enrich_email_address

boolean

default:true

Enrich the work email address. When enrich_email_address, enrich_phone_number and enrich_profile are all omitted or false, email enrichment is applied by default.

enrich_phone_number

boolean

default:false

Enrich the mobile phone number. Requires the phone add-on on your plan, otherwise the call is rejected with 402. Provide linkedin_url for best results.

enrich_profile

boolean

default:false

Enrich the full LinkedIn profile of the contact (headline, seniority, location, current company). Requires linkedin_url.

verify_catch_all

boolean

default:false

Run the extra catch-all verification layer. When enabled, contact_email_address_status returns catch_all_safe / catch_all_not_safe instead of catch_all. Requires the catch-all add-on on your plan, otherwise the call is rejected with 402.

webhook

string<uri>

URL that receives the full result payload as soon as the whole batch is done. Recommended over polling. See Webhooks.

Example:

"https://example.com/bettercontact/results"

push_contact_individually

boolean

default:false

When true, each lead is pushed to contact_webhook as soon as it is enriched, instead of waiting for the whole batch. Useful for batches of 100.

contact_webhook

string<uri>

URL that receives one payload per lead. Only used when push_contact_individually is true.

process_flow

string

Identifier of the process flow to use for this enrichment. Only for accounts subscribed to the process flow add-on.

timeout_seconds

integer

Maximum time the waterfall is allowed to run before the request is terminated with whatever has been found. Defaults to the timeout configured on your account.

Required range: x >= 1

Example:

240

Response

Enrichment request accepted. Poll GET /async/{request_id} or wait for the webhook.

success

boolean

Example:

true

string

Example:

"your-request-id"

message

string

Example:

"Processing..."

Get Started

Using the API

Lead Finder - Get new leads

Waterfall enrichment - Get phone and email

Enrich Profile

My account

Enrich leads

Authorizations

Body

Response