Lemlist Developer Docs

curl --request POST \
  --url https://api.lemlist.com/api/v2/enrichments/bulk \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "input": {
      "companyName": "Example Ets",
      "companyDomain": "example.com",
      "firstName": "John",
      "lastName": "Doe"
    },
    "enrichmentRequests": [
      "find_email"
    ],
    "metadata": {
      "id": "some_id"
    }
  },
  {
    "input": {
      "linkedinUrl": "https://www.linkedin.com/in/john-doe"
    },
    "enrichmentRequests": [
      "find_email"
    ],
    "metadata": "some_id"
  }
]
'

[
  {
    "id": "enr_ExampleA1b2C3d4E5",
    "metadata": {
      "id": "some_id"
    }
  },
  {
    "id": "enr_ExampleF6g7H8i9J0",
    "metadata": "some_id"
  },
  {
    "error": "MISSING_INPUTS",
    "message": "Missing LinkedIn url OR the combination of first name, last name, company name, company domain",
    "metadata": "some_id"
  }
]

POST

enrichments

bulk

curl --request POST \
  --url https://api.lemlist.com/api/v2/enrichments/bulk \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "input": {
      "companyName": "Example Ets",
      "companyDomain": "example.com",
      "firstName": "John",
      "lastName": "Doe"
    },
    "enrichmentRequests": [
      "find_email"
    ],
    "metadata": {
      "id": "some_id"
    }
  },
  {
    "input": {
      "linkedinUrl": "https://www.linkedin.com/in/john-doe"
    },
    "enrichmentRequests": [
      "find_email"
    ],
    "metadata": "some_id"
  }
]
'

[
  {
    "id": "enr_ExampleA1b2C3d4E5",
    "metadata": {
      "id": "some_id"
    }
  },
  {
    "id": "enr_ExampleF6g7H8i9J0",
    "metadata": "some_id"
  },
  {
    "error": "MISSING_INPUTS",
    "message": "Missing LinkedIn url OR the combination of first name, last name, company name, company domain",
    "metadata": "some_id"
  }
]

Unlike other endpoints, this one starts with /v2/enrichments.

Every call starts new enrichments and uses credits, even when the same person was enriched before.

How to use the endpoint

The bulk enrichment API is ideal for:

Processing large lists of prospects efficiently
Enriching CRM data in batches
Finding and verifying multiple contacts simultaneously
Automating data enrichment workflows at scale

Required inputs

Type	Required input	Description
`find_email`	`linkedinUrl` OR (`firstName` + `lastName` + (`companyName` OR `companyDomain`)) OR `email`	Find the person’s email and check its deliverability
`find_phone`	`linkedinUrl` OR (`firstName` + `lastName` + (`companyName` OR `companyDomain`)) OR `email`	Find phone numbers
`verify`	a valid `email`	Verify email deliverability
`linkedin_enrichment`	`linkedinUrl` OR `email` OR (`firstName` + `lastName` + (`companyName` OR `companyDomain`))	Enrich with LinkedIn profile data

linkedinUrl must be a person profile URL (linkedin.com/in/… or a Sales Navigator lead URL). For find_email and find_phone, any other LinkedIn URL is ignored and the other inputs must be enough on their own; for linkedin_enrichment it fails the row with BAD_LINKEDIN_URL.
For linkedin_enrichment, email and the name combination are only used when no linkedinUrl is given.
A row missing these inputs fails with MISSING_INPUTS; for verify, with MISSING_EMAIL when email is absent and BAD_EMAIL when it is not a valid email.
Requesting find_email and verify in the same row runs only one of them: verify when email is a valid email, find_email otherwise.

Every input value must be a string of at most 400 characters that contains no <…> sequence, and input may only hold the input fields: anything else rejects the whole call with WRONG_INPUT_FORMAT.

Metadata

The metadata field can be a string or an object whose values are strings, each of at most 400 characters and without any <…> sequence. It is returned in the API response and in the webhooks, allowing you to track and correlate enrichment requests. Any other value rejects the whole call with WRONG_METADATA_FORMAT.

Response

The API returns an array where each element corresponds to a request in the input array, in the same order. A started request returns an enrichment id; a request that could not be started returns an error code and a readable message.

{
  "id": "enr_ExampleA1b2C3d4E5",
  "metadata": {
    "crmId": "12345"
  }
}

{
  "error": "MISSING_INPUTS",
  "message": "Missing LinkedIn url OR the combination of first name, last name, company name, company domain",
  "metadata": "12345"
}

The row error codes are listed in Request errors.

Getting Results

Check Enrich Data for details on the enrichment result structure.

Since enrichment is asynchronous, you can retrieve results in two ways:

Webhooks (recommended): your team’s enrichment webhooks, and the webhookUrl query parameter when given, receive an event for each enrichment as soon as it is over
Polling: Use the Get Enrichment Result endpoint with the returned enrichment ID

Learn more about webhooks in the Enrich object definition.

Request error codes

These reject the whole call with a 400 (405 for METHOD_NOT_ALLOWED) and a {"error": "<CODE>"} body. No enrichment is started.

Error Code	Description
`WRONG_BODY_FORMAT`	The body must be a JSON array
`NO_ENRICHMENTS_REQUESTED`	The body must contain at least one enrichment
`TOO_MANY_ENRICHMENTS_REQUESTED`	Maximum 500 enrichments per request
`WRONG_INPUT_FORMAT`	An `input` is not an object, has a key that is not an input field, or a value that is not a string, is longer than 400 characters or contains a `<…>` sequence
`WRONG_METADATA_FORMAT`	A `metadata` is neither a string nor an object whose values are strings, or one of its strings is longer than 400 characters or contains a `<…>` sequence
`WRONG_ENRICHMENT_REQUEST_FORMAT`	An `enrichmentRequests` is not an array
`NO_WORKFLOW_REQUESTED`	An `enrichmentRequests` is empty
`UNAUTHORIZED_WORKFLOW_REQUESTED`	An `enrichmentRequests` holds an unknown enrichment type
`WRONG_WEBHOOK_URL`	The `webhookUrl` query parameter is not a valid URL
`METHOD_NOT_ALLOWED`	The endpoint only accepts `POST`

Limits

Maximum requests per call: 500 enrichments
Rate limits: Standard API rate limits apply (20 requests per 2 seconds)
Credits: Each enrichment type consumes credits from your team’s balance

See lemlist API credits for more information about credit consumption.

Authorizations

Authorization

string

header

required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Query Parameters

webhookUrl

string

URL that receives the enrichmentDone or enrichmentError event of each enrichment of the call, on top of your team's webhooks. See the webhooks of the Enrichment object.

Body

application/json

Maximum array length: 500

input

object

required

Input data for enrichment. Required fields depend on enrichmentRequests (see Required inputs). Values must be strings of at most 400 characters without any <…> sequence; an unknown key or any other value rejects the whole call with WRONG_INPUT_FORMAT.

Show child attributes

enrichmentRequests

enum<string>[]

required

Enrichment types to perform, at least one of: find_email, find_phone, verify, linkedin_enrichment. Requesting find_email and verify together runs only one of them: verify when input.email is a valid email, find_email otherwise.

Available options:

find_email,

find_phone,

verify,

linkedin_enrichment

Example:

["find_email", "verify"]

metadata

Custom data returned in the response and in the webhooks. A string, or an object whose values are strings, each of at most 400 characters without any <…> sequence; anything else rejects the whole call with WRONG_METADATA_FORMAT.

Example:

{ "id": "some_id" }

Response

One item per row, in the order of the request: an enrichment id, or an error code with its message when the row could not be started

string

Enrichment ID, when the row was started

Example:

"enr_ExampleA1b2C3d4E5"

error

enum<string>

Why the row was not started. See the request errors of the Enrichment object.

Available options:

BAD_EMAIL,

BAD_LINKEDIN_URL,

MISSING_EMAIL,

MISSING_INPUTS,

MISSING_FUNDS,

CREDITS_USAGE_FORBIDDEN,

NOT_ALLOWED_EMAIL,

NOT_ALLOWED_PHONE,

NOT_ALLOWED_LINKEDIN,

NOT_ALLOWED_VERIFY,

LINKEDIN_UNSUBSCRIBED,

TEAM_BLOCKED,

TEAM_IN_ERROR,

SYSTEM_DISABLED,

NO_AVAILABLE_PROVIDER

message

string

Human-readable explanation of error, present with it, possibly translated to the language of the API user. Branch on error, never on message.

metadata

The metadata sent with the row, when any

Getting started

Popular Resources

Endpoints

Objects & Definitions

Bulk Enrich Data

How to use the endpoint

Required inputs

Metadata

Response

Getting Results

Request error codes

Limits

Authorizations

Query Parameters

Body

Response

​How to use the endpoint

​Required inputs

​Metadata

​Response

​Getting Results

​Request error codes

​Limits

Authorizations

Query Parameters

Body

Response

How to use the endpoint

Required inputs

Metadata

Response

Getting Results

Request error codes

Limits