- Docs
- API reference
- Endpoints and schemas
- KYB API
- Endpoints
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}.
https://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.
Example
Section titled “Example”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.
{ "background_task": { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "status": "pending", "subtasks": [] }}Poll with that ID:
curl --request GET "https://api.enigma.com/v2/kyb/f47ac10b-58cc-4372-a567-0e02b2c3d479" \ --header "x-api-key: $ENIGMA_API_KEY"The subtask has not resolved and names no entity yet. Poll again.
{ "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "status": "pending", "subtasks": [ { "media": { "legal_entity_id": null, "status": "pending" } } ]}A complete subtask that names a registered entity, with its articles. Stop polling and merge.
{ "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "status": "complete", "subtasks": [ { "media": { "legal_entity_id": "4dccd7a5-790c-c4d1-0000-108000000000", "status": "complete", "result": { "negative_news": [ { "url": "https://example.com/news/article", "title": "Example negative news headline", "sentiment": "negative", "sourceName": "Example News", "publishedDate": "2026-05-22" } ] } } } ]}A complete background task can also return a single subtask that names no entity. Its result.negative_news: null says nothing about any entity.
{ "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "status": "complete", "subtasks": [ { "media": { "legal_entity_id": null, "status": "complete", "result": { "negative_news": null } } } ]}The subtask failed and has an error. See When a poll returns failed.
{ "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "status": "failed", "subtasks": [ { "media": { "legal_entity_id": null, "status": "failed", "error": "upstream reported failure" } } ]}Parameters
Section titled “Parameters”x-api-keyRequiredYour API key, the same kind of key as for the POST request. Send it from your server only. See Authentication.
task_idRequiredThe
background_task.idfrom 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.
Response
Section titled “Response”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_idThe background task ID, as a lowercase UUID with dashes.
statusThe background task status:
pending,completeorfailed. See Status values.subtasksThe results so far. Each item has one key,
media, which holds one subtask.
The media subtask
Section titled “The media 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_idThe entity’s
idfromdata.registered_entities[].idin the POST response.nullwhile the subtask is pending, and on a subtask that names no entity.statusThe subtask status:
pending,completeorfailed.resultWhenstatusiscompleteresult.negative_newsholds the articles. Whenlegal_entity_idis set,negative_news: nullmeans Enigma found no negative news for that entity. Whenlegal_entity_idisnull,negative_news: nullsays nothing about any entity.errorWhenstatusisfailedWhy 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.
Status values
Section titled “Status values”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. |
Poll for results
Section titled “Poll for results”- Read
background_taskin 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. idisnull: there is nothing to poll. The results are inbackground_task.subtasks, or, ifstatusisfailed,errorsays why the background task could not be created.idis set (statusis alwayspending): go to step 2.
- No
- Call this endpoint with
idastask_id. - While
statusispending, 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. - When
statusiscomplete, stop polling. When it isfailed, follow When a poll returnsfailed. - 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.
When a poll returns failed
Section titled “When a poll returns failed”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_idand a new background task.
Combine POST and GET results
Section titled “Combine POST and GET results”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 codes
Section titled “Status codes”| 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.
{ "error": true, "message": "task not found"}Related
Section titled “Related”- Get negative news: request negative news and poll for it, end to end.
- Negative news: the background task, subtask and article objects.
POST /v2/kyb/: the request that creates the background task.- Response object: where
background_tasksits in the POST response. - Errors and rate limits: every status code and when to retry.