Skip to content
Console(opens in a new tab)

Retrieve a background task

Get the negative news results that were not ready when the POST request returned: the full definition of GET /v2/kyb/{task_id}.

GEThttps://api.enigma.com/v2/kyb/{task_id}

Negative news is the only part of a KYB response that can arrive after the POST request returns. When the articles are not ready before the POST response is sent, the response carries a background_task object with a non-null id. That id is the task ID: pass it to this endpoint to retrieve the results. Get negative news walks through the whole flow.

The Request tab shows a poll. Each of the other tabs shows an example response for one background task status. The article is illustrative, and the error wording can change.

This POST response comes from a request with attrs=negative_news, trimmed to background_task. Its id is not null, so poll this endpoint for the results.

POST response (trimmed)
{
"background_task": {
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"status": "pending",
"subtasks": []
}
}

Poll with that ID:

cURL
curl --request GET "https://api.enigma.com/v2/kyb/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
--header "x-api-key: $ENIGMA_API_KEY"
x-api-keyheaderRequired

Your API key, the same kind of key as for the POST request. Send it from your server only. See Authentication.

task_idpath, stringRequired

The background_task.id from the POST response. Treat it as an opaque string and pass it exactly as returned.

The request has no body and no query parameters. Background tasks belong to your organization, not to one API key. Any API key in the organization that sent the POST request can retrieve the background task.

A 200 response always has these three fields. It has the same shape as background_task in the POST response, except that the ID is named task_id and there is no top-level error.

task_idstring

The background task ID, as a lowercase UUID with dashes.

statusstring

The background task status: pending, complete or failed. See Status values.

subtasksarray of object

The results so far. Each item has one key, media, which holds one subtask.

Each media subtask is the negative news result for one registered entity. The API calls a registered entity a legal entity here. The article fields are listed in Subtasks and articles.

legal_entity_idstring or null

The entity’s id from data.registered_entities[].id in the POST response. null while the subtask is pending, and on a subtask that names no entity.

statusstring

The subtask status: pending, complete or failed.

resultobjectWhen status is complete

result.negative_news holds the articles. When legal_entity_id is set, negative_news: null means Enigma found no negative news for that entity. When legal_entity_id is null, negative_news: null says nothing about any entity.

errorstringWhen status is failed

Why the lookup did not finish.

A pending subtask does not name an entity yet. When it completes, it can become one subtask per registered entity, so the number of subtasks can change between polls. Key results by legal_entity_id, not by position in the array.

The same three values apply to background_task.status in the POST response, to status in the GET response, and to each subtask. These are not task statuses. The rule for the background task status depends on where you read it:

Where you read it Rule
GET response, or a POST response where id is null and there is no error The status is derived from the subtasks. It is failed if any subtask failed, otherwise pending if any is pending, otherwise complete.
POST response where id is set The status is always pending, even when every subtask already in subtasks is complete.
POST response where error is present The status is failed and subtasks is empty.

Each value means the following. Whatever the status, read the complete subtasks.

Value Background task Subtask
pending At least one result is not ready and none has failed. Poll the GET endpoint. The result is not ready.
complete Every result is ready. Stop polling. The result is in result.
failed At least one subtask failed, or the background task could not be created (error is present, and this is final). On the GET, failed is not final: other subtasks can still be pending, and a later poll can resolve a failed subtask. Poll again. The lookup did not finish. error says why.
  1. Read background_task in the POST response.
    • No background_task: no registered entity matched, or the news lookup failed for every matched entity. There is nothing to poll, and no registered entity has a negative news result.
    • id is null: there is nothing to poll. The results are in background_task.subtasks, or, if status is failed, error says why the background task could not be created.
    • id is set (status is always pending): go to step 2.
  2. Call this endpoint with id as task_id.
  3. While status is pending, wait and poll again. Start with a 2-second wait and double it after each poll, up to 30 seconds: 2, 4, 8, 16, 30, 30, and so on.
  4. When status is complete, stop polling. When it is failed, follow When a poll returns failed.
  5. Merge the POST and GET results. See Combine POST and GET results.

Polling more often does not make results arrive sooner. No retention period is guaranteed for a background task. Poll soon after the POST request, and store the results you need.

A failed status is not final. Each poll looks up the results again, so a temporary error can show as a failed subtask on one poll, and a later poll can return pending or complete for it. Because failed outranks pending, a failed background task can also hold subtasks that are still pending.

When status is failed:

  • Keep every complete subtask. Each failed subtask has an error.
  • An entity without a complete subtask has no negative news result.
  • If any subtask is still pending, keep polling with the same backoff until none is.
  • A failed subtask can succeed on a later poll, but this is not guaranteed. If it keeps failing, send a new POST request to run negative news again. It is a new request, with a new response_id and a new background task.

The GET returns only the results that were still pending when the POST request returned. Subtasks that were already complete in the POST response are not repeated. To see every result, merge the complete subtasks from background_task.subtasks in the POST response with the subtasks from the final GET response, keyed by legal_entity_id. Then read each registered entity’s result as described in Interpret the results.

Status When What to do
200 The background task exists in your organization, whatever its status. Read status.
401 The x-api-key header is missing or the API key is invalid. Check the key. Do not retry unchanged.
403 Access was denied. Check the key. Do not retry unchanged.
404 task_id is not a valid task ID, is unknown, or belongs to another organization. Do not retry. Check that you passed background_task.id from a POST request sent by your organization.
503 Enigma could not look up the background task. The background task may still exist. Retry with backoff.

The 404 and 503 responses use the standard error body. Other statuses, such as a gateway 401, 403 or 504, or a 500, can have a different body, so branch on the HTTP status, not on the message. For retry rules, see Errors and rate limits.

Example 404 response
{
"error": true,
"message": "task not found"
}