Documentation
Start typing to search…

Adding Searches to Orders

Adding new searches to existing orders


The Order API allows you to add additional searches to an existing order after it has been created. This is useful when you need to run supplementary background checks or criminal searches beyond what was included in the original package. With this functionality, you can dynamically expand the scope of an order's screening process without creating a new order.

Overview

Adding a search to an order is accomplished by making a POST request to the /v1/orders/{orderId}/searches endpoint. This endpoint creates a "requested search" that is associated with the specified order. Once created, the search is automatically dispatched to the appropriate vendor for processing, and the results are returned to the order in the same manner as searches that were part of the original package.

It's important to note that adding a search requires you to provide the necessary applicant data for that specific search type. Each search type has its own data requirements, which are validated against a JSON schema before the search is created.

Available Search Types

The following search types can be added to an order:

  • nat+crim - National Criminal Database Search
  • county - County Criminal Records Search
  • ssn - Social Security Number Verification
  • fastTrack - Fast Track Criminal Search
  • aamva - AAMVA Driver's License Verification
  • standardIdVerification - Standard ID Verification

Each search type requires different data fields to be provided in the request body.

Adding a County Criminal Search

A county criminal search is used to search for criminal records in a specific county jurisdiction. This type of search is particularly useful when you need to verify an applicant's criminal history in a particular geographic area where they have lived or worked.

Required Data Fields

When adding a county criminal search, you must provide the following information:

  • ssn - The applicant's Social Security Number
  • firstName - The applicant's first name
  • middleName - The applicant's middle name
  • lastName - The applicant's last name
  • dateOfBirth - The applicant's date of birth (format: YYYY-MM-DD)
  • address - An address object containing location information

The address field can be provided in one of two formats:

Option 1: Full Address (includes all address components)

{
  "firstLine": "409 13th St",
  "secondLine": "Apt 2B",
  "city": "Oakland",
  "state": "CA",
  "zipCode": "94612",
  "county": "Alameda County",
  "country": "US"
}

Option 2: County and State Only (minimum required for county search)

{
  "county": "Alameda County",
  "state": "CA"
}

Example Request

To add a county criminal search to an existing order, send a POST request to the /v1/orders/{orderId}/searches endpoint:

Endpoint:

POST /v1/orders/{orderId}/searches

Request Headers:

Content-Type: application/json
x-api-key: your-api-key

Request Body:

{
  "searchType": "county",
  "data": {
    "ssn": "555-55-5555",
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "Michael",
    "dateOfBirth": "1990-01-15",
    "address": {
      "county": "Alameda County",
      "state": "CA"
    }
  }
}

Example with Full Address:

{
  "searchType": "county",
  "data": {
    "ssn": "555-55-5555",
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "Michael",
    "dateOfBirth": "1990-01-15",
    "address": {
      "firstLine": "409 13th St",
      "secondLine": "",
      "city": "Oakland",
      "state": "CA",
      "zipCode": "94612",
      "county": "Alameda County",
      "country": "US"
    }
  }
}

Response:

{
  "id": "req_search_abc123def456"
}

The response returns the unique identifier for the newly created requested search. You can use this ID to track the search's progress and retrieve its results.

Retrieving Search Results

Once the county criminal search has been added, it will be processed in the background. You can retrieve the search results by making a GET request to the /v1/orders/{orderId}/searches/{searchId} endpoint:

Endpoint:

GET /v1/orders/{orderId}/searches/{searchId}

Response:

{
  "id": "req_search_abc123def456",
  "orderId": "order_123456",
  "status": "RETURNED",
  "createdAt": "2026-01-26T10:30:00Z",
  "updatedAt": "2026-01-26T10:45:00Z",
  "searchType": {
    "id": "search_type_county",
    "name": "county"
  },
  "results": [
    {
      "id": "result_789xyz",
      "requestedSearchId": "req_search_abc123def456",
      "blob": { ... },
      "normalized": { ... },
      "searchType": "COUNTY_CRIMINAL",
      "alert": "CLEAR",
      "detail": null,
      "createdAt": "2026-01-26T10:45:00Z",
      "updatedAt": "2026-01-26T10:45:00Z"
    }
  ]
}

You can also view all searches associated with an order by making a GET request to the /v1/orders/{orderId}/searches endpoint.

Other Search Type Examples

Adding a National Criminal Search

A national criminal search queries nationwide criminal databases to identify potential criminal records across all jurisdictions.

Request Body:

{
  "searchType": "nat+crim",
  "data": {
    "ssn": "555-55-5555",
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "Michael",
    "dateOfBirth": "1990-01-15"
  }
}

Note that the national criminal search does not require an address field, as it searches across all jurisdictions.

Adding an SSN Verification Search

An SSN verification search validates the authenticity of a Social Security Number and verifies that it matches the applicant's identity.

Request Body:

{
  "searchType": "ssn",
  "data": {
    "ssn": "555-55-5555",
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "Michael",
    "dateOfBirth": "1990-01-15",
    "address": {
      "firstLine": "409 13th St",
      "secondLine": "",
      "city": "Oakland",
      "state": "CA",
      "zipCode": "94612",
      "county": "Alameda County",
      "country": "US"
    }
  }
}

The SSN verification search requires a complete address with all address components (firstLine, city, state, zipCode, etc.).

Search Processing and Timing

Once a search is added to an order, it enters the same processing workflow as searches that were part of the original package. The search is dispatched to the appropriate vendor based on the organization's configuration, and the results are processed and normalized upon completion.

The time it takes for a search to return results can vary depending on the search type and the complexity of the records being searched. County criminal searches typically take between 1 to 48 hours, though in some cases they may take up to one week if the county requires manual record retrieval.

The search status will progress through the following states:

  • DISPATCHED - The search has been sent to the vendor and is being processed
  • RETURNED - The search has been completed and results are available
  • DEFERRED - The search has been created but not yet dispatched (used in specific workflow scenarios)

You can monitor the search status by retrieving the order details or by using the search-specific endpoint described above.

Postback Notifications

If you provided a postbackWebhookURL when creating the order, you will receive a webhook notification when the added search completes and the order status changes. This allows you to be notified immediately when the new search results are available, without needing to poll the API.

The webhook payload will include the updated order details, including all requested searches and their results.

Error Handling

When adding a search to an order, the API validates the provided data against the search type's JSON schema. If the data is invalid or missing required fields, you will receive a 400 Bad Request error with details about which fields are incorrect.

Common errors include:

  • Missing required fields - Ensure all required fields for the search type are provided
  • Invalid data format - Check that dates are in YYYY-MM-DD format and other fields match expected formats
  • Order not found - Verify that the order ID is correct and the order exists
  • Unauthorized - Ensure your API key has permission to access the specified order

If you encounter an error, review the error message and adjust your request accordingly before retrying.

Updated 7 days ago