Skip to main content
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

​
Accepted Labels

For INDIVIDUAL entities:
  • first_name - First name (required if not using full_name)
  • last_name - Last name (required if not using full_name)
  • full_name - Full name (required if not using first_name and last_name)
  • entity_type - Must be “INDIVIDUAL” (optional, defaults to INDIVIDUAL)
  • date_of_birth - Date of birth in YYYY-MM-DD format
  • place_of_birth - Place of birth
  • country_code - Country code
For BUSINESS entities:
  • name - Business name (required)
  • entity_type - Must be “BUSINESS”
  • country_code - Country code
  • company_identifier - Company registration number

​
Examples

Individual with full name: 
{
  "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"}
  ]
}
Individual with first and last name: 
{
  "reference": "CUST-2024-002",
  "input": [
    {"label": "first_name", "value": "John"},
    {"label": "last_name", "value": "Smith"},
    {"label": "entity_type", "value": "INDIVIDUAL"},
    {"label": "place_of_birth", "value": "New York"}
  ]
}
Business entity: 
{
  "reference": "CUST-2024-003",
  "input": [
    {"label": "name", "value": "Acme Corporation"},
    {"label": "entity_type", "value": "BUSINESS"},
    {"label": "company_identifier", "value": "123456789"},
    {"label": "country_code", "value": "US"}
  ]
}

​
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: