Skip to main content
The Name Screening API enables you to screen individuals and organizations against global watchlists, sanctions lists, PEP (Politically Exposed Persons) databases and adverse media. In addition, there is an automated remediation engine which performs additional registry and other checks. This guide walks you through the complete workflow.

​
Overview

Name screening is an asynchronous process that involves:
  1. Creating an alert - Submit profile information for screening
  2. Provider processing - The configured screening provider (World Check, ComplyAdvantage, or LexisNexis) processes the alert
  3. Additional data gathering - Additional data is retrieved (registry information etc…)
  4. Automated remediation - Automated remediation is performed
You can retrieve the complete alert in its current state at any time by retrieving it by it’s ID. Optionally, you can receive webhook notifications that you can use to trigger fetch and update events in your own systems.

​
Quick Start

​
1. Create an Alert

Submit profile information to initiate screening: 
curl -X POST https://api.godiligent.ai/name-screening/alerts \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "CUSTOMER-2024-001",
    "profile": [
      {"label": "Name", "value": "John Doe"},
      {"label": "DOB", "value": "1980-01-15"},
      {"label": "Country", "value": "United States"}
    ]
  }'
Response: 
{
  "id": "d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4"
}
The alert begins in UNRESOLVED status with UNREMEDIATED remediation status. Save the returned id for subsequent queries. For asynchronous notifications when screening results are available, register a webhook using the existing webhook registration mechanism. Supported Event (Coming Soon):
  • name_screening_alert_updated - Triggered when new hits are found or alert status changes
Example Webhook Payload: 
{
  "headers": {
    "X-Event-Name": "NAME_SCREENING_ALERT_UPDATED",
    "X-Target-type": "NAME_SCREENING_ALERT",
    "X-Customer-Id": "your-customer-id"
  },
  "payload": {
    "alert_id": "d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4",
    "reference": "CUSTOMER-2024-001",
    "status": "UNRESOLVED",
    "hit_count": 3,
    "updated_at": "2024-10-02T14:30:00Z"
  }
}
See Securing Webhooks for verification best practices.

​
3. Retrieve Alert Details

Query the alert to review screening hits: 
curl -X GET https://api.godiligent.ai/name-screening/alerts/d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4 \
  -H "X-API-KEY: your-api-key"
Response: 
{
  "id": "d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4",
  "reference": "CUSTOMER-2024-001",
  "status": "UNRESOLVED",
  "profile": [
    {"label": "Name", "value": "John Doe"},
    {"label": "DOB", "value": "1980-01-15"}
  ],
  "hits": [
    {
      "reference": "WC-12345",
      "status": "UNRESOLVED",
      "source_types": ["SANCTION"],
      "profile": [
        {"label": "Primary Name", "value": "JOHN DOE"},
        {"label": "Provider Match Score", "value": "95.2"}
      ],
      "articles": [
        {
          "url": "https://example.com/sanctions-article",
          "content": "Article content..."
        }
      ],
      "remediation": null
    }
  ],
  "comments": [],
  "createdAt": "2024-10-02T12:00:00Z",
  "updatedAt": "2024-10-02T14:30:00Z"
}

​
Workflow Diagram

​
Understanding Hits

Each alert can contain multiple hits - potential matches from screening providers. Each hit includes:
  • Reference: Provider’s unique identifier for the match
  • Status: UNRESOLVED, FALSE_POSITIVE, or TRUE_POSITIVE
  • Source Types: Origin of the match (e.g., SANCTION, WATCHLIST, PEP, MEDIA)
  • Profile: Match details including confidence scores
  • Articles: Supporting evidence and news articles
  • Remediation: Analysis and decision on the match

​
Hit Statuses

StatusDescription
UNRESOLVEDPending review - requires analyst decision
FALSE_POSITIVENot a true match - different person/entity
TRUE_POSITIVEConfirmed match - requires action

​
Alert Statuses

StatusDescription
UNRESOLVEDOne or more hits pending review
RESOLVEDAll hits have been reviewed and resolved

​
Remediation Status

StatusDescription
UNREMEDIATEDContains unresolved hits requiring review
REMEDIATEDAll hits have been resolved (marked as false/true positive)

​
Best Practices

​
1. Use Unique References

Always use unique, meaningful references for your alerts. If you submit the same reference twice, the API returns the existing alert ID instead of creating a duplicate.

​
2. Poll Responsibly

If not using webhooks, poll the alert endpoint at reasonable intervals (e.g., every 30-60 seconds) rather than continuously.

​
3. Store Alert IDs

Persist alert IDs in your system linked to your customer records for future reference and audit trails.

​
4. Review All Hits

Even low-confidence matches should be reviewed, as automated scoring may not capture all risk factors.

​
5. Document Decisions

Use the comments and remediation features to document why hits were marked as false or true positives for compliance and audit purposes.

​
Provider Configuration

The screening provider (World Check, ComplyAdvantage, or LexisNexis) is determined from your customer configuration. Contact support to configure or change your screening provider.

​
Next Steps