Skip to main content

QuickStart

Find website domains for two companies with Name to Domain (company-name-to-domain). This example uses sample company names; replace them with yours. Running the task can consume credits.

Authentication​

Create a Personal API Key from the API page in your Datablist account, then exchange it for a 24-hour access token:

bash
curl --request POST 'https://api.datablist.com/v1/account/token' \
  --header 'Content-Type: application/json' \
  --data '{"apiKey":"YOUR_PERSONAL_API_KEY"}'

See Get an access token for the request field, response attributes, and error statuses.

The response contains the token and its expiration:

json
{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "expires_at": 1791622800,
  "account_id": "account-id",
  "user_id": "user-id",
  "plan": "business",
  "scope": ["admin"]
}

Send access_token on every authenticated request:

http
Authorization: Bearer ACCESS_TOKEN

The account-bound token expires after 24 hours. Exchange the Personal API Key again after expiration. Deleting the key prevents future exchanges but does not revoke tokens that have already been issued.

Keep the key private. Use the access token, not the key, in the Bearer header. Never include either credential in task data or logs. You can access only tasks belonging to the token's account.

Try a request in the documentation​

Open Try it on an endpoint page. Choose Personal API Key, paste your key, and click Connect. You can also choose Access token to use a token you already have. The key is cleared after exchange. Authentication stays in memory while you navigate the documentation; refreshing the page or clicking Disconnect clears it. Connect again after the token expires or a request returns 401.

Fill in your IDs and review the parameters and JSON body, then click Send. The response panel shows the status, body, headers, and request duration. These are real API calls: tasks can consume credits, and writes or deletions change your data.

Closing the panel or clicking Cancel request stops waiting in your browser. It cannot undo work already accepted by the API. Check task status yourself; the documentation does not retry requests or check progress automatically.

Previous calls stay available in the panel so you can find earlier IDs and responses. Disconnect clears your credentials and call history.

1. Inspect the catalog and schema​

Copy the returned access_token. The examples below use DATABLIST_ACCESS_TOKEN as a placeholder.

List the available enrichments. Catalog discovery requires no authentication:

bash
curl 'https://api.datablist.com/v1/enrichments'

Confirm that company-name-to-domain appears in the catalog, then fetch its schema. If it is absent, choose an available enrichment and adapt the settings and inputs:

bash
curl 'https://api.datablist.com/v1/enrichments/company-name-to-domain'

Validate your settings and each input's data against the returned schemas.

2. Create a task​

Create a task with a unique uniqueId and one to 10,000 inputs:

bash
curl --request POST 'https://api.datablist.com/v1/enrichments/tasks' \
  --header 'Authorization: Bearer DATABLIST_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "enrichmentId": "company-name-to-domain",
    "uniqueId": "company-import-20261009-part-1",
    "settings": {},
    "inputs": [
      {"inputId": "company-123", "data": {"companyName": "Acme, Inc."}},
      {"inputId": "company-456", "data": {"companyName": "Example GmbH"}}
    ]
  }'

The API returns 202 Accepted. Save the task @id and the URLs under links. The response also includes the current status, progress, outcomes, and credits.

3. Poll the task​

Poll the task's links.self URL every few seconds:

bash
curl 'https://api.datablist.com/v1/enrichments/tasks/TASK_ID' \
  --header 'Authorization: Bearer DATABLIST_ACCESS_TOKEN'

Wait for status to become completed, failed, or stopped.

4. Read all results​

Once the task is completed, failed, or stopped, request its links.results URL:

bash
curl 'https://api.datablist.com/v1/enrichments/tasks/TASK_ID/results?limit=50' \
  --header 'Authorization: Bearer DATABLIST_ACCESS_TOKEN'

Each result contains your original inputId, a status, outputs, credits used, and an optional public error. Follow nextCursor until it is null:

bash
curl 'https://api.datablist.com/v1/enrichments/tasks/TASK_ID/results?limit=50&cursor=NEXT_CURSOR' \
  --header 'Authorization: Bearer DATABLIST_ACCESS_TOKEN'

Pass cursors back unchanged. Do not parse or construct them.

Safe retries​

If a creation response is lost, check task history for your uniqueId before sending another POST. The task may already be running or finished.

An active duplicate returns 409. Once a task is completed, failed, stopped, or overdue, you can reuse its ID, but doing so starts new work and can charge credits again.

503 ApiTaskDispatchFailed means the API could not start all the work. The task is marked failed, but some work may already have run and consumed credits. Check its results before deciding to create another task.