Start Contacts Enrichment

curl --request POST \
  --url https://api.preceptai.co.uk/v1/leads/enrich \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Q3 Lead List",
  "webhookUrl": "https://your-site.com/webhook",
  "leads": [
    {
      "linkedinUrl": "https://linkedin.com/in/johndoe",
      "enrichType": [
        "emails",
        "phones"
      ],
      "customData": {
        "contact_id": "lead_123"
      }
    },
    {
      "firstName": "Jane",
      "lastName": "Smith",
      "companyName": "Precept AI",
      "enrichType": [
        "emails"
      ],
      "customData": {
        "contact_id": "lead_456"
      }
    }
  ],
  "includeContactDetails": true
}
'

import requests

url = "https://api.preceptai.co.uk/v1/leads/enrich"

payload = {
    "name": "Q3 Lead List",
    "webhookUrl": "https://your-site.com/webhook",
    "leads": [
        {
            "linkedinUrl": "https://linkedin.com/in/johndoe",
            "enrichType": ["emails", "phones"],
            "customData": { "contact_id": "lead_123" }
        },
        {
            "firstName": "Jane",
            "lastName": "Smith",
            "companyName": "Precept AI",
            "enrichType": ["emails"],
            "customData": { "contact_id": "lead_456" }
        }
    ],
    "includeContactDetails": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Q3 Lead List',
    webhookUrl: 'https://your-site.com/webhook',
    leads: [
      {
        linkedinUrl: 'https://linkedin.com/in/johndoe',
        enrichType: ['emails', 'phones'],
        customData: {contact_id: 'lead_123'}
      },
      {
        firstName: 'Jane',
        lastName: 'Smith',
        companyName: 'Precept AI',
        enrichType: ['emails'],
        customData: {contact_id: 'lead_456'}
      }
    ],
    includeContactDetails: true
  })
};

fetch('https://api.preceptai.co.uk/v1/leads/enrich', 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.preceptai.co.uk/v1/leads/enrich",
  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([
    'name' => 'Q3 Lead List',
    'webhookUrl' => 'https://your-site.com/webhook',
    'leads' => [
        [
                'linkedinUrl' => 'https://linkedin.com/in/johndoe',
                'enrichType' => [
                                'emails',
                                'phones'
                ],
                'customData' => [
                                'contact_id' => 'lead_123'
                ]
        ],
        [
                'firstName' => 'Jane',
                'lastName' => 'Smith',
                'companyName' => 'Precept AI',
                'enrichType' => [
                                'emails'
                ],
                'customData' => [
                                'contact_id' => 'lead_456'
                ]
        ]
    ],
    'includeContactDetails' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.preceptai.co.uk/v1/leads/enrich"

	payload := strings.NewReader("{\n  \"name\": \"Q3 Lead List\",\n  \"webhookUrl\": \"https://your-site.com/webhook\",\n  \"leads\": [\n    {\n      \"linkedinUrl\": \"https://linkedin.com/in/johndoe\",\n      \"enrichType\": [\n        \"emails\",\n        \"phones\"\n      ],\n      \"customData\": {\n        \"contact_id\": \"lead_123\"\n      }\n    },\n    {\n      \"firstName\": \"Jane\",\n      \"lastName\": \"Smith\",\n      \"companyName\": \"Precept AI\",\n      \"enrichType\": [\n        \"emails\"\n      ],\n      \"customData\": {\n        \"contact_id\": \"lead_456\"\n      }\n    }\n  ],\n  \"includeContactDetails\": true\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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.preceptai.co.uk/v1/leads/enrich")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Q3 Lead List\",\n  \"webhookUrl\": \"https://your-site.com/webhook\",\n  \"leads\": [\n    {\n      \"linkedinUrl\": \"https://linkedin.com/in/johndoe\",\n      \"enrichType\": [\n        \"emails\",\n        \"phones\"\n      ],\n      \"customData\": {\n        \"contact_id\": \"lead_123\"\n      }\n    },\n    {\n      \"firstName\": \"Jane\",\n      \"lastName\": \"Smith\",\n      \"companyName\": \"Precept AI\",\n      \"enrichType\": [\n        \"emails\"\n      ],\n      \"customData\": {\n        \"contact_id\": \"lead_456\"\n      }\n    }\n  ],\n  \"includeContactDetails\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.preceptai.co.uk/v1/leads/enrich")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Q3 Lead List\",\n  \"webhookUrl\": \"https://your-site.com/webhook\",\n  \"leads\": [\n    {\n      \"linkedinUrl\": \"https://linkedin.com/in/johndoe\",\n      \"enrichType\": [\n        \"emails\",\n        \"phones\"\n      ],\n      \"customData\": {\n        \"contact_id\": \"lead_123\"\n      }\n    },\n    {\n      \"firstName\": \"Jane\",\n      \"lastName\": \"Smith\",\n      \"companyName\": \"Precept AI\",\n      \"enrichType\": [\n        \"emails\"\n      ],\n      \"customData\": {\n        \"contact_id\": \"lead_456\"\n      }\n    }\n  ],\n  \"includeContactDetails\": true\n}"

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

{
  "message": "Enrichment job successfully created and batches are being processed.",
  "enrichment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "error": "Bad Request",
  "message": "Invalid input, please check the documentation."
}

{
  "message": "Not enough credits to start enrichment. Please upgrade your plan to start enrichment."
}

{
  "error": "Internal server error."
}

Leads

Start Contacts Enrichment

Enrich your contacts using this endpoint.

This endpoint enriches a list of contacts with contact details and Personalized AI insights:

Verified email addresses.
Verified phone numbers.
Professional summary.
Top problems.
Internal strategic initiatives.
Public appearances.

To enrich a contact, you can provide either their LinkedIn profile URL or a combination of their first name, last name, and company name/domain. You can process up to 1,000 contacts in a single request.

To associate your own internal identifiers with each lead, use the customData field. This data will be returned to you in the webhook response, allowing you to easily map the enrichment results back to your system.

To receive the results, you must provide a webhookUrl.

POST

leads

enrich

Start Contacts Enrichment

curl --request POST \
  --url https://api.preceptai.co.uk/v1/leads/enrich \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Q3 Lead List",
  "webhookUrl": "https://your-site.com/webhook",
  "leads": [
    {
      "linkedinUrl": "https://linkedin.com/in/johndoe",
      "enrichType": [
        "emails",
        "phones"
      ],
      "customData": {
        "contact_id": "lead_123"
      }
    },
    {
      "firstName": "Jane",
      "lastName": "Smith",
      "companyName": "Precept AI",
      "enrichType": [
        "emails"
      ],
      "customData": {
        "contact_id": "lead_456"
      }
    }
  ],
  "includeContactDetails": true
}
'

import requests

url = "https://api.preceptai.co.uk/v1/leads/enrich"

payload = {
    "name": "Q3 Lead List",
    "webhookUrl": "https://your-site.com/webhook",
    "leads": [
        {
            "linkedinUrl": "https://linkedin.com/in/johndoe",
            "enrichType": ["emails", "phones"],
            "customData": { "contact_id": "lead_123" }
        },
        {
            "firstName": "Jane",
            "lastName": "Smith",
            "companyName": "Precept AI",
            "enrichType": ["emails"],
            "customData": { "contact_id": "lead_456" }
        }
    ],
    "includeContactDetails": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Q3 Lead List',
    webhookUrl: 'https://your-site.com/webhook',
    leads: [
      {
        linkedinUrl: 'https://linkedin.com/in/johndoe',
        enrichType: ['emails', 'phones'],
        customData: {contact_id: 'lead_123'}
      },
      {
        firstName: 'Jane',
        lastName: 'Smith',
        companyName: 'Precept AI',
        enrichType: ['emails'],
        customData: {contact_id: 'lead_456'}
      }
    ],
    includeContactDetails: true
  })
};

fetch('https://api.preceptai.co.uk/v1/leads/enrich', 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.preceptai.co.uk/v1/leads/enrich",
  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([
    'name' => 'Q3 Lead List',
    'webhookUrl' => 'https://your-site.com/webhook',
    'leads' => [
        [
                'linkedinUrl' => 'https://linkedin.com/in/johndoe',
                'enrichType' => [
                                'emails',
                                'phones'
                ],
                'customData' => [
                                'contact_id' => 'lead_123'
                ]
        ],
        [
                'firstName' => 'Jane',
                'lastName' => 'Smith',
                'companyName' => 'Precept AI',
                'enrichType' => [
                                'emails'
                ],
                'customData' => [
                                'contact_id' => 'lead_456'
                ]
        ]
    ],
    'includeContactDetails' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.preceptai.co.uk/v1/leads/enrich"

	payload := strings.NewReader("{\n  \"name\": \"Q3 Lead List\",\n  \"webhookUrl\": \"https://your-site.com/webhook\",\n  \"leads\": [\n    {\n      \"linkedinUrl\": \"https://linkedin.com/in/johndoe\",\n      \"enrichType\": [\n        \"emails\",\n        \"phones\"\n      ],\n      \"customData\": {\n        \"contact_id\": \"lead_123\"\n      }\n    },\n    {\n      \"firstName\": \"Jane\",\n      \"lastName\": \"Smith\",\n      \"companyName\": \"Precept AI\",\n      \"enrichType\": [\n        \"emails\"\n      ],\n      \"customData\": {\n        \"contact_id\": \"lead_456\"\n      }\n    }\n  ],\n  \"includeContactDetails\": true\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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.preceptai.co.uk/v1/leads/enrich")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Q3 Lead List\",\n  \"webhookUrl\": \"https://your-site.com/webhook\",\n  \"leads\": [\n    {\n      \"linkedinUrl\": \"https://linkedin.com/in/johndoe\",\n      \"enrichType\": [\n        \"emails\",\n        \"phones\"\n      ],\n      \"customData\": {\n        \"contact_id\": \"lead_123\"\n      }\n    },\n    {\n      \"firstName\": \"Jane\",\n      \"lastName\": \"Smith\",\n      \"companyName\": \"Precept AI\",\n      \"enrichType\": [\n        \"emails\"\n      ],\n      \"customData\": {\n        \"contact_id\": \"lead_456\"\n      }\n    }\n  ],\n  \"includeContactDetails\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.preceptai.co.uk/v1/leads/enrich")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Q3 Lead List\",\n  \"webhookUrl\": \"https://your-site.com/webhook\",\n  \"leads\": [\n    {\n      \"linkedinUrl\": \"https://linkedin.com/in/johndoe\",\n      \"enrichType\": [\n        \"emails\",\n        \"phones\"\n      ],\n      \"customData\": {\n        \"contact_id\": \"lead_123\"\n      }\n    },\n    {\n      \"firstName\": \"Jane\",\n      \"lastName\": \"Smith\",\n      \"companyName\": \"Precept AI\",\n      \"enrichType\": [\n        \"emails\"\n      ],\n      \"customData\": {\n        \"contact_id\": \"lead_456\"\n      }\n    }\n  ],\n  \"includeContactDetails\": true\n}"

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

{
  "message": "Enrichment job successfully created and batches are being processed.",
  "enrichment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "error": "Bad Request",
  "message": "Invalid input, please check the documentation."
}

{
  "message": "Not enough credits to start enrichment. Please upgrade your plan to start enrichment."
}

{
  "error": "Internal server error."
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

leads

object[]

required

An array of lead objects to enrich. Each object must contain either a linkedinUrl or a combination of firstName, lastName, and companyName or companyDomain.

Show child attributes

name

string

A readable name for your enrichment for searching on your dashboard.

webhookUrl

string<uri>

Optional. Your webhook URL to receive the result of the enrichment. If not provided, you can poll the GET /v1/jobs/{jobId} endpoint.

includeContactDetails

boolean

Whether to include contact details (email and phone) for the enriched leads. If true, the webhook results will map back these fields as enrichEmail and enrichPhone.

translate

boolean

This should be set to true if the lead names are not in English. This is needed for non english names to ensure the most accurate contact details are returned. The names will be translated to English before enriching them.

streamingResults

boolean

Optional. When true and a webhookUrl is provided, contact results are progressively streamed in real-time as each lead is enriched (with status: "in_progress"), followed by a final completion webhook when all leads finish.

Response

Request accepted. The enrichment is in progress. The response will vary based on whether all leads could be processed.

Option 1
Option 2

message

string

Example:

"Enrichment job successfully created and batches are being processed."

enrichment_id

string<uuid>

Getting Started

Essentials

Integrations

API Reference

Start Contacts Enrichment

Authorizations

Body

Response