> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deepidv.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Adverse Media

> Screen individuals for negative news and legal mentions

```
POST /v1/screening/adverse-media
```

Starts an **asynchronous** adverse-media check across news, court records, and watchlist databases. Because the scan fans out across multiple vendors, the request returns immediately with `202 Accepted` and a `jobId` — poll [`GET /v1/async-jobs/{jobId}`](/api-reference/async-jobs/get-async-job) to retrieve the result once it's ready.

<Note>
  This endpoint returns a job reference, **not** the screening result. The result
  is delivered through the async-jobs polling endpoint.
</Note>

## Request

### Headers

| Header            | Required | Description                                                                                                        |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `x-api-key`       | Yes      | Your API key                                                                                                       |
| `Content-Type`    | Yes      | `application/json`                                                                                                 |
| `Idempotency-Key` | No       | Client-supplied key. Reusing a key returns the existing job (`200`) instead of queuing a new one — safe on retries |

### Body parameters

| Parameter     | Type   | Required | Description                                                     |
| ------------- | ------ | -------- | --------------------------------------------------------------- |
| `email`       | string | Yes      | Individual's email address                                      |
| `firstName`   | string | Yes      | Individual's first name (1–255 chars)                           |
| `lastName`    | string | Yes      | Individual's last name (1–255 chars)                            |
| `dateOfBirth` | string | Yes      | Date of birth in `YYYY-MM-DD` format                            |
| `country`     | string | No       | ISO 3166-1 alpha-2 country code (e.g. `US`) to focus the search |

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.deepidv.com/v1/screening/adverse-media \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
    -d '{
      "email": "applicant@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "dateOfBirth": "1980-01-15",
      "country": "US"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.deepidv.com/v1/screening/adverse-media", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "YOUR_API_KEY",
      "Idempotency-Key": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    },
    body: JSON.stringify({
      email: "applicant@example.com",
      firstName: "John",
      lastName: "Doe",
      dateOfBirth: "1980-01-15",
      country: "US",
    }),
  });

  const { jobId } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.deepidv.com/v1/screening/adverse-media",
      headers={
          "Content-Type": "application/json",
          "x-api-key": "YOUR_API_KEY",
          "Idempotency-Key": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      },
      json={
          "email": "applicant@example.com",
          "firstName": "John",
          "lastName": "Doe",
          "dateOfBirth": "1980-01-15",
          "country": "US",
      },
  )

  job_id = response.json()["jobId"]
  ```
</CodeGroup>

## Idempotency

Supply an optional `Idempotency-Key` header to make retries safe. The first request with a given key queues the job and returns `202`. Any subsequent request with the **same key** returns `200` with the **existing** job reference instead of starting a duplicate scan. Use a unique key (e.g. a UUID) per logical screening request.

## Response

### 202 — Accepted (new job queued)

### 200 — Existing job returned (reused `Idempotency-Key`)

Both responses share the same body shape:

| Field     | Type   | Description                                                        |
| --------- | ------ | ------------------------------------------------------------------ |
| `jobId`   | string | Identifier to poll for the result via `GET /v1/async-jobs/{jobId}` |
| `status`  | string | Job status — one of `pending`, `processing`, `ready`, `failed`     |
| `message` | string | Human-readable acknowledgement                                     |

### Error responses

| Status             | Description                               |
| ------------------ | ----------------------------------------- |
| `400 Bad Request`  | Request body failed schema validation     |
| `401 Unauthorized` | API key is invalid                        |
| `403 Forbidden`    | API key is missing or resource not in org |
| `404 Not Found`    | Referenced resource was not found         |
| `500 Server Error` | Unexpected server error                   |

<ResponseExample>
  ```json 202 theme={null}
  {
    "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "pending",
    "message": "Adverse media check queued. Poll GET /v1/async-jobs/{jobId} for the result."
  }
  ```
</ResponseExample>

## Result shape

Once the job reaches `ready`, the async-jobs endpoint returns the screening result in its `result` field:

| Field                 | Type    | Description                                           |
| --------------------- | ------- | ----------------------------------------------------- |
| `totalHits`           | integer | Total number of findings                              |
| `riskLevel`           | string  | Overall risk — `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL` |
| `riskScore`           | integer | Numeric risk score `0–100`                            |
| `summary`             | string  | Human-readable summary of the findings                |
| `findings`            | array   | Individual findings (see below)                       |
| `exposuresByCategory` | object  | Hit counts and article lists bucketed by category     |

Each entry in `findings` has the following shape:

| Field         | Type           | Description                                                              |
| ------------- | -------------- | ------------------------------------------------------------------------ |
| `findingId`   | string         | Unique identifier for the finding                                        |
| `severity`    | string         | `MEDIUM`, `HIGH`, or `CRITICAL`                                          |
| `category`    | string         | Adverse-media category (e.g. `financial_crime`, `terrorism`)             |
| `title`       | string         | Short title of the finding                                               |
| `detail`      | string         | Longer description                                                       |
| `sourceUrl`   | string \| null | Link to the source article/record                                        |
| `sourceName`  | string \| null | Normalized publisher/source name                                         |
| `articleDate` | string \| null | Publication date of the source, if known                                 |
| `confidence`  | number         | Match confidence `0–1`                                                   |
| `confirmedBy` | array          | Source types that corroborate the finding (e.g. `news`, `court-records`) |