Skip to main content
POST
/
name-screening
/
searches
Create a screening search
curl --request POST \
  --url https://api.godiligent.ai/v1/name-screening/searches \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "reference": "CUST-2024-001",
  "input": [
    {
      "label": "Name",
      "value": "John Doe"
    }
  ]
}
'
{
  "id": "d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4"
}
Creates a name screening search and initiates provider queries. The search will return hits directly when matches are found by the configured provider.

​
Behavior

  • New searches begin with status PENDING and transition to COMPLETED or FAILED
  • Provider queries run asynchronously and populate hits when matches are found
  • Search IDs are UUIDs that can be used with the Get Search endpoint

​
Request Body

The request requires:
  • reference: Unique identifier for the search (max 200 characters)
  • input: Array of profile fields with label and value pairs
Example: 
{
  "reference": "CUST-2024-001",
  "input": [
    {"label": "Name", "value": "John Doe"},
    {"label": "DOB", "value": "1980-01-15"}
  ]
}

​
Workflow

After creating a search, the system will:
  1. Generate a unique search ID
  2. Initialize the search with status PENDING
  3. Query the configured screening provider
  4. Populate hits array with any matches found
  5. Update search status to COMPLETED
If the provider query fails, the search status becomes FAILED.

​
Response

The response contains only the search ID: 
{
  "id": "d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4"
}
Use this ID to:

Authorizations

​
X-API-KEY
string
header
required

API key for authentication

Body

application/json
​
reference
string
required

Unique reference identifier for the search

Maximum string length: 200
Example:

"CUST-2024-001"

​
input
object[]
required

Profile fields for the entity being screened

Minimum array length: 1

Response

Search created successfully

​
id
string<uuid>

Search ID (UUID)

Example:

"d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4"