API Version 1#

Order workflow#

The order workflow of a v1 API integration is as follows:

Client obtains an OAuth 2.0 access token by authorizing against the token endpoint using the credentials provided by Choice Screening.
Client optionally calls the ping endpoint to validate that its access token is valid.
Client calls the packages endpoint to view a list of packages available for ordering.
Client places an order with a package number obtained from the packages endpoint using the order endpoint and observes the response code and order response body to ensure that the order request was submitted successfully.
Client either polls the order status endpoint OR utilizes the order callback URL to receive an order response body containing the most recent status and result information for the order.
Client calls the report endpoint to retrieve an HTML response representing a styled, user-friendly order report. The order response body also includes a report URL that provides the same data as this endpoint.

Step 1 - Obtain an Access Token#

All Choice Screening API endpoints require a valid OAuth 2.0 access token. A token can be retrieved using the token endpoint.

Token endpoint#

Token endpoint HTTP method#

POST

Token endpoint request URL#

{environment}/connect/token

where {environment} is

https://stageauth.choicescreening.com for STAGING/TEST
https://csauth.choicescreening.com for PRODUCTION

Token endpoint request headers#

Content-Type: application/x-www-form-urlencoded

Token endpoint request body#

grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}&scope={scopes}

where {client_id}, {client_secret} and {scopes} are values provided by Choice Screening

Token endpoint response#

200 OK

{
    "access_token": "{access_token}",
    "expires_in": 1209600,
    "token_type": "Bearer"
}

where expires_in is how many seconds the token is valid for.

Unauthorized requests#

If a client makes a request that does not include an OAuth 2.0 access token, the server returns the following status:

401 Unauthorized

The server will sometimes (but not always) return a response, shown below. We recommend that the client should handle invalid token errors using the 401 Unauthorized HTTP response code instead of the response json:

{
    "message": "Authorization has been denied for this request."
}

Step 2 - Verify Auth Token against Ping endpoint#

The ping endpoint allows the client to verify that an access token is still valid. This endpoint is generally used for testing and/or debugging.

Ping endpoint HTTP method#

GET

Ping endpoint request URL#

{apiBaseUrl}/{clientCode}/ping

where {apiBaseUrl} is

https://stageapi.choicescreening.com for STAGING/TEST
https://csapi.choicescreening.com for PRODUCTION

and {clientCode} is provided by Choice Screening.

Ping endpoint request headers#

Authorization: Bearer {access_token}

Ping endpoint response#

200 OK

Pong

Step 3 - Obtain a Package Number from the Packages endpoint#

The packages endpoint will return all of the background screening packages that are available for running. The packages provided by this endpoint are used when ordering searches using the order endpoint.

Packages endpoint HTTP method#

GET

Packages endpoint request URL#

{apiBaseUrl}/{clientCode}/packages

where {apiBaseUrl} is

https://stageapi.choicescreening.com for STAGING/TEST
https://csapi.choicescreening.com for PRODUCTION

and {clientCode} is provided by Choice Screening.

Packages endpoint request headers#

Authorization: Bearer {access_token}

Packages endpoint response#

200 OK

{
    "packages": [
        {
            "packageNumber": "string",
            "packageName": "string",
            "packageDescription": "string",
            "packagePrice": 0
        },
        {
            "packageNumber": "string",
            "packageName": "string",
            "packageDescription": "string",
            "packagePrice": 0
        },
        {
            "packageNumber": "string",
            "packageName": "string",
            "packageDescription": "string",
            "packagePrice": 0
        }
    ]
}

Of particular importance is the packageNumber field, which is used in the items field of the order endpoint request model.

Step 4 - Place an order on the Order endpoint#

The order endpoint allows the client to run background screening packages provided by the packages endpoint.

Order endpoint request URL#

{apiBaseUrl}/{clientCode}/order

where {apiBaseUrl} is

https://stageapi.choicescreening.com for STAGING/TEST
https://csapi.choicescreening.com for PRODUCTION

and {clientCode} is provided by Choice Screening.

Order endpoint request headers#

Authorization: Bearer {access_token}

Placing a new order#

Note: Refer to the order endpoint request model documentation for a complete description of all order fields available for use.

Minimum data requirements for placing a new order#

The data required in order to submit an order is dependent upon whether or not you intend to utilize Choice Screening's Online Consent Form.

The business advantages and caveats of utilizing Choice Screening's Online Consent Form are out of scope for this document. We recommend consulting your Choice Screening Account Executive to determine whether using our Online Consent Form makes the most sense for your needs.

When using Choice Screening's Online Consent Form, most of the data required for placing an order will be collected directly from the applicant via the form, thus the minimum data requirements for ordering are as follows:

"isNew": true,

Place a NEW order

"isConsent": true,

Use Choice Screening's Online Consent Form

"applicant": { 
  "firstName": "JOHN", 
  "lastName": "DOE",
  ...

Applicant first and last name

"applicant": {
  ...
  "consent": { 
    "applicantEmail": "JOHNDOE@EXAMPLE.COM" 
    } 
  }
}

Applicant email address where we will send the consent form to

"items": { 
  "item": [{ 
    "itemNumber": { 
      "type": "Package", 
      "value": "{packageNumber}" 
      } 
    }] 
  }

The {packageNumber} of the desired package returned from the packages endpoint.

Here is a sample JSON payload for placing a new order that utilizes Choice Screening's Online Consent Form:

{
  "order": {
    "isNew": true,
    "isConsent": true,
    "applicant": {
      "firstName": "JOHN",
      "lastName": "DOE",
      "consent": {
        "applicantEmail": "JOHNDOE@EXAMPLE.COM"
      }
    },
    "items": {
      "item": [
        {
          "itemNumber": {
            "type": "PACKAGE",
            "value": "{packageNumber}"
          }
        }
      ]
    }
  }
}

When ordering without Choice Screening's Online Consent Form, all data required by the package being requested must be present in the order request payload at the time of ordering.

The common required fields:

"isNew": true,

Place a NEW order

"isConsent": false,

Do NOT use Choice Screening's Online Consent Form

"applicant": { 
  "firstName": "JOHN", 
  "middleName": "MIDDLE", 
  "lastName": "DOE",
}

Applicant first, middle and last name. Note that while middle name is not explicitly required, providing it increases search accuracy.

"dob": {
  "month": 7,
  "day": 8,
  "year": 1990
},

Applicant date of birth

"items": { 
  "item": [{ 
    "itemNumber": { 
      "type": "PACKAGE", 
      "value": "{packageNumber}" 
    } 
  }] 
}

The {packageNumber} of the desired package returned from the packages endpoint.

Other required fields are dependent upon the type of search being run.

National/Federal Criminal

{
  "order": {
    "isNew": true,
    "isConsent": false,
    "applicant": {
      "firstName": "JOHN",
      "middleName": "SAMPLE",
      "lastName": "DOE",
      "dob": {
        "month": 7,
        "day": 8,
        "year": 1990
      },      
      "ssn": "123456789"
    },
    "items": {
      "item": [
        {
          "itemNumber": {
            "type": "PACKAGE",
            "value": "{packageNumber}"
          }
        }
      ]
    }
  }
}

Credit

{
  "order": {
    "isNew": true,
    "isConsent": false,
    "applicant": {
      "firstName": "JOHN",
      "middleName": "SAMPLE",
      "lastName": "DOE",
      "dob": {
        "month": 7,
        "day": 8,
        "year": 1990
      },      
      "ssn": "123456789",
      "address": "123 SAMPLE ST.",
      "city": "EXAMPLETOWN",
      "state": "CO",
      "zipCode": "81212"
    },
    "items": {
      "item": [
        {
          "itemNumber": {
            "type": "PACKAGE",
            "value": "{packageNumber}"
          }
        }
      ]
    }
  }
}

Motor Vehicle

{
  "order": {
    "isNew": true,
    "isConsent": false,
    "applicant": {
      "firstName": "JOHN",
      "middleName": "SAMPLE",
      "lastName": "DOE",
      "dob": {
        "month": 7,
        "day": 8,
        "year": 1990
      },
      "driversLicenseNumber": "A987654321"      
    },
    "items": {
      "item": [
        {
          "itemNumber": {
            "type": "PACKAGE",
            "value": "{packageNumber}"
          },
          "stateCode": "CO"
        }
      ]
    }
  }
}

Drug Testing

{
  "order": {
    "isNew": true,
    "isConsent": false,
    "applicant": {
      "firstName": "JOHN",
      "middleName": "SAMPLE",
      "lastName": "DOE",
      "dob": {
        "month": 7,
        "day": 8,
        "year": 1990
      },      
      "ssn": "123456789",
      "address": "123 SAMPLE ST.",
      "city": "EXAMPLETOWN",
      "state": "CO",
      "zipCode": "81212",
      "email": {
        "applicants": "JOHNDOE@EXAMPLE.COM"
      }
    },
    "items": {
      "item": [
        {
          "itemNumber": {
            "type": "PACKAGE",
            "value": "{packageNumber}"
          }
        }
      ]
    }
  }
}

Abuse

SSN Verification

{
  "order": {
    "isNew": true,
    "isConsent": false,
    "applicant": {
      "firstName": "JOHN",
      "middleName": "SAMPLE",
      "lastName": "DOE",
      "dob": {
        "month": 7,
        "day": 8,
        "year": 1990
      },      
      "ssn": "123456789",
      "address": "123 SAMPLE ST.",
      "city": "EXAMPLETOWN",
      "state": "CO",
      "zipCode": "81212"
    },
    "items": {
      "item": [
        {
          "itemNumber": {
            "type": "PACKAGE",
            "value": "{packageNumber}"
          }
        }
      ]
    }
  }
}

Note: Refer to the model documentation for a full listing of each search type available as well as its corresponding sample request model and response model.

Step 5 - Check the status of your order#

There are three options available for retrieving the status of your order. These are, in order of simplicity and lowest development time:

Polling the order status endpoint.
Utilizing an order callback URL.
Establishing a custom callback.

Option 1 - Polling the Order Status endpoint#

The simplest way to obtain status information about your order is to perform an authenticated GET request against our order status endpoint. This will return a payload containing status information about the order you are requesting.

Order Status endpoint HTTP method#

GET

Order Status endpoint request URL#

{apiBaseUrl}/{clientCode}/order/status/{orderId}

where {apiBaseUrl} is

https://stageapi.choicescreening.com for STAGING/TEST
https://csapi.choicescreening.com for PRODUCTION

{clientCode} is provided by Choice Screening

and {orderId} is the order you are obtaining the status of.

Order Status endpoint request headers#

Authorization: Bearer {access_token}

Order Status endpoint response#

200 OK

{
  "order": {
    "id": 1234567,
    "isError": false,
    "isComplete": false,
    "status": "Pending",
    "statusDateTime": "2020-08-18T05:27:48.1561984Z",
    "applicant": {
      "firstName": "JOHN",
      "middleName": "SAMPLE",
      "lastName": "DOE",
      "reference": ""
    },
    "items": {
      "item": [
        {
          "Id": 5123456,
          "line": 1,
          "product": "County Criminal Search (Non-Instant) (FREMONT,CO)",
          "statusId": 1,
          "statusText": "Pending",
          "contents": {
            "response": {
              "pending": {
                "message": "Results are Pending."
              },
              "request": {
                "csRequest": {
                  "state": "CO",
                  "county": "Fremont",
                  "employerID": "12345"
                }
              }
            }
          }
        },
        {
          "Id": 5123457,
          "line": 2,
          "product": "Education Verification",          
          ...
        }
        ...
      ]
    }
  }
}

Overall order status#

Overall order status can be determined by the following fields:

"isError": false

isError signifies if there was an order processing error. An order with status "isError": true cannot be completed as-is and must either be resubmitted with the error fixed, or investigated by Choice Screening customer service.

"isComplete": false

isComplete represents the overall completion status of the order. If "isComplete": true then the all of the order's associated searches have been finished, otherwise if "isComplete": false then the order is still in progress.

"status": "Pending"

status represents the overall status of the order. The value of this status will depend on what searches are included in the overall order, as well as whether or not the ordering company utilizes a hiring matrix. See possible statuses below for valid values.

"statusDateTime": ""2020-08-18T05:27:48.1561984Z"

statusDateTime corresponds to the UTC last date and time that the status value changed.

Note: Refer to the model documentation for a full listing of each search type available as well as its corresponding response model.

Individual search status#

Individual searches within an order are denoted by the item field in the items array returned as part of the Order Status response. Individual search status can be determined by the following fields:

"statusId": 1

statusId corresponds to the status of the individual search. See possible status values below for valid values.

"statusText": "Pending"

statusText is the text representation of the statusId per the possible status values.

Possible status values#

StatusId	Status	Description
0	None	Not started
1	Pending	In progress
2	Review	Complete, contains results recommended for review
3	Passed	Complete, no results / no adverse results
4	Matrix	Complete, flagged according to hiring matrix
5	Complete	Complete, may have informational results
6	Unable to Complete	Unable to complete search as-is

Option 2 - Utilizing an Order Callback URL#

Another simple way to obtain status information about your order is to provide an Order Callback URL in your order request.

In the order endpoint request model that there is a field titled returnUrl:

{
  "order": {
    "isNew": true,
    "id": 0,
    "returnUrl": "https://example.com/choicescreeningcallback",
    "trackingId": "",
...

Our system will submit the same payload provided from the Order Status Endpoint as a POST to the URL provided in returnUrl, if a URL is provided.

NOTE: You must arrange with Choice Screening to properly secure this callback. Common options are BASIC auth over HTTPS, OAuth 2.0 Bearer Tokens, or API keys.

If your implementation requires a custom result payload, consider establishing a Custom Callback.

Option 3 - Custom Callbacks#

If your integration requires very specific result payload, callback schedule or security requirements, please consult with your Choice Screening Account Executive to discuss your needs.

Step 6 - Obtain a report of your order#

Whereas the Order Status endpoint is used to determine the overall status of an order (i.e. whether or not the order is complete), the Order Report endpoint is used to generate an end-user friendly HTML report of the final order result.

The two options for obtaining a report for a user are

Get the report HTML from the Reporting endpoint and display it to the user
Get a signed report URL from the Order Report URL endpoint and redirect the user to the URL

Get the report HTML from the Reporting endpoint#

Reporting endpoint HTTP method#

GET

Reporting endpoint request URL#

{apiBaseUrl}/reporting/get/{orderId}

where {apiBaseUrl} is

https://stageapi.choicescreening.com for STAGING/TEST
https://csapi.choicescreening.com for PRODUCTION

and {orderId} is the order you are obtaining the report of.

Reporting endpoint request headers#

Authorization: Bearer {access_token}

Reporting endpoint response#

200 OK

The response body of the Order Report endpoint is a full HTML document ready for display to the user.

<html lang="en">
  <head>
    <title>Background Screening Report</title>
    ...

Get the report URL from the Order Report URL endpoint#

The report URL that is generated from the Order Report URL is a signed URL with a relatively short expiration. If the URL expires, simply request a new URL from the endpoint with a valid access token.

Order Report URL endpoint HTTP method#

GET

Order Report URL endpoint request URL#

{apiBaseUrl}/{clientCode}/reporturl/{orderId}

where {apiBaseUrl} is

https://stageapi.choicescreening.com for STAGING/TEST
https://csapi.choicescreening.com for PRODUCTION

{clientCode} is provided by Choice Screening

and {orderId} is the order you are obtaining the report of.

Order Report URL endpoint request headers#

Authorization: Bearer {access_token}

Order Report URL endpoint response#

200 OK

{
  "reportUrl": "https://..."
}

API Version 1#

Order workflow#

Step 1 - Obtain an Access Token#

Token endpoint#

Token endpoint HTTP method#

Token endpoint request URL#

Token endpoint request headers#

Token endpoint request body#

Token endpoint response#

Unauthorized requests#

Step 2 - Verify Auth Token against Ping endpoint#

Ping endpoint HTTP method#

Ping endpoint request URL#

Ping endpoint request headers#

Ping endpoint response#

Step 3 - Obtain a Package Number from the Packages endpoint#

Packages endpoint HTTP method#

Packages endpoint request URL#

Packages endpoint request headers#

Packages endpoint response#

Step 4 - Place an order on the Order endpoint#

Order endpoint request URL#

Order endpoint request headers#

Placing a new order#

Minimum data requirements for placing a new order#

Ordering with Choice Screening's Online Consent Form#

Sample new order if using Choice Screening's Online Consent Form#

Ordering without Choice Screening's Online Consent Form#

Sample new order if NOT using Choice Screening's Online Consent Forms#

Step 5 - Check the status of your order#

Option 1 - Polling the Order Status endpoint#

Order Status endpoint HTTP method#

Order Status endpoint request URL#

Order Status endpoint request headers#

Order Status endpoint response#

Overall order status#

Individual search status#

Possible status values#

Option 2 - Utilizing an Order Callback URL#

Option 3 - Custom Callbacks#

Step 6 - Obtain a report of your order#

Get the report HTML from the Reporting endpoint#

Reporting endpoint HTTP method#

Reporting endpoint request URL#

Reporting endpoint request headers#

Reporting endpoint response#

Get the report URL from the Order Report URL endpoint#

Order Report URL endpoint HTTP method#

Order Report URL endpoint request URL#

Order Report URL endpoint request headers#

Order Report URL endpoint response#