Bulk Contact Enrichment (deprecated)

Enrich multiple contacts (deprecated)

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"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": "<string>"
}

{
  "error": "Not enough enrichment credits left",
  "code": "insufficient_credits",
  "top_up_url": "https://app.pipecorn.com/settings/subscriptions/credits"
}

{
  "error": "You have reached your weekly enrichment credit limit for this workspace",
  "code": "workspace_limit_exceeded"
}

{
  "error": "A request with this Idempotency-Key is still being processed",
  "code": "idempotency_key_in_use"
}

{
  "error": "You can't use the personal email enrichment feature without consenting with our terms of use"
}

POST

contacts

bulk_enrich

Enrich multiple contacts (deprecated)

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"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": "<string>"
}

{
  "error": "Not enough enrichment credits left",
  "code": "insufficient_credits",
  "top_up_url": "https://app.pipecorn.com/settings/subscriptions/credits"
}

{
  "error": "You have reached your weekly enrichment credit limit for this workspace",
  "code": "workspace_limit_exceeded"
}

{
  "error": "A request with this Idempotency-Key is still being processed",
  "code": "idempotency_key_in_use"
}

{
  "error": "You can't use the personal email enrichment feature without consenting with our terms of use"
}

This endpoint is deprecated. Send one request per contact to the asynchronous single endpoint (results delivered to your webhook_url) or, when you need results inline, to the synchronous endpoint. Existing integrations keep working, but this endpoint receives no new features — phone_type filtering and phone_details are only available on the single endpoints.

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_type`	Required 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 402 Payment Required and code: "insufficient_credits", and no contacts are enqueued — the response carries a top_up_url you can send the user to. If the batch would exceed your workspace weekly credit limit, the request is rejected with 403 Forbidden and code: "workspace_limit_exceeded" instead; buying credits does not lift that limit. See Credit and limit errors.

Authorizations

X-API-KEY

string

header

required

Your API key

Headers

Idempotency-Key

string

A unique value you generate per operation, such as a UUID. Retrying with the same key and the same body returns the stored response instead of running the request again, so a retry after a timeout never charges twice. Successful responses are kept for 24 hours; a failed request is not stored and can be retried with the same key.

Maximum string length: 255

Example:

"4f1c2e9a-8a7d-4c1b-9f63-2d6e0b5a7c11"

Body

application/json

Bulk contact information for enrichment

Email batch
Phone batch
Personal email batch

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

Option 1
Option 2
Option 3

Show child attributes

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

Overview

Leads (People)

Accounts (Companies)

Waterfall Enrichment

Signals

Searches

Personas

Lists

Alerts

Miscellaneous

API Reference

Constraints

Enrichment Types

Required Fields per contact

Receiving results

Credits

Authorizations

Headers

Body

Response

​Constraints

​Enrichment Types

​Required Fields per contact

​Receiving results

​Credits

Authorizations

Headers

Body

Response

Constraints

Enrichment Types

Required Fields per contact

Receiving results

Credits