API — Enrichment

Bulk Enrichment with Deep Enrich API

Easily enrich multiple contacts at once using this endpoint.

Requirements for Enrichment

To successfully enrich a contact, provide at least:

  • First Name
  • Last Name
  • Company Name or Domain
  • (Optional) LinkedIn URL – Enhances email and phone discovery.

Batch Processing: Enrich up to 100 contacts per request.

Single Contact: Simply submit one entry within the list.

Tracking via Dashboard

All enrichment requests made through the API are visible in your Deep Enrich dashboard.
Tip: Assign a clear name to each request for easier tracking. Example: Use "John_Doe_Sales_Team" instead of generic names.

Using Custom Fields

Enhance data management by passing custom properties as objects.

Example: If enriching contacts from a marketing tool, include the tool’s lead_ID in the custom field.

Important: Ensure all custom values are strings (numeric values may cause errors).

Fetching Enrichment Results

Choose one of the following methods to retrieve results:

  • Webhook (Recommended): Get results automatically when enrichment is complete.
  • GET /bulk/enrichment_id (Less Preferred): Manually check status until results are available.

How Webhooks Work

Webhook Notifications in Deep Enrich API

Your webhook URL will receive a POST request in the following cases:

  • Enrichment is completed – The process has successfully finished.
  • Insufficient credits – The request couldn't proceed due to low balance.
  • Enrichment canceled – The request was manually or automatically stopped.
Webhook Reliability & Retries
  • If the webhook fails (returns a non-2xx status code), Deep Enrich retries every minute, up to five times.
  • The response format mirrors the output of the GET /bulk/enrichment_id endpoint, ensuring consistency.
Authorization & Request Body Format

To access the Deep Enrich API, include a Bearer authentication header:

  • Authorization: Bearer < your_api_key > (Replace < your_api_key > with your actual API key.)

Request Body (JSON Format)

  • name (string) [Required]
    A descriptive name for the enrichment request.
    Example: "Marketing Leads - Q3 Campaign"
  • datas (object[]) [Required]
    A list of contacts to be enriched.
  • webhook_url (string) [Optional]
    Provide a Webhook URL to receive enrichment results automatically.
    Example: "https://yourdomain.com/api/enrichment-callback"
Response: 200 OK (Request Successful)

When your request is successfully processed, the API returns a 200 OK response with the following field:

  • enrichment_id (string) – A unique identifier assigned to the enrichment request.

Example Response:

							
							{
							   "enrichment_id": "a1b2c3d4-5678-90ef-gh12-ijkl345678mn"
							}
						

 

 

 

										
										curl --request POST \
										  --url https://app.Deepenrich.com/api/v1/contact/enrich/bulk \
										  --header 'Authorization: Bearer ' \
										  --header 'Content-Type: application/json' \
										  --data '{
										  "name": "Sales Operations in London",
										  "webhook_url": "https://example.com/webhook",
										  "datas": [
										    {
										      "firstname": "john",
										      "lastname": "snow",
										      "domain": "example.com",
										      "company_name": "example inc",
										      "linkedin_url": "https://www.linkedin.com/in/demoge/",
										      "enrich_fields": [
										        "contact.emails",
										        "contact.phones"
										      ],
										      "custom": {
										        "user_id": "12584"
										      }
										    }
										  ]
										}'
										
									
										
										import requests
										url = "https://app.Deepenrich.com/api/v1/contact/enrich/bulk"
										payload = {
										    "name": "Sales Operations in London",
										    "webhook_url": "https://example.com/webhook",
										    "datas": [
										        {
										            "firstname": "john",
										            "lastname": "snow",
										            "domain": "example.com",
										            "company_name": "example inc",
										            "linkedin_url": "https://www.linkedin.com/in/demoge/",
										            "enrich_fields": ["contact.emails", "contact.phones"],
										            "custom": {"user_id": "12584"}
										        }
										    ]
										}
										headers = {
										    "Authorization": "Bearer ",
										    "Content-Type": "application/json"
										}
										response = requests.request("POST", url, json=payload, headers=headers)
										print(response.text)
										
									
										
										const options = {
										  method: 'POST',
										  headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'},
										  body: '{"name":"Sales Operations in London","webhook_url":"https://example.com/webhook","datas":[{"firstname":"john","lastname":"snow","domain":"example.com","company_name":"example inc","linkedin_url":"https://www.linkedin.com/in/demoge/","enrich_fields":["contact.emails","contact.phones"],"custom":{"user_id":"12584"}}]}'
										};
										fetch('https://app.Deepenrich.com/api/v1/contact/enrich/bulk', options)
										  .then(response => response.json())
										  .then(response => console.log(response))
										  .catch(err => console.error(err));
										
									
										
										<?php 
										$curl = curl_init();
										curl_setopt_array($curl, [
										  CURLOPT_URL => "https://app.deepenrich.com/api/v1/contact/enrich/bulk",
										  CURLOPT_RETURNTRANSFER => true,
										  CURLOPT_ENCODING => "",
										  CURLOPT_MAXREDIRS => 10,
										  CURLOPT_TIMEOUT => 30,
										  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
										  CURLOPT_CUSTOMREQUEST => "POST",
										  CURLOPT_POSTFIELDS => "{\n  \"name\": \"Sales Operations in London\",\n  \"webhook_url\": \"https://example.com/webhook\",\n  \"datas\": [\n    {\n      \"firstname\": \"john\",\n      \"lastname\": \"snow\",\n      \"domain\": \"example.com\",\n      \"company_name\": \"example inc\",\n      \"linkedin_url\": \"https://www.linkedin.com/in/demoge/\",\n      \"enrich_fields\": [\n        \"contact.emails\",\n        \"contact.phones\"\n      ],\n      \"custom\": {\n        \"user_id\": \"12584\"\n      }\n    }\n  ]\n}",
										  CURLOPT_HTTPHEADER => [
										    "Authorization: Bearer ",
										    "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/ioutil"
										)
										func main() {
										url := "https://app.Deepenrich.com/api/v1/contact/enrich/bulk"
										payload := strings.NewReader("{\n  \"name\": \"Sales Operations in London\",\n  \"webhook_url\": \"https://example.com/webhook\",\n  \"datas\": [\n    {\n      \"firstname\": \"john\",\n      \"lastname\": \"snow\",\n      \"domain\": \"example.com\",\n      \"company_name\": \"example inc\",\n      \"linkedin_url\": \"https://www.linkedin.com/in/demoge/\",\n      \"enrich_fields\": [\n        \"contact.emails\",\n        \"contact.phones\"\n      ],\n      \"custom\": {\n        \"user_id\": \"12584\"\n      }\n    }\n  ]\n}")
										req, _ := http.NewRequest("POST", url, payload)
										req.Header.Add("Authorization", "Bearer ")
										req.Header.Add("Content-Type", "application/json")
										res, _ := http.DefaultClient.Do(req)
										defer res.Body.Close()
										body, _ := ioutil.ReadAll(res.Body)
										fmt.Println(res)
										fmt.Println(string(body))
										}
										
									
										
										HttpResponse response = Unirest.post("https://app.Deepenrich.com/api/v1/contact/enrich/bulk")
										  .header("Authorization", "Bearer ")
										  .header("Content-Type", "application/json")
										  .body("{\n  \"name\": \"Sales Operations in London\",\n  \"webhook_url\": \"https://example.com/webhook\",\n  \"datas\": [\n    {\n      \"firstname\": \"john\",\n      \"lastname\": \"snow\",\n      \"domain\": \"example.com\",\n      \"company_name\": \"example inc\",\n      \"linkedin_url\": \"https://www.linkedin.com/in/demoge/\",\n      \"enrich_fields\": [\n        \"contact.emails\",\n        \"contact.phones\"\n      ],\n      \"custom\": {\n        \"user_id\": \"12584\"\n      }\n    }\n  ]\n}")
										  .asString();
										
									
example
										
											{
											  "workspace_id": ""
											}
										
									
												
													{
													  "code": "error.authorization.not_set",
													  "message": "Authorization headers not set"
													}
												
											
												
													{
													  "code": "error.authorization.not_bearer",
													  "message": "Authorization headers not have prefix 'bearer'"
													}
												
											
												
													{
													  "code": "error.api.key",
													  "message": "Unknown api key"
													}
												
											
										This response does not have an example.