- Docs
- API reference
- Endpoints and schemas
- KYB API
- Checks
Negative news
The background task, subtask and article objects that carry negative news, and how to read them for each registered entity.
Negative news is an add-on attribute. When you request it, Enigma looks for recent news articles with negative sentiment about each registered entity in the response. The articles arrive in a top-level background_task object, not in data, because they can take longer than the rest of the response. Results that are ready when the POST returns are in the response. Poll GET /v2/kyb/{task_id} for the rest.
Unlike the checks in How checks work, negative news adds no task to risk_summary.tasks, so there is no result to branch on: you read the articles for each registered entity instead. This page defines the objects that carry them. To request negative news and poll for it, see Get negative news.
A background_task with one complete subtask and one illustrative article looks like this, trimmed from Inline and asynchronous results.
{ "background_task": { "id": null, "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" } ] } } } ] }}The background_task object
Section titled “The background_task object”background_task is a top-level field of the response, next to data. It holds the negative news results that were ready when the POST returned, and a task ID for the rest.
idThe task ID to pass to
GET /v2/kyb/{task_id}.nullwhen every result is already insubtasks, or when the background task could not be created. Treat it as an opaque string.statusThe background task status:
pending,completeorfailed. See Status values.subtasksThe results that were ready when the POST returned. Each item has one key,
media, which holds one subtask. In the POST response, every subtask iscomplete. Can be empty.errorPresent only when the background task could not be created. A human-readable description. Do not match on its text.
What the POST returns
Section titled “What the POST returns”background_task |
Meaning | What to do |
|---|---|---|
| Absent | No registered entity matched, or the news lookup failed for every matched entity. The two cases look the same. | Treat every registered entity as having no negative news result. Do not read this as “no negative news found”. |
id is null, no error |
Nothing needs polling. The results are in subtasks, and status is complete. A registered entity whose news lookup failed has no subtask. |
Read subtasks. |
id is set |
Some results are not ready. status is pending, and subtasks holds any results that were already ready. |
Keep subtasks, then poll for the rest. |
id is null, error is present |
The background task could not be created. status is failed and subtasks is empty. The rest of the response is complete. |
To get negative news, send the POST request again later. It is a new request. |
See Inline and asynchronous results for an example of each case.
Subtasks and articles
Section titled “Subtasks and articles”A subtask with a legal_entity_id is the negative news result for that registered entity. A pending subtask is not tied to an entity yet, and it can become several subtasks when it completes. The API calls a registered entity a legal entity in this object, so the entity’s ID is in legal_entity_id. The GET endpoint returns subtasks in the same shape.
The media subtask
Section titled “The media subtask”legal_entity_idThe
idof the registered entity, fromdata.registered_entities[].id.nullwhen the subtask is pending or failed, or when the result is not tied to a registered entity.statusThe subtask status:
pending,completeorfailed.resultPresent when the subtask is complete. Holds one key,
negative_news: an array of article objects, ornullwhen Enigma found no negative news about the entity.errorPresent when the subtask failed. A human-readable description. Do not match on its text.
The article object
Section titled “The article object”Each item in result.negative_news is one news article. Only articles with negative sentiment are returned. Two keys are camelCase, unlike the rest of the API: use sourceName and publishedDate exactly as spelled.
urlThe link to the article.
titleThe article headline.
sentimentAlways
negative, because only negative-sentiment articles are returned. The letter case can vary, so compare it case-insensitively.sourceNameThe publication that ran the article.
publishedDateThe date the article was published, for example
2026-05-22. The format comes from the news provider and is not guaranteed, so parse it defensively.
Enigma passes article fields through from its news providers. A field the provider does not supply is null.
Inline and asynchronous results
Section titled “Inline and asynchronous results”Each tab shows a POST response trimmed to the registered entity id and background_task. The article and the error text are illustrative.
id is null and the article is already in subtasks. The subtask’s legal_entity_id matches the registered entity’s id.
{ "data": { "registered_entities": [ { "id": "4dccd7a5-790c-c4d1-0000-108000000000" } ] }, "background_task": { "id": null, "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" } ] } } } ] }}id is set and nothing is ready yet. Pass id to the GET endpoint and poll for the result.
{ "data": { "registered_entities": [ { "id": "4dccd7a5-790c-c4d1-0000-108000000000" } ] }, "background_task": { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "status": "pending", "subtasks": [] }}The background task could not be created. Everything outside background_task is complete.
{ "data": { "registered_entities": [ { "id": "4dccd7a5-790c-c4d1-0000-108000000000" } ] }, "background_task": { "id": null, "status": "failed", "error": "failed to create media task; the synchronous KYB data is complete. Retry later.", "subtasks": [] }}Interpret the results
Section titled “Interpret the results”After you merge the POST and GET results, find the subtask whose legal_entity_id matches each registered entity’s id, and read it as follows.
| Case | What you see | Meaning |
|---|---|---|
| Articles | A complete subtask with the entity’s id in legal_entity_id, and an array in result.negative_news |
Enigma found negative news about the entity. The articles are in result.negative_news. |
| No articles | A complete subtask with the entity’s id in legal_entity_id, and result.negative_news is null |
Enigma found no negative news about the entity. |
| Failed | A subtask whose status is failed. Its legal_entity_id is null. |
A lookup did not finish. error describes the problem but not which entity it was for. |
| No entity ID | Any other subtask whose legal_entity_id is null, including a complete one |
It tells you nothing about any registered entity. |
| Missing | No complete subtask carries the entity’s id, or the response has no background_task |
Enigma has no negative news result for the entity. |
Status values
Section titled “Status values”background_task.status and each subtask’s status are pending, complete or failed. Status values on the GET page gives the rule for each and what each means.
Related
Section titled “Related”- How checks work: the tasks in
risk_summary.tasks, which negative news does not add to. - Get negative news: request negative news and poll for it.
GET /v2/kyb/{task_id}: polling, status values and status codes.- Add-ons:
attrs,productsand account enablement. - Registered entities: the entities that
legal_entity_idrefers to.