Create Search - Godiligent API Documentation

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"
}

{
  "errors": [
    {
      "path": [
        "<string>"
      ],
      "message": "<string>",
      "code": "<string>"
    }
  ]
}

POST

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"
}

{
  "errors": [
    {
      "path": [
        "<string>"
      ],
      "message": "<string>",
      "code": "<string>"
    }
  ]
}

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:

Generate a unique search ID
Initialize the search with status PENDING
Query the configured screening provider
Populate hits array with any matches found
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:

Check search status with GET /name-screenings/searches/
Retrieve hits from the search response
Monitor provider query progress

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

Option 1
Option 2

Show child attributes

Response

Search created successfully

string<uuid>

Search ID (UUID)

Example:

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

​Behavior

​Workflow

Authorizations

Body

Response

Behavior

Workflow