External API docs

Find employees

Submit async enrichment tasks for known company domains, then poll and retrieve final results after processing completes.

Overview

Use this endpoint to find employees for a company when you already know the company's website domain.

This is an asynchronous workflow:

  1. submit a batch of tasks
  2. poll batch status until ready
  3. fetch task results by 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
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 the backend may apply defaults.

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 https://).
Parameter
title
Type
string
Required
Yes
Example
"Head of Marketing"
Description
Role to match (for example VP Sales, Head of Marketing).
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 'X-API-Key: <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "domain": "@bluebottlecoffee.com",
      "company_name": "Blue Bottle",
      "title": "Head of Marketing",
      "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. Use it to poll for readiness.
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 'X-API-Key: <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 'X-API-Key: <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 'X-API-Key: <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 https://).

cURL example
cURL
curl --request POST \
  --url https://api.openmart.ai/api/v1/task/batch/find_people \
  --header 'Accept: application/json' \
  --header 'X-API-Key: <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","title":"Head of Marketing"}]'
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 'X-API-Key: <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","title":"Head of Marketing"}]'
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 'X-API-Key: <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","company_name":"Blue Bottle Coffee","title":"Head of Marketing"}]'
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 'X-API-Key: <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.

cURL example
cURL
curl --request POST \
  --url https://api.openmart.ai/api/v1/task/batch/find_people \
  --header 'Accept: application/json' \
  --header 'X-API-Key: <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","title":"Head of Marketing","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 'X-API-Key: <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","title":"Head of Marketing","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 'X-API-Key: <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","title":"Head of Marketing","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 'X-API-Key: <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","title":"Head of Marketing","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 'X-API-Key: <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 'X-API-Key: <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 'X-API-Key: <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '[{"domain":"bluebottlecoffee.com","title":"Head of Marketing","tracking_id":"customer-42"}]'
# Find Employees

## Endpoint

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

## Description

Submit async enrichment tasks for known company domains. Returns a batch_id; poll for status, then retrieve results. This is an asynchronous workflow.

## Authentication

Header: `X-API-Key: <your_api_key>`

## Parameters

### Most common parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| domain | string | Yes | Company email domain (e.g. acme.com, no https://). |
| title | string | Yes | Role to match (e.g. VP Sales, Head of Marketing). |
| max_k | integer | Yes | Max contacts to return for this item (1–8). |
| company_name | string | No | Brand/legal name; helps disambiguate common domains. |
| info_access | array[string] | No | Include "EMAIL", "PHONE", or both. Default: both. |

### Location hints

| Name | Type | Required | Description |
|------|------|----------|-------------|
| city | string | No | Location hint when one domain maps to multiple regions. |
| state | string | No | Location hint when one domain maps to multiple regions. |
| country | string | No | Location hint when one domain maps to multiple regions. |

### Pipeline and delivery

| Name | Type | Required | Description |
|------|------|----------|-------------|
| version | integer | No | 0 = default pipeline; 1 = alternate all-in-one variant. |
| notify_url | string | No | HTTPS URL for completion callback. |

### Optional metadata

| Name | Type | Required | Description |
|------|------|----------|-------------|
| tracking_id | string | No | Your ID; echoed on GET /api/v1/task/{task_id} for correlation. |

## Example Request

```bash
curl -X POST "https://api.openmart.ai/api/v1/task/batch/find_people" \
  -H "Accept: application/json" \
  -H "X-API-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "domain": "@bluebottlecoffee.com",
      "company_name": "Blue Bottle",
      "title": "Head of Marketing",
      "country": "US"
    }
  ]'
```

## Example Response (submit)

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

## Async workflow

1. Submit → receive batch_id (above)
2. Poll: GET /api/v1/task/batch/<batch_id>/status → wait until batch_ready is true
3. Get IDs: GET /api/v1/task/batch/<batch_id>/task_ids?status=COMPLETED
4. Get results: GET /api/v1/task/<task_id>

## Task result 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 }
    }
  ]
}
```