Order endpoint request model#

The full order request json is below. An explanation of each field follows.

{
  "order": {
    "isNew": true,
    "id": 0,
    "returnUrl": "https://example.com/choicescreeningcallback",
    "trackingId": "",
    "isConsent": false,
    "isNotifyOnComplete": false,
    "applicant": {
      "firstName": "John",
      "middleName": "Charles",
      "lastName": "Doe",
      "dob": {
        "month": 7,
        "day": 8,
        "year": 1990
      },
      "ssn": "123456789",
      "address": "123 Sample St.",
      "city": "Example",
      "state": "CO",
      "zipCode": "80015",
      "driversLicenseNumber": "987654321",
      "reference": "",
      "sex": "",
      "consent": {
        "applicantEmail": "johndoe@example.com",
        "companyCopyEmail": "johndoe@example.com",
        "specialInstructions": ""
      },
      "email": {
        "applicants": "johndoe@example.com",
        "sendCopyTo": "johndoe@example.com"
      },
      "phone": "555-555-5555"
    },
    "items": {
      "item": [
        {
          "itemNumber": {
            "type": "Product",
            "value": "165"
          },
          "stateCode": "",
          "county": "",
          "country": "",
          "jurisdiction": "",
          "mvrCode": "",
          "alias": {
            "firstName": "",
            "middleName": "",
            "lastName": ""
          },
          "employerId": "12345",
          "passportNumber": "",
          "passportCountryCode": "",
          "applicantEmail": "",
          "applicantPhone": "",
          "packageProducts": {
            "packageProduct": [
              {
                "productNumber": "",
                "stateCode": "",
                "county": "",
                "country": "",
                "jurisdiction": "",
                "mvrCode": "",
                "employerId": "",
                "applicantPhone": "",
                "applicantEmail": "",
                "alias": {
                  "firstName": "",
                  "middleName": "",
                  "lastName": ""
                }
              }
            ]
          }
        }
      ]
    },
    "verifications": {
      "verification": [
        {
          "type": "",
          "education": [
            {
              "schoolId": "",
              "schoolState": "",
              "studentName": "",
              "schoolName": "",
              "schoolLocation": "",
              "schoolType": "",
              "degree": "",
              "major": "",
              "currentStatus": "",
              "degreeMonth": 0,
              "degreeYear": 0,
              "notes": ""
            }
          ],
          "employment": [
            {
              "companyName": "",
              "position": "",
              "city": "",
              "stateCode": "",
              "startMonth": 0,
              "startYear": 0,
              "endMonth": 0,
              "endYear": 0,
              "contactName": "",
              "contactEmail": "",
              "contactPhone": "",
              "contactAuthorized": false,
              "notes": ""
            }
          ],
          "proLic": [
            {
              "licenseType": "",
              "stateCode": "",
              "licenseNumber": "",
              "notes": ""
            }
          ],
          "proRef": [
            {
              "contactName": "",
              "contactPhone": "",
              "contactEmail": "",
              "address": "",
              "city": "",
              "stateCode": "",
              "zipCode": "",
              "notes": ""
            }
          ],
          "personalRef": [
            {
              "contactName": "",
              "contactPhone": "",
              "contactEmail": "",
              "address": "",
              "city": "",
              "stateCode": "",
              "zipCode": "",
              "notes": ""
            }
          ],
          "rentalHistory": [
            {
              "landLord": "",
              "address": "",
              "city": "",
              "stateCode": "",
              "zipCode": "",
              "contactPhone": "",
              "contactEmail": "",
              "startMonth": "",
              "startYear": "",
              "endMonth": "",
              "endYear": ""
            }
          ],
          "dotVerification": [
            {
              "companyName": "",
              "position": "",
              "city": "",
              "stateCode": "",
              "startMonth": 0,
              "startYear": 0,
              "endMonth": 0,
              "endYear": 0,
              "contactName": "",
              "contactEmail": "",
              "contactPhone": "",
              "notes": ""
            }
          ]
        }
      ]
    }
  }
}

Order request model properties#

isNew (boolean, required)#

"isNew": true or false

For placing a new order: true
For adding to existing orders: false

When "isNew": false then the client must specify a valid order id in the id field for this request:

"isNew": false,
"id": 1234567,

id (integer, optional)#

"id": 1234567

When "isNew": false this field is required, it specifies which order id to add to.
When "isNew": true this field is ignored.

returnUrl (string, optional)#

"returnUrl": "https://www.example.com/"

When provided, this is the callback URL that is POSTed to when the order is complete.
Client 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.

trackingId (string, return value)#

"trackingId": ""

When provided, this becomes an external tracking identifier that can be used to track the order back to the integrator's system.

isConsent (boolean, required)#

"isConsent": true or false

When utilizing Choice Screening's online consent form for collecting applicant information and consent to screening: true
When using the online consent form, certain order data becomes optional. Refer to the field descriptions to determine which data fields become optional.
When ordering without Choice Screening's online consent form: false

isNotifyOnComplete (boolean, required)#

"isNotifyOnComplete": true or false

For receiving an email notification when the order is complete: true
For no email notification: false

Applicant request model properties#

The applicant model specifies information about the applicant (or subject) of the background screening search. Note that if an online consent form is used ("isConsent": true), many of these values become optional. The field descriptions below specify when the field is optional for consent form orders.

firstName (string, required)#

"firstName": "John"

The first name of the applicant.

middleName (string, optional)#

"middleName": "Charles"

The middle name of the applicant.

lastName (string, required)#

"lastName": "Doe"

The last name of the applicant.

dob (object, required)#

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

The Date of Birth of the applicant.
month (integer, required)
day (integer, required)
year (integer, required)

ssn (string, varies)#

"ssn": "123456789"

The Social Security Number (SSN) of the applicant.
SSN may be required depending on the package ordered.
When using a consent form SSN is optional, even if the package being ordered requires it.

address (string, varies)#

"address": "123 Sample St."

The street address of the applicant.
Address may be required depending on the package ordered.
When using a consent form address is optional, even if the package being ordered requires it.

sex (string, varies)#

"sex": "M" // or options below

Gender (Sex)	Description
`M`	Male
`F`	Female
`O`	Other
`P`	Prefer Not to Answer

phone (string, varies)#

"phone": "555-555-5555"

The phone number of the applicant.
Phone may be required depending on the package ordered.
When using a consent form phone is optional, even if the package being ordered requires it.

Verifications (History) request model properties#

The Verifications request model specifies information about verification related products, such as employment or education verifications. These are also commonly referred to as employment histories, education histories, etc.

When using a consent form ("isConsent": true), the verification request objects are optional, and any valid values provided in the request are pre-filled into the applicant's consent form.
When NOT using a consent form ("isConsent": false), the verification request objects are required according to the specific verification products contained in the Package(s) being ordered.

Multiple verification objects can be specified in a single request, as shown below:

verification (array, varies)#

"verifications": {
  "verification": [
    {
      "type": "education",
      "education": [
        {
          "schoolName": "",
          ...
        },
        {
          "schoolName": "",
          ...
        }
      ]
    },
    {
      "type": "employment",
      "employment": [
        {
          "companyName": "",
          ...
        },
        {
          "companyName": "",
          ...
        }
      ]
    },
    ...
  ]
}

type (string, required)#

Verification Type must be set according to the verification payload you wish to send

For submitting a verification/history for	type is
Education	`education`
Employment	`employment`
Professional references	`professionalreference`
Personal references	`personalreference`
Professional licenses and certificates	`license`
Department of Transportation	`dot`
Rental	`rental`

The verification payloads are defined as follows:

education ([object], varies)#

Education History Verifications
When using a consent form ("isConsent": true), all fields may be considered optional; any valid values provided in the payload will get preloaded into the applicant's consent form.
When not using a consent form ("isConsent": false), the following fields become required:

Required fields when not using a consent form
schoolName
schoolLocation
schoolType
degree
major

...
  "verification": [
    {
      "type": "education",
      "education": [
        {
          "studentName": "Student 1",
          "schoolName": "College of Learning",
          "schoolLocation": "New York, NY",
          "schoolType": "[see options below]",
          "degree": "[see options below]",
          "major": "Computer Science",
          "currentStatus": "[see options below]",
          "degreeMonth": 12,
          "degreeYear": 2024
        },
        {
          "studentName": "Student 2",
          ... 
        }
      ]
    }
  ],

"schoolType": "None" // or options below

School Type
`None`
`High School`
`GED`
`Vocational`
`College`
`International`

"degree": "None" // or options below

Degree Options
`None`
`Diploma`
`Associate`
`Bachelor`
`Master`
`Doctorate`
`GED`
`Other`
`Certificate`

"currentStatus": "None" // or options below

Current Status
`None`
`Graduated`
`In Progress`
`No Degree`
`Did Not Graduate`

employment ([object], varies)#

Employment History Verifications
When using a consent form ("isConsent": true), all fields may be considered optional; any valid values provided in the payload will get preloaded into the applicant's consent form.
When not using a consent form ("isConsent": false), the following fields become required:

Required fields when not using a consent form
companyName
position
startMonth
startYear
contactName
contactPhone
contactAuthorized

...
  "verification": [
    {
      "type": "employment",
      "employment": [
        {
          "companyName": "Recent Corp",
          "position": "Training Lead",
          "city": "Denver",
          "stateCode": "CO",
          "startMonth": 1,
          "startYear": 2024,
          "endMonth": 0,
          "endYear": 0,
          "contactName": "John Doe",
          "contactEmail": "jdoe@example.com",
          "contactPhone": "555-555-5555",
          "contactAuthorized": true
        },
        {
          "companyName": "Last Corp",
          ...
        }
      ]
    }
  ],

"endMonth": 0,
"endYear": 0

For current employment, endMonth and endYear can be provided as 0.

"contactAuthorized": true or false

Specifies if Choice Screening is authorized to contact the employer provided. Defaults to false.

proLic ([object], varies)#

Professional License and Certificate Verifications
When using a consent form ("isConsent": true), all fields may be considered optional; any valid values provided in the payload will get preloaded into the applicant's consent form.
When not using a consent form ("isConsent": false), the following fields become required:

Required fields when not using a consent form
licenseType
stateCode
licenseNumber

  "verification": [
    {
      "type": "license",
      {
        "proLic": [
          {
            "licenseType": "Colorado Professional Teaching License",
            "stateCode": "CO",
            "licenseNumber": "ABC123"
          },
          {
            "licenseType": "National Board of Professional Teaching Standards Certificate",
            ...
          }
        ]
      }
    }
  ]

proRef ([object], varies)#

Professional Reference Verifications
When using a consent form ("isConsent": true), all fields may be considered optional; any valid values provided in the payload will get preloaded into the applicant's consent form.
When not using a consent form ("isConsent": false), the following fields become required:

Required fields when not using a consent form
contactName
contactPhone

  "verification": [
    {
      "type": "professionalreference",
      {
        "proRef": [
          {
            "contactName": "John Doe",
            "contactPhone": "555-555-5555",
            "contactEmail": "jdoe@example.com",
            "address": "123 Test St",
            "city": "Englewood",
            "stateCode": "CO",
            "zipCode": "80112"
          },
          {
            "contactName": "Jane Doe",
            ...
          }
        ]
      }
    }
  ]

personalRef ([object], varies)#

Personal Reference Verifications
When using a consent form ("isConsent": true), all fields may be considered optional; any valid values provided in the payload will get preloaded into the applicant's consent form.
When not using a consent form ("isConsent": false), the following fields become required:

Required fields when not using a consent form
contactName
contactPhone

  "verification": [
    {
      "type": "personalreference",
      {
        "personalRef": [
          {
            "contactName": "Jimmy Doe",
            "contactPhone": "555-555-5555",
            "contactEmail": "jimdoe@example.com",
            "address": "123 Test St",
            "city": "Englewood",
            "stateCode": "CO",
            "zipCode": "80112"
          },
          {
            "contactName": "Janey Doe",
            ...
          }
        ]
      }
    }
  ]

rentalHistory ([object], varies)#

Rental History Verifications
When using a consent form ("isConsent": true), all fields may be considered optional; any valid values provided in the payload will get preloaded into the applicant's consent form.
When not using a consent form ("isConsent": false), the following fields become required:

Required fields when not using a consent form
landlord
address
city
stateCode
zipCode
startMonth
startYear
endMonth
endYear

  "verification": [
    {
      "type": "rental",
      {
        "rentalHistory": [
          {
            "landlord": "ACME Apartments",
            "address": "123 Roadrunner Ln",
            "city": "Walla Walla",
            "stateCode": "WA",
            "zipCode": "99362",
            "contactPhone": "555-555-5555",
            "contactEmail": "rentacme@example.com",
            "startMonth": 1,
            "startYear": 1997,
            "endMonth": 5,
            "endYear": 2000
          },
          {
            "landlord": "Mom",
            ...
          }
        ]
      }
    }
  ]

dotVerification ([object], varies)#

Department of Transportation (DOT) Verifications
When using a consent form ("isConsent": true), all fields may be considered optional; any valid values provided in the payload will get preloaded into the applicant's consent form.
When not using a consent form ("isConsent": false), the following fields become required:

Required fields when not using a consent form
companyName
position
startMonth
startYear
contactName
contactPhone

  "verification": [
    {
      "type": "dot",
      "dotVerification": [
        {
          "companyName": "Latest DOT Comp",
          "position": "Driver",
          "city": "Denver",
          "stateCode": "CO",
          "startMonth": 1,
          "startYear": 2000,
          "endMonth": 12,
          "endYear": 2023,
          "contactName": "John Doe",
          "contactEmail": "jdoe@example.com",
          "contactPhone": "555-555-5555"
        },
        {
          "companyName": "Prior DOT",
          ...
        }
      ]
    }
  ]

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

State Criminal#

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

County Criminal#

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

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"
      },
      "phone": "555-555-5555"
    },
    "items": {
      "item": [
        {
          "itemNumber": {
            "type": "PACKAGE",
            "value": "[[packageNumber]]"
          }
        }
      ]
    }
  }
}

Eviction#

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