Skip to main content
POST
/
v1
/
name-screenings
/
searches
curl --request POST \
  --url https://api.godiligent.ai/v1/name-screenings/searches \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "reference": "CUST-2024-001",
  "input": [
    {
      "label": "full_name",
      "value": "John Smith"
    },
    {
      "label": "entity_type",
      "value": "INDIVIDUAL"
    },
    {
      "label": "date_of_birth",
      "value": "1980-01-15"
    },
    {
      "label": "country_code",
      "value": "US"
    }
  ]
}
'
{
  "id": "d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4"
}

​
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

​
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 and trigger a webhook, check Webhooks for more details
If the provider query fails, the search status becomes FAILED. Use this ID to:

Authorizations

​
X-API-KEY
string
header
required

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. Must include entity_type field with value 'INDIVIDUAL' or 'BUSINESS'. Field restrictions apply based on entity type. Labels are normalized to uppercase internally. For INDIVIDUAL: must include either full_name OR both first_name and last_name. For BUSINESS: name field is required. date_of_birth must be in YYYY-MM-DD format.

Minimum array length: 1

Response

Search created successfully

​
id
string<uuid>

Search ID (UUID)

Example:

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