Remediation API - Godiligent API Documentation

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

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 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.

Quick Start

1. Submit an Alert

Provide your screening subject and hits:

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:

{
  "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), 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

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 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.
`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.

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.

Store Alert IDs

Persist the returned id for audit trails and result retrieval.

Duplicate Prevention

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.

Example: Business Entity

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 — Retrieve full resolution results
Working with Webhooks — Set up alert_remediated notifications
Securing Webhooks — Verify webhook signatures
Name Screening Guide — AI remediation overview

Getting Started

​Overview

​Quick Start

​1. Submit an Alert

​2. Receive Webhook Notification

​3. Retrieve Results

​Request Reference

​Alert Fields

​Hit Fields

​Subject Fields

​Hit Profile Fields

​Actions Reference

​Status Codes

​Configuration

​Best Practices

​Use Stable Profile References

​Provide Rich Hit Profiles

​Use Webhooks for Production

​Store Alert IDs

​Duplicate Prevention

​Example: Business Entity

​Next Steps

Overview

Quick Start

1. Submit an Alert

2. Receive Webhook Notification

3. Retrieve Results

Request Reference

Alert Fields

Hit Fields

Subject Fields

Hit Profile Fields

Actions Reference

Status Codes

Configuration

Best Practices

Use Stable Profile References

Provide Rich Hit Profiles

Use Webhooks for Production

Store Alert IDs

Duplicate Prevention

Example: Business Entity

Next Steps