Skip to main content
POST
/
contacts
/
bulk_enrich
Enrich multiple contacts
curl --request POST \
  --url https://app.pipecorn.com/api/v2/contacts/bulk_enrich \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "contacts": [
    {
      "firstname": "Mathieu",
      "lastname": "Brun-Picard",
      "domain": "pipecorn.com",
      "company_name": "Pipecorn",
      "linkedin_url": "https://www.linkedin.com/in/mathieu-brun-picard/",
      "custom": {
        "hubspot_id": "4447901"
      }
    },
    {
      "firstname": "Nicolas",
      "lastname": "Fernandez-Le Follic",
      "domain": "pipecorn.com",
      "company_name": "Pipecorn",
      "linkedin_url": "https://www.linkedin.com/in/nicolasfernandezlefollic/",
      "custom": {
        "hubspot_id": "4447902"
      }
    }
  ],
  "webhook_url": "https://webhook.site/8b53c96f-f2cd-4c24-bc09-b3c2176d7ea8",
  "enrichment_type": [
    "email"
  ]
}
'
import requests

url = "https://app.pipecorn.com/api/v2/contacts/bulk_enrich"

payload = {
    "contacts": [
        {
            "firstname": "Mathieu",
            "lastname": "Brun-Picard",
            "domain": "pipecorn.com",
            "company_name": "Pipecorn",
            "linkedin_url": "https://www.linkedin.com/in/mathieu-brun-picard/",
            "custom": { "hubspot_id": "4447901" }
        },
        {
            "firstname": "Nicolas",
            "lastname": "Fernandez-Le Follic",
            "domain": "pipecorn.com",
            "company_name": "Pipecorn",
            "linkedin_url": "https://www.linkedin.com/in/nicolasfernandezlefollic/",
            "custom": { "hubspot_id": "4447902" }
        }
    ],
    "webhook_url": "https://webhook.site/8b53c96f-f2cd-4c24-bc09-b3c2176d7ea8",
    "enrichment_type": ["email"]
}
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({
    contacts: [
      {
        firstname: 'Mathieu',
        lastname: 'Brun-Picard',
        domain: 'pipecorn.com',
        company_name: 'Pipecorn',
        linkedin_url: 'https://www.linkedin.com/in/mathieu-brun-picard/',
        custom: {hubspot_id: '4447901'}
      },
      {
        firstname: 'Nicolas',
        lastname: 'Fernandez-Le Follic',
        domain: 'pipecorn.com',
        company_name: 'Pipecorn',
        linkedin_url: 'https://www.linkedin.com/in/nicolasfernandezlefollic/',
        custom: {hubspot_id: '4447902'}
      }
    ],
    webhook_url: 'https://webhook.site/8b53c96f-f2cd-4c24-bc09-b3c2176d7ea8',
    enrichment_type: ['email']
  })
};

fetch('https://app.pipecorn.com/api/v2/contacts/bulk_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://app.pipecorn.com/api/v2/contacts/bulk_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([
    'contacts' => [
        [
                'firstname' => 'Mathieu',
                'lastname' => 'Brun-Picard',
                'domain' => 'pipecorn.com',
                'company_name' => 'Pipecorn',
                'linkedin_url' => 'https://www.linkedin.com/in/mathieu-brun-picard/',
                'custom' => [
                                'hubspot_id' => '4447901'
                ]
        ],
        [
                'firstname' => 'Nicolas',
                'lastname' => 'Fernandez-Le Follic',
                'domain' => 'pipecorn.com',
                'company_name' => 'Pipecorn',
                'linkedin_url' => 'https://www.linkedin.com/in/nicolasfernandezlefollic/',
                'custom' => [
                                'hubspot_id' => '4447902'
                ]
        ]
    ],
    'webhook_url' => 'https://webhook.site/8b53c96f-f2cd-4c24-bc09-b3c2176d7ea8',
    'enrichment_type' => [
        'email'
    ]
  ]),
  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.pipecorn.com/api/v2/contacts/bulk_enrich"

	payload := strings.NewReader("{\n  \"contacts\": [\n    {\n      \"firstname\": \"Mathieu\",\n      \"lastname\": \"Brun-Picard\",\n      \"domain\": \"pipecorn.com\",\n      \"company_name\": \"Pipecorn\",\n      \"linkedin_url\": \"https://www.linkedin.com/in/mathieu-brun-picard/\",\n      \"custom\": {\n        \"hubspot_id\": \"4447901\"\n      }\n    },\n    {\n      \"firstname\": \"Nicolas\",\n      \"lastname\": \"Fernandez-Le Follic\",\n      \"domain\": \"pipecorn.com\",\n      \"company_name\": \"Pipecorn\",\n      \"linkedin_url\": \"https://www.linkedin.com/in/nicolasfernandezlefollic/\",\n      \"custom\": {\n        \"hubspot_id\": \"4447902\"\n      }\n    }\n  ],\n  \"webhook_url\": \"https://webhook.site/8b53c96f-f2cd-4c24-bc09-b3c2176d7ea8\",\n  \"enrichment_type\": [\n    \"email\"\n  ]\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.pipecorn.com/api/v2/contacts/bulk_enrich")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"contacts\": [\n    {\n      \"firstname\": \"Mathieu\",\n      \"lastname\": \"Brun-Picard\",\n      \"domain\": \"pipecorn.com\",\n      \"company_name\": \"Pipecorn\",\n      \"linkedin_url\": \"https://www.linkedin.com/in/mathieu-brun-picard/\",\n      \"custom\": {\n        \"hubspot_id\": \"4447901\"\n      }\n    },\n    {\n      \"firstname\": \"Nicolas\",\n      \"lastname\": \"Fernandez-Le Follic\",\n      \"domain\": \"pipecorn.com\",\n      \"company_name\": \"Pipecorn\",\n      \"linkedin_url\": \"https://www.linkedin.com/in/nicolasfernandezlefollic/\",\n      \"custom\": {\n        \"hubspot_id\": \"4447902\"\n      }\n    }\n  ],\n  \"webhook_url\": \"https://webhook.site/8b53c96f-f2cd-4c24-bc09-b3c2176d7ea8\",\n  \"enrichment_type\": [\n    \"email\"\n  ]\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://app.pipecorn.com/api/v2/contacts/bulk_enrich")

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  \"contacts\": [\n    {\n      \"firstname\": \"Mathieu\",\n      \"lastname\": \"Brun-Picard\",\n      \"domain\": \"pipecorn.com\",\n      \"company_name\": \"Pipecorn\",\n      \"linkedin_url\": \"https://www.linkedin.com/in/mathieu-brun-picard/\",\n      \"custom\": {\n        \"hubspot_id\": \"4447901\"\n      }\n    },\n    {\n      \"firstname\": \"Nicolas\",\n      \"lastname\": \"Fernandez-Le Follic\",\n      \"domain\": \"pipecorn.com\",\n      \"company_name\": \"Pipecorn\",\n      \"linkedin_url\": \"https://www.linkedin.com/in/nicolasfernandezlefollic/\",\n      \"custom\": {\n        \"hubspot_id\": \"4447902\"\n      }\n    }\n  ],\n  \"webhook_url\": \"https://webhook.site/8b53c96f-f2cd-4c24-bc09-b3c2176d7ea8\",\n  \"enrichment_type\": [\n    \"email\"\n  ]\n}"

response = http.request(request)
puts response.read_body
{
  "enrichment_id": "123e4567-e89b-12d3-a456-426614174000"
}
Enqueue up to 100 contacts for waterfall enrichment in a single request. The endpoint returns immediately with an enrichment_id for the bulk job; each contact is enriched asynchronously and results are delivered to your webhook_url as each contact completes.

​
Constraints

  • Minimum: 2 contacts per request. For a single contact, use the single async endpoint.
  • Maximum: 100 contacts per request.
  • A single enrichment_type applies to every contact in the batch.

​
Enrichment Types

Pass enrichment_type as an array containing one of:
  • ["email"] — Find and validate professional emails
  • ["phone"] — Find phone numbers (requires linkedin_url on every contact)
  • ["personal_email"] — Find personal emails (requires linkedin_url and account-level consent — see below)
Requesting personal_email requires the authenticated user to have consented to personal email enrichment in their account settings. If consent is missing the entire batch is rejected with 422 Unprocessable Entity. This consent gate is required for GDPR compliance.

​
Required Fields per contact

The required per-contact fields depend on the batch-wide enrichment_type:
enrichment_typeRequired fields per contact
["email"]firstname, lastname, and one of linkedin_url, domain, or company_name
["phone"]linkedin_url
["personal_email"]linkedin_url
Phone and personal email batches run off each contact’s linkedin_url alone, so firstname/lastname are not required for those types.

​
Receiving results

Provide webhook_url to receive results — we POST one payload per contact as each one finishes. The webhook payload echoes the custom fields you sent with that contact, so you can correlate results back to your records.

​
Credits

Credits are checked up-front for the entire batch. If your balance is insufficient the request is rejected with 422 Unprocessable Entity and no contacts are enqueued.

Authorizations

​
X-API-KEY
string
header
required

Your API key

Body

application/json

Bulk contact information for enrichment

Each contact requires firstname, lastname, and one of linkedin_url, domain, or company_name.

​
enrichment_type
enum<string>[]
required

Set to ["email"] for the whole batch.

Maximum array length: 1
Available options:
email
​
contacts
object[]
required
Maximum array length: 100
​
webhook_url
string<uri>

Webhook URL to receive enrichment results

​
phone_country_codes
string[]

Optional. Restrict phone enrichment to phone numbers from these countries (applies to every contact in the batch). When omitted, the user's account-level default phone country codes are applied.

ISO 3166-1 alpha-2 country code (e.g. "US", "FR", "GB")

Response

Bulk enrichment request accepted. Each contact is enriched asynchronously; results are delivered via the webhook_url callback as each contact finishes.

​
enrichment_id
string<uuid>

The ID of the bulk enrichment job