Browse API docsFind decision makers
External API docs

Find decision makers

Start a background search for people at known company domains, check its status, and retrieve the results when it finishes.

Starting from a company list?

If you do not already have company domains, start with Search businesses. The end-to-end guide shows how to take content.root_domain from search results, prepare batches, and connect each person back to the original business.

Follow the complete search-to-owner workflow

Overview

Use this endpoint to find decision makers or other employees when you already know the company's website domain.

This is a background workflow:

  1. submit a batch of tasks
  2. check the batch status until it is ready
  3. retrieve each result using its task ID

Before you start

Make sure you have:

  • an Openmart account
  • an API key
  • one or more company domains to enrich
  • 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.

1

Step 1: Submit a task

Example: Find the head of marketing at Blue Bottle in the U.S.

Use this example after you have a company email domain (for example from Search businesses). Openmart will attempt to find a head of marketing contact for that business. Some optional fields are omitted and Openmart applies their default values.

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

Parameters

Parameter
domain
Type
string
Required
Yes
Example
"bluebottlecoffee.com"
Description
Company email domain to search (e.g. acme.com, no @ or https://).
Parameter
title
Type
string
Required
Yes
Example
"Head of Marketing"
Description
Role to match (for example VP Sales, Head of Marketing).
Parameter
max_k
Type
integer
Required
Yes
Example
2
Description
Maximum number of contacts to return for this company (1–8).
Parameter
country
Type
string
Required
No
Example
"US"
Description
Location hint to narrow matching to the U.S.

cURL request

cURL
curl --request POST \
  --url https://api.openmart.ai/api/v1/task/batch/find_people \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "domain": "bluebottlecoffee.com",
      "company_name": "Blue Bottle",
      "title": "Head of Marketing",
      "max_k": 2,
      "country": "US"
    }
  ]'

Response details

This request returns a batch_id. Use it to poll batch status, then retrieve final results by task ID.

Response example

JSON
{
  "batch_id": "183219bc-066e-4641-9d6f-48205b7fbada",
  "submit_for": "find_people",
  "status": {
    "processing": 1,
    "completed": 0,
    "errored": 0,
    "total": 1,
    "batch_ready": false
  }
}

Key elements of the API response

Response element
batch_id
Description
The ID for this 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
The task type submitted (for example find_people).
Response element
status.batch_ready
Description
When true, the batch has produced task IDs and you can fetch results.
Response element
status.processing
Description
How many tasks are still processing.
Response element
status.completed
Description
How many tasks have completed.
2

Step 2: Check batch status

Replace <batch_id> with the batch_id from the submit response.

Endpoint
GET https://api.openmart.ai/api/v1/task/batch/<batch_id>/status

cURL request

cURL
curl --request GET \
  --url https://api.openmart.ai/api/v1/task/batch/<batch_id>/status \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>'

Response example

JSON
{
  "processing": 0,
  "completed": 1,
  "errored": 0,
  "total": 1,
  "batch_ready": true
}

Keep polling until batch_ready becomes true.

3

Step 3: Get task IDs in a batch

After the batch is ready, fetch task IDs for completed tasks. Replace <batch_id> with your batch ID.

Endpoint
GET https://api.openmart.ai/api/v1/task/batch/<batch_id>/task_ids?status=COMPLETED

cURL request

cURL
curl --request GET \
  --url https://api.openmart.ai/api/v1/task/batch/<batch_id>/task_ids?status=COMPLETED \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>'

Response example

JSON
[
  "2fc8b627-1111-2222-3333-123456789abc"
]

Copy one task ID and use it in the next step.

4

Step 4: Get task results

Replace <task_id> with a task ID from the previous step.

Endpoint
GET https://api.openmart.ai/api/v1/task/<task_id>

cURL request

cURL
curl --request GET \
  --url https://api.openmart.ai/api/v1/task/<task_id> \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>'

Response example

JSON
{
  "task_id": "2fc8b627-1111-2222-3333-123456789abc",
  "status": "COMPLETED",
  "tracking_id": "customer-42",
  "data": [
    {
      "first_name": "Jane",
      "last_name": "Doe",
      "title": "Head of Marketing",
      "email": { "email": "jane@bluebottlecoffee.com", "verified": true }
    }
  ]
}

When status is COMPLETED, read the final payload in data.

All request parameters

Request body for POST /api/v1/task/batch/find_people. Send a JSON array of task objects (min 1, max 100). Each object uses the same schema as constants.FindPeopleAPIParam.

Most common parameters

These are the fields most teams set for day-to-day people enrichment.

domainstringRequired: Yes
Example: "bluebottlecoffee.com"

Company email domain to search (e.g. acme.com, no @ or https://).

cURL example
cURL
curl --request POST \
  --url https://api.openmart.ai/api/v1/task/batch/find_people \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","title":"Head of Marketing","max_k":2}]'
titlestringRequired: Yes
Example: "Head of Marketing"

Role to match (e.g. VP Sales, Marketing Director). If empty, the server may substitute a default owner/employee.

cURL example
cURL
curl --request POST \
  --url https://api.openmart.ai/api/v1/task/batch/find_people \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","title":"Head of Marketing","max_k":2}]'
company_namestringRequired: No
Example: "Blue Bottle Coffee"

Brand/legal name; helps disambiguate common domains.

cURL example
cURL
curl --request POST \
  --url https://api.openmart.ai/api/v1/task/batch/find_people \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","company_name":"Blue Bottle Coffee","title":"Head of Marketing","max_k":2}]'
max_kintegerRequired: Yes
Example: 2

Max contacts to return for this array item (1-8).

cURL example
cURL
curl --request POST \
  --url https://api.openmart.ai/api/v1/task/batch/find_people \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","title":"Head of Marketing","max_k":2}]'
info_accessarray[string]Required: No
Example: ["EMAIL","PHONE"]

Include EMAIL, PHONE, or both. Default: both if omitted. If provided, it must contain at least one value.

cURL example
cURL
curl --request POST \
  --url https://api.openmart.ai/api/v1/task/batch/find_people \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","title":"Head of Marketing","max_k":2,"info_access":["EMAIL","PHONE"]}]'

Location hints

Use these fields when one domain maps to multiple regions.

citystringRequired: No
Example: "San Francisco"

Location hint when one domain maps to multiple regions.

cURL example
cURL
curl --request POST \
  --url https://api.openmart.ai/api/v1/task/batch/find_people \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","title":"Head of Marketing","max_k":2,"city":"San Francisco"}]'
statestringRequired: No
Example: "CA"

Location hint when one domain maps to multiple regions.

cURL example
cURL
curl --request POST \
  --url https://api.openmart.ai/api/v1/task/batch/find_people \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","title":"Head of Marketing","max_k":2,"state":"CA"}]'
countrystringRequired: No
Example: "US"

Location hint when one domain maps to multiple regions.

cURL example
cURL
curl --request POST \
  --url https://api.openmart.ai/api/v1/task/batch/find_people \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","title":"Head of Marketing","max_k":2,"country":"US"}]'

Pipeline and delivery

Advanced options for pipeline selection and completion callbacks (when enabled).

versionintegerRequired: No
Example: 0

0 = default pipeline; 1 = alternate all-in-one variant.

cURL example
cURL
curl --request POST \
  --url https://api.openmart.ai/api/v1/task/batch/find_people \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","title":"Head of Marketing","max_k":2,"version":0}]'
notify_urlstringRequired: No
Example: "https://example.com/webhook/openmart"

HTTPS URL for completion callback (if supported for your key).

cURL example
cURL
curl --request POST \
  --url https://api.openmart.ai/api/v1/task/batch/find_people \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","title":"Head of Marketing","max_k":2,"notify_url":"https://example.com/webhook/openmart"}]'

Optional metadata

Use these fields to correlate responses back to your internal records.

tracking_idstringRequired: No
Example: "customer-42"

Your ID; echoed on GET /api/v1/task/{task_id} for correlation.

cURL example
cURL
curl --request POST \
  --url https://api.openmart.ai/api/v1/task/batch/find_people \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","title":"Head of Marketing","max_k":2,"tracking_id":"customer-42"}]'

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.