Enrich leads

Changed on Nov 3, 2026

Submit between 1 and 100 leads for waterfall email and phone enrichment.

This endpoint is asynchronous: it answers immediately with a id (the request_id) and enriches in the background. Retrieve the results with GET /async/{request_id}, or provide a webhook to have them pushed to you.

post/async

Request

Base URL
https://app.bettercontact.rocks/api/v2
URL
https://app.bettercontact.rocks/api/v2/async
Auth
API key in header X-API-Key

Request body

enrich_email_addressboolean

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_numberboolean

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_profileboolean

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

verify_catch_allboolean

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.

webhookstring uri

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

push_contact_individuallyboolean

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_webhookstring uri

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

process_flowstring

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

timeout_secondsinteger

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.

Example request

{
  "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"
      }
    }
  ],
  "webhook": "https://example.com/bettercontact/results",
  "timeout_seconds": 240
}

Response

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

successboolean

idstring

messagestring

Example response

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

Changes

Nov 3, 2026cd9044a26697 Revision changes
- breaking
  the request property's minItems was increased to 1
- breaking
  the request property format changed from no format to uri
- info
  api operation id createEnrichment was added
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  the request property // became optional
- info
  the request property became optional
- info
  the request property became optional
- info
  the request property default value true was added
- info
  the request property default value false was added
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the optional property to the response with the status

Operation history