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

# Remediation API

> Submit externally-screened alerts for AI-powered remediation

<Note>
  **Beta** — This API is under active development. The contract may change based on early adopter feedback. Please contact the team before integrating.
</Note>

The Remediation API enables customers who perform name screening themselves to submit their alerts directly for AI-powered analysis. Instead of Diligent querying a screening provider, you provide the screening subject and hits, and Diligent's AI resolves each hit with evidence-based reasoning.

## Overview

This is a companion to the [Create Search](/api-reference/name-screening/create-search) workflow. Where Create Search screens a subject against a provider's databases and then remediates, the Remediation API skips the provider step — you bring the hits, we bring the AI.

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant API
    participant AI as AI Workflow
    participant Webhook

    Client->>API: POST /name-screenings/alerts/remediate
    API->>Client: Returns { id } (201)
    API->>AI: Enqueue for processing
    AI->>AI: Enrich (registry, web search, articles)
    AI->>AI: Entity resolution + rule engine
    AI->>AI: Generate report + summary
    AI->>Webhook: POST alert_remediated event
    Webhook->>Client: Notification received
    Client->>API: GET /name-screenings/alerts/{id}
    API->>Client: Full resolution results
```

## Quick Start

### 1. Submit an Alert

Provide your screening subject and hits:

```bash theme={null}
curl -X POST https://api.godiligent.ai/v1/name-screenings/alerts/remediate \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "WC-CASE-2026-001",
    "alt_reference": "CUST-SCREENING-42",
    "input": [
      {"label": "full_name", "value": "John Alexander Doe"},
      {"label": "entity_type", "value": "INDIVIDUAL"},
      {"label": "date_of_birth", "value": "1985-03-15"},
      {"label": "country_code", "value": "DE"}
    ],
    "hits": [
      {
        "reference": "WC-RESULT-12345",
        "profile_reference": "WC-ENTITY-789",
        "categories": ["SANCTION"],
        "fields": [
          {"label": "Name", "value": "John A. Doe"},
          {"label": "Date of Birth", "value": "1985-03-15"},
          {"label": "Nationality", "value": "German"},
          {"label": "Listed On", "value": "EU Sanctions List"}
        ]
      },
      {
        "reference": "WC-RESULT-67890",
        "categories": ["PEP"],
        "fields": [
          {"label": "Name", "value": "Jonathan Doe"},
          {"label": "Position", "value": "Member of Parliament"},
          {"label": "Country", "value": "United Kingdom"}
        ]
      }
    ]
  }'
```

**Response:**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "reference": "WC-CASE-2026-001",
  "alt_reference": "CUST-SCREENING-42",
  "hits": [
    { "reference": "WC-RESULT-12345", "profile_reference": "WC-ENTITY-789" },
    { "reference": "WC-RESULT-67890", "profile_reference": "WC-RESULT-67890" }
  ]
}
```

### 2. Receive Webhook Notification

If you have registered a webhook for the `alert_remediated` event (see [Working with Webhooks](/guides/webhooks/working-with-webhooks)), you will receive a notification when processing completes. The payload follows the standard `alert_remediated` format.

Alternatively, poll the GET endpoint until it returns `200`. The endpoint returns `404` until processing is complete. Typical processing time is 10-60 seconds depending on the number of hits and configured enrichments.

### 3. Retrieve Results

```bash theme={null}
curl https://api.godiligent.ai/v1/name-screenings/alerts/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-KEY: your-api-key"
```

The response is identical to the standard [Get Alert](/api-reference/name-screening/get-alert) endpoint. Each hit includes:

* **`action`** — The action taken (e.g. `COMMENT_FALSE_POSITIVE`, `SET_AS_MATCH`)
* **`determination`** — Simplified result: `TRUE_POSITIVE`, `FALSE_POSITIVE`, or `UNRESOLVED`
* **`applied_rule`** — Which rule triggered the action
* **`summary`** — Human-readable explanation of the AI's reasoning
* **`evidences`** — Supporting facts with citations to data sources

## Request Reference

### Alert Fields

| Field           | Type   | Required | Description                                                                   |
| --------------- | ------ | -------- | ----------------------------------------------------------------------------- |
| `reference`     | string | Yes      | Provider reference for the alert (e.g. case ID from your screening provider). |
| `alt_reference` | string | No       | Your own client reference for the same alert (e.g. internal case number).     |
| `input`         | array  | Yes      | Subject profile as label/value pairs. See [Subject Fields](#subject-fields).  |
| `hits`          | array  | Yes      | Screening hits to remediate. At least one required.                           |

### Hit Fields

| Field               | Type      | Required | Description                                                                                                                                                                                                                                            |
| ------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `reference`         | string    | Yes      | Provider reference for this hit (e.g. result ID or match ID). Must be unique within the alert.                                                                                                                                                         |
| `profile_reference` | string    | No       | Provider's unique reference for the matched profile/entity. May differ from `reference` — some providers use separate IDs for the match result vs the underlying entity. Enables enrichment caching across alerts. Defaults to `reference` if omitted. |
| `categories`        | string\[] | Yes      | One or more of: `SANCTION`, `PEP`, `MEDIA`.                                                                                                                                                                                                            |
| `fields`            | array     | Yes      | Hit entity profile as label/value pairs. See [Hit Profile Fields](#hit-profile-fields).                                                                                                                                                                |

### Subject Fields

The `input` array accepts freeform label/value pairs. The AI uses LLM-based extraction, so exact labels are flexible. The following are recommended for best results:

**Individuals:**

| Label            | Example                | Notes                                        |
| ---------------- | ---------------------- | -------------------------------------------- |
| `full_name`      | `"John Alexander Doe"` | Full name, or use `first_name` + `last_name` |
| `first_name`     | `"John"`               | Given name (alternative to `full_name`)      |
| `last_name`      | `"Doe"`                | Family name (alternative to `full_name`)     |
| `entity_type`    | `"INDIVIDUAL"`         | `INDIVIDUAL` or `BUSINESS`                   |
| `date_of_birth`  | `"1985-03-15"`         | ISO 8601 (YYYY-MM-DD) or year only (YYYY)    |
| `place_of_birth` | `"Munich, Germany"`    | Freeform                                     |
| `country_code`   | `"DE"`                 | ISO alpha-2, alpha-3, or full name           |

**Businesses:**

| Label                | Example                | Notes                          |
| -------------------- | ---------------------- | ------------------------------ |
| `name`               | `"Acme Holdings GmbH"` | Full name including legal form |
| `entity_type`        | `"BUSINESS"`           |                                |
| `country_code`       | `"AT"`                 | Country of registration        |
| `company_identifier` | `"FN 123456a"`         | Registration number, LEI, etc. |

### Hit Profile Fields

Hit `fields` are freeform — use whatever labels your provider gives you. Common examples:

| Label           | Description                       |
| --------------- | --------------------------------- |
| `Name`          | Entity name as listed             |
| `Date of Birth` | DOB if available                  |
| `Nationality`   | Nationality or citizenship        |
| `Country`       | Country of origin or registration |
| `Position`      | Political or corporate position   |
| `Listed On`     | Sanctions list or source          |
| `AKA`           | Aliases / also-known-as           |

## Actions Reference

The AI assigns one of these actions to each hit based on evidence and your configured rules:

| Action                   | Determination    | Description                                 |
| ------------------------ | ---------------- | ------------------------------------------- |
| `SET_AS_MATCH`           | `TRUE_POSITIVE`  | High-confidence match.                      |
| `COMMENT_MATCH`          | `TRUE_POSITIVE`  | Likely match — review recommended.          |
| `DO_NOTHING`             | `UNRESOLVED`     | Insufficient evidence to decide.            |
| `COMMENT_FALSE_POSITIVE` | `FALSE_POSITIVE` | Likely false positive — review recommended. |
| `SET_AS_FALSE_POSITIVE`  | `FALSE_POSITIVE` | High-confidence false positive.             |

## Status Codes

| Code  | Description                                                             |
| ----- | ----------------------------------------------------------------------- |
| `201` | Alert accepted for remediation.                                         |
| `400` | Validation error (missing fields, invalid format). See `details` array. |
| `404` | Customer configuration not found. Rules must be configured first.       |
| `500` | Internal server error.                                                  |

## Configuration

Before using this endpoint, your account needs a name screening configuration with:

* **Rules** — Define how evidence maps to actions
* **Segments** (optional) — Category-specific rule sets (e.g. stricter rules for sanctions)
* **Enrichments** — Which external sources to consult (registry, web search, articles)

Configuration is managed through the Diligent dashboard. Contact support for setup.

## Best Practices

### Use Stable Profile References

If you screen the same entity across multiple alerts, provide a consistent `profile_reference` on the hit. This enables Diligent to cache enrichment data (web searches, registry lookups) and significantly speed up subsequent remediations.

### Provide Rich Hit Profiles

The more data you include in hit `fields`, the better the AI can resolve. Name alone produces weaker evidence than name + DOB + nationality.

### Use Webhooks for Production

Polling works for development, but register for the `alert_remediated` webhook event for production integrations. See [Working with Webhooks](/guides/webhooks/working-with-webhooks).

### Store Alert IDs

Persist the returned `id` for audit trails and result retrieval.

### Duplicate Prevention

<Warning>
  **Not idempotent** — Submitting the same `reference` twice will create a new alert each time. If you need to prevent duplicates, check for an existing alert by its `reference` before resubmitting.
</Warning>

## Example: Business Entity

```bash theme={null}
curl -X POST https://api.godiligent.ai/v1/name-screenings/alerts/remediate \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "CA-SEARCH-2026-002",
    "alt_reference": "CUST-KYB-99",
    "input": [
      {"label": "name", "value": "Acme Holdings GmbH"},
      {"label": "entity_type", "value": "BUSINESS"},
      {"label": "country_code", "value": "AT"},
      {"label": "company_identifier", "value": "FN 123456a"}
    ],
    "hits": [
      {
        "reference": "CA-MATCH-456",
        "categories": ["SANCTION"],
        "fields": [
          {"label": "Name", "value": "Acme Holdings Ltd"},
          {"label": "Country of Registration", "value": "Cyprus"},
          {"label": "Listed On", "value": "OFAC SDN"}
        ]
      }
    ]
  }'
```

## Next Steps

* [Get Alert API Reference](/api-reference/name-screening/get-alert) — Retrieve full resolution results
* [Working with Webhooks](/guides/webhooks/working-with-webhooks) — Set up `alert_remediated` notifications
* [Securing Webhooks](/guides/webhooks/securing-webhooks) — Verify webhook signatures
* [Name Screening Guide](/guides/name-screening/guide) — AI remediation overview