Browse API docsEnrich known people
External API docs

Enrich known people

Submit an async batch to enrich a list of known people (names + optional LinkedIn) for a company domain. Returns email and/or phone per person.

Overview

Use this endpoint when you already know who you want to enrich and just need their contact info. You provide one or more people (name, optional LinkedIn URL) scoped to a company domain; the workflow returns their email, phone, or both.

If you don't know the specific people yet and want to discover decision makers by title, use find decision makers instead.

Before you start

Make sure you have:

  • an Openmart account
  • an API key
  • a tool to send API requests, such as Postman or curl

Authentication. We recommend sending your API key as Authorization: Bearer <your_api_key>. If your current integration already uses X-API-Key: <your_api_key>, it will continue to work.

Allow enough time to start the job. The request can take more than 30 seconds to return a batch_id, so set your HTTP client timeout to at least 60 seconds. The enrichment then continues in the background. If your app times out, check whether it saved a batch ID before starting the same job again.

This runs as a background job. After you start it, follow: check batch status, get task IDs, then get task results.

1

Submit a batch of people lookups

Endpoint
POST https://api.openmart.ai/api/v1/task/batch/lookup_people

Parameters

Parameter
domain
Type
string
Required
Yes
Example
"bluebottlecoffee.com"
Description
Company root domain where the people work.
Parameter
company_name
Type
string
Required
No
Example
"Blue Bottle"
Description
Optional human-readable company name. Improves resolution when the domain is ambiguous.
Parameter
people
Type
array[object]
Required
Yes
Example
[{"first_name":"Jane","last_name":"Doe"}]
Description
Known people to enrich. 1 to 8 entries per task. Each needs first_name and last_name; linkedin_url is optional and helps disambiguation.
Parameter
include_phone_grade
Type
boolean
Required
No
Example
false
Description
Optional boolean. Defaults to enabled for API calls unless the server default is changed. Explicit false skips phone verification and grade for fresh lookups (valid and confidence_grade are null; verification_status is unverified). Cached grades are retained and missing cached grades are not backfilled.
Parameter
info_access
Type
array[string]
Required
No
Example
["EMAIL","PHONE"]
Description
Which contact fields to return. Allowed values: EMAIL, PHONE. Default: ["EMAIL","PHONE"] (both). If provided, it must contain at least one value.
Parameter
tracking_id
Type
string
Required
No
Example
"bluebottle-jane"
Description
Your correlation ID. Echoed back on task read.

cURL request

cURL
curl --request POST \
  --url https://api.openmart.ai/api/v1/task/batch/lookup_people \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "domain": "bluebottlecoffee.com",
      "company_name": "Blue Bottle",
      "city": "Oakland",
      "state": "CA",
      "country": "US",
      "info_access": ["EMAIL", "PHONE"],
      "people": [
        {
          "first_name": "Jane",
          "last_name": "Doe",
          "linkedin_url": "https://www.linkedin.com/in/jane-doe/"
        }
      ],
      "tracking_id": "bluebottle-jane"
    }
  ]'

Submission response

JSON
{
  "batch_id": "2fc8b627-1111-2222-3333-123456789abc",
  "submit_for": "lookup_people",
  "status": {
    "processing": 1,
    "completed": 0,
    "errored": 0,
    "total": 1,
    "batch_ready": false
  }
}
Response element
batch_id
Description
UUID for the submitted batch. Keep the submission request open long enough to read it; use a client timeout of at least 60 seconds.
Response element
submit_for
Description
Task type echoed back. Either "lookup_people" or "lookup_business_email" (depending on which endpoint you called).
Response element
status.processing / completed / errored / total
Description
Per-task counts. On submit, everything starts in processing.
Response element
status.batch_ready
Description
true once processing == 0. Keep polling GET /api/v1/task/batch/{batch_id}/status until this flips to true.

Per-task result (via GET /api/v1/task/{task_id})

Once the batch is ready, fetching each task ID returns:

JSON
{
  "task_id": "2fc8b627-aaaa-bbbb-cccc-00112233aabb",
  "status": "COMPLETED",
  "tracking_id": "bluebottle-jane",
  "data": [
    {
      "first_name": "Jane",
      "last_name": "Doe",
      "linkedin_url": "https://www.linkedin.com/in/jane-doe/",
      "email": {
        "email": "jane@bluebottlecoffee.com",
        "verified": true
      },
      "phones": [
        {
          "phone_number": "+14155550123",
          "line_type": "MOBILE",
          "valid": true,
          "confidence_grade": "A"
        }
      ]
    }
  ]
}

data is an array of PeopleInfo records (first_name, last_name, linkedin_url, email, phones).

After submission: get your results

Submission just enqueues the batch. To retrieve results:

  1. Poll GET /api/v1/task/batch/{batch_id}/status until batch_ready is true.
  2. Call GET /api/v1/task/batch/{batch_id}/task_ids?status=COMPLETED to list task IDs that finished.
  3. For each task ID, call GET /api/v1/task/{task_id} to read data — the task-specific result payload.

All request parameters

Request body is a JSON array of 1–100 task objects for POST /api/v1/task/batch/lookup_people. Batch-size errors return 400 with {"detail":"the number of tasks in each batch should be between 1 and 100"}.

Per-task fields

Each item in the batch array is one task. Submit 1 to 100 tasks per request.

domainstringRequired: Yes
Example: "bluebottlecoffee.com"

Company root domain. Missing → 400 detail:"Domain is required".

cURL example
cURL
curl --request POST \
  --url https://api.openmart.ai/api/v1/task/batch/lookup_people \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","people":[{"first_name":"Jane","last_name":"Doe"}]}]'
company_namestringRequired: No
Example: "Blue Bottle"

Optional human-readable company name.

cURL example
cURL
curl --request POST \
  --url https://api.openmart.ai/api/v1/task/batch/lookup_people \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","company_name":"Blue Bottle","people":[{"first_name":"Jane","last_name":"Doe"}]}]'
city / state / countrystringRequired: No
Example: "Oakland" / "CA" / "US"

Optional company-location narrowing.

cURL example
cURL
curl --request POST \
  --url https://api.openmart.ai/api/v1/task/batch/lookup_people \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","city":"Oakland","state":"CA","country":"US","people":[{"first_name":"Jane","last_name":"Doe"}]}]'
include_phone_gradebooleanRequired: No
Example: false

Optional boolean. Defaults to enabled for API calls unless the server default is changed. Explicit false skips phone verification and grade for fresh lookups (valid and confidence_grade are null; verification_status is unverified). Cached grades are retained and missing cached grades are not backfilled.

cURL example
cURL
curl --request POST --url https://api.openmart.ai/api/v1/task/batch/lookup_people --header 'Content-Type: application/json' --data '[{"domain": "example.com", "people": [{"first_name": "Jane", "last_name": "Doe"}], "include_phone_grade": false}]'
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
info_accessarray[string]Required: No
Example: ["EMAIL","PHONE"]

Subset of contact fields to return. Each element must be "EMAIL" or "PHONE". Default (when omitted) is both. If provided, it must contain at least one value.

cURL example
cURL
curl --request POST \
  --url https://api.openmart.ai/api/v1/task/batch/lookup_people \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","info_access":["EMAIL"],"people":[{"first_name":"Jane","last_name":"Doe"}]}]'
peoplearray[object]Required: Yes
Example: [{"first_name":"Jane","last_name":"Doe"}]

Known people to enrich. Include 1–8 people per task. Each person requires first_name and last_name; linkedin_url is optional and improves match quality.

cURL example
cURL
curl --request POST \
  --url https://api.openmart.ai/api/v1/task/batch/lookup_people \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","people":[{"first_name":"Jane","last_name":"Doe","linkedin_url":"https://www.linkedin.com/in/jane-doe/"}]}]'
tracking_idstringRequired: No
Example: "bluebottle-jane"

Caller-supplied correlation ID. Echoed back on task read.

cURL example
cURL
curl --request POST \
  --url https://api.openmart.ai/api/v1/task/batch/lookup_people \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","people":[{"first_name":"Jane","last_name":"Doe"}],"tracking_id":"bluebottle-jane"}]'
notify_urlstring (URL)Required: No
Example: "https://your.webhook/endpoint"

Optional webhook URL. It must be a complete, valid URL when provided.

cURL example
cURL
curl --request POST \
  --url https://api.openmart.ai/api/v1/task/batch/lookup_people \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","people":[{"first_name":"Jane","last_name":"Doe"}],"notify_url":"https://your.webhook/endpoint"}]'

If this request fails

Match the error number or message in the response, then use the action below.

Error 400 / 422“... is required” or another field error
Read the error or detail field, then fix the named input.
Error 401“Invalid API Key”
Check the complete key and authentication header.
Error 402“Credit limit reached”
Check the team balance before trying again.
Error 403“Forbidden” or “not allowed”
Check whether this key and account can use the action.
Error 404“Not Found”
Check the API address, version, and GET, POST, or DELETE method.
Error 429“Too many requests”
Wait, then retry with fewer requests running at once.
Error 500–504Server error or timeout
Wait briefly and retry. Avoid duplicating an async job.

See Troubleshooting & FAQ for step-by-step help and the information to include when asking for support.