NAV

Getting Started

AssureHire makes it easy to integrate background screening with your application. Developers have the option of coding to our REST API, or we can develop an integration module to consume your data.

You must have an AssureHire account to test or use the API.
Contact Us to request an Account.

Authentication

Authenticate by including your secret API key in the request. You can manage your API keys in your User Settings. Your API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

Each user has their own API key and should use only their API key to access the API. However, if using the users API key is too cumbersome to implement (because it requires authenticating each user) you can use the Account API Key. Certain actions, such as creating a background check require the email address of the user to be provided when using the API Key.

Authentication to the API is performed via HTTP Basic Auth . Provide your API key as the basic auth username value. You do not need to provide a password when using a User API Key. However, when using the Account API Key, you must set the password to the md5 hash of the users email address (email address needs to be lowercased)/

If you need to authenticate via bearer auth (e.g., for a cross-origin request), use -H "Authorization: Bearer bad18eba1ff45jk7858b8ae88a77fa30" instead of -u bad18eba1ff45jk7858b8ae88a77fa30:.

Errors

AssureHire uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and codes in the 5xx range indicate an error with AssureHire’s servers (rare, 5xx errors instantly notify our on-call system engineer).

HTTP Status Code Meaning
200 OK – Everything worked as expected.
400 Bad Request – The request was unacceptable, often due to missing a required parameter.
401 Unauthorized – No valid API key provided.
403 Forbidden – The resource exists, however the API token used does not have access.
404 Not Found – The requested resource doesn’t exist.
429 Too Many Requests – Too many requests hit the API too quickly.
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Ping

Ping the API

curl "YOUR_API_KEY:@https://api.assurehire.com/v1/ping"
{
  "message": "pong",
  "time": "2016-07-27T22:30:25.765+00:00",
  "user": "melissa@acme.com"
}

The primary purpose of ping is to test authentication, however you may use it to monitor API uptime as well.

The user attribute will be null if the API does not detect authentication, otherwise it will return the email address for the given API token.

Background Checks

Create a Background Check

curl -d "email=candidate@yourco.com" "YOUR_API_KEY:@https://api.assurehire.com/v1/backgroundchecks"
{
  "id": "114911215506949681",
  "created_at": "2016-06-07T16:45:28.089602+00:00",
  "submitted_at": "2016-06-07T16:45:28.089602+00:00",
  "updated_at": "2016-06-07T21:15:37.451418+00:00",
  "completed_at": "2016-06-07T21:08:06.328+00:00",
  "due_at": "2016-06-07T21:08:06.328+00:00",
  "turnaround": 2,
  "status": "pending",
  "status_msg": "",
  "score": "clear",
  "copy_requested": false,
  "purpose": "employment",
  "bill_code": "store51",
  "job_code": "adm5-clerk",
  "package_id": "Standard",
  "report_url": "https://assurehire.com/backgroundchecks/114911215506949681/report",
  "consent_url": "https://assurehire.com/backgroundchecks/114911215506949681/consent",
  "applicant_url": "https://assurehire.com/mybackgroundcheck/114911215506949681",
  "last_name": "Schrute",
  "first_name": "Dwight",
  "middle_name": null,
  "name_suffix": null,
  "ssn": "XXXXX1305",
  "dob": "XXXX-03-21",
  "driver_license_number": "A293833",
  "driver_license_state": "CA",
  "gender": null,
  "title": null,
  "email": "ds@acme.com",
  "mobile_phone": "9165551234",
  "home_phone": "9165551234",
  "work_phone": null,
  "address_street": "2206 Plaza Drive",
  "address_city": "Rocklin",
  "address_state": "CA",
  "address_zip": "95747",
  "access_fee": null,
  "price": 55.0,
  "meta": {},
  "searches": [
    {
      "id": "75862037749564556",
      "submitted_at": "2016-06-07T16:45:28.089602+00:00",
      "updated_at": "2016-06-07T21:15:37.451418+00:00",
      "completed_at": "2016-06-07T21:08:06.328+00:00",
      "due_at": "2016-06-07T21:08:06.328+00:00",
      "product_id": "MSMJ",
      "product_description": "National Criminal Database",
      "status": "complete",
      "package_id": "Standard",
      "access_fee": null,
      "price": null
    },
    {
      "id": "75862037749564557",
      "submitted_at": "2016-06-07T16:45:28.089602+00:00",
      "updated_at": "2016-06-07T21:15:37.451418+00:00",
      "completed_at": null,
      "due_at": "2016-06-07T21:08:06.328+00:00",
      "product_id": "VEDU",
      "product_description": "Education Verification",
      "status": "pending",
      "package_id": "Standard",
      "access_fee": null,
      "price": null,
      "request": {
        "institution": "USC",
        "degree": "B.S Computer Science",
        "start_date": "1/2000",
        "end_date": "1/2004"
      }
    },
    {
      "id": "75862037749564558",
      "submitted_at": "2016-06-07T16:45:28.089602+00:00",
      "updated_at": "2016-06-07T21:15:37.451418+00:00",
      "completed_at": null,
      "due_at": "2016-06-07T21:08:06.328+00:00",
      "product_id": "VEMP",
      "product_description": "Employment Verification",
      "status": "pending",
      "package_id": "Standard",
      "access_fee": null,
      "price": null,
      "request": {
        "employer": "Acme Publications",
        "title": "Security",
        "contact": "Mary Jane",
        "phone_number": "15552223333",
        "email": "mjane@acmepubs.com",
        "website": "www.acmepubs.com",
        "start_date": "1/2000",
        "end_date": "1/2004",
        "reason_for_leavin": "USC"
      }
    },
    {
      "id": "75862037749564559",
      "submitted_at": "2016-06-07T16:45:28.089602+00:00",
      "updated_at": "2016-06-07T21:15:37.451418+00:00",
      "completed_at": null,
      "due_at": "2016-06-07T21:08:06.328+00:00",
      "product_id": "VLIC",
      "product_description": "License Verification",
      "status": "pending",
      "package_id": "Standard",
      "access_fee": null,
      "price": null,
      "request": {
        "license_num": "AB6969",
        "issuing_agency": "Dept of Justice",
        "issued": "1/2015",
        "expires": "1/2021"
      }
    }
  ]
}

Create a Background Check

HTTP Request

POST https://api.assurehire.com/v1/backgroundchecks

Creating a background check on an applicant requires proper disclosure and authorization from the applicant. If disclosure and authorization has already been conducted then you should create a background check supplying all the necessary information to perform the background check (applicant’s personal identifiers, including SSN and DOB).

AssureHire will email the candidate a link to initiate the electronic disclosure and authorization process and collect any needed data if the email parameter is set and the ssn and dob parameters are blank. This option will result in a newly created background check with a status of invite. When the applicant completes the process, the background check will be submitted for processing and the status will be upgraded to pending.

Body Parameters

Parameter Description
email [string] Candidate’s email address, required if ssn and dob are blank.
package_id [string] Package ID or name required. This parameter controls what type of background check is run, packages are usually setup at account creation. See Background Check Packages
callback_url [string] If provided, AssureHire will make a POST request to the given url each time the report changes. All content is expected to be JSON and conform to AssureHire’s schema. We can implement data transformers on our servers to map your schema to AssureHire’s and will issue you a unique protocol identifier for use in the callback_url (e.g. assuming your company is named BestHREver, we would assign you the protocol besthrever enabling you to set the callback_url to besthrever://integrations?token=5150. Our system would then replace besthrever with https and transform the content of the requests). When using a unique protocol identifier you can post any initial order information as a body parameter using the protocol identifier as the parameter name.
personal info… the following fields can be set on the background check object email, ssn, first_name, last_name, middle_name, dob, address_street, address_city, address_state, address_zip, mobile_phone, home_phone, driver_license_number, driver_license_state, meta
searches [array of hash] Search information can be provided by submitting an array of hashes. Each hash should contain the request data and the product_id. Each request will inherit personal info from the background check so it should only be provided to override the default values.

List Background Checks

curl -d "email=candidate@yourco.com" "YOUR_API_KEY:@https://api.assurehire.com/v1/backgroundchecks"

array of backgroundcheck resource

List background checks, by default the list excludes invites,draft,archived,cancelled.

HTTP Request

GET https://api.assurehire.com/v1/backgroundchecks

URL Parameters

Parameter Description
status [‘invite’, 'draft’, 'pending’, 'pre-adverse’, 'dispute’, 'complete’, 'archived’, 'cancelled’] Defaults to pending,pre-adverse,dispute,complete. Note multiple statuses can be AND together via comma separation.
created_at Only list background checks since provided created date.
updated_at Only list background checks since provided updated date.
completed_at Only list background checks since provided completed date.
due_at Only list background checks since provided due date.
turnaround Only list background checks greater than provided turnaround (value in hours).

Get a Background Check

curl -d "email=candidate@yourco.com" "YOUR_API_KEY:@https://api.assurehire.com/v1/backgroundchecks/114911215506949681"

backgroundcheck resource

Get a background check by ID

HTTP Request

GET https://api.assurehire.com/v1/backgroundchecks/:id

URL Parameters

Parameter Description
id The id of the background check to retrieve

Background Check Packages

Packages control which screening products are ordered. They are a vital organizational resource for EEO Compliance and order simplification.

List Packages

curl -d "email=candidate@yourco.com" "YOUR_API_KEY:@https://api.assurehire.com/v1/backgroundcheck_packages"
[
  {
    "id": "55994665484157953",
    "name": "Standard",
    "created_at": "2016-06-07T16:45:28.089602+00:00",
    "updated_at": "2016-06-07T21:15:37.451418+00:00",
    "deleted_at": null,
    "price": 25.00,
    "ssn": true,
    "crct": "1x",
    "expl": true,
    "msmj": true,
    "sxdb": "true"
  },
  {
    "id": "55994665484157955",
    "name": "Pro",
    "created_at": "2016-06-07T16:45:28.089602+00:00",
    "updated_at": "2016-06-07T21:15:37.451418+00:00",
    "deleted_at": null,
    "price": 35.00,
    "ssn": true,
    "crct": "7yr",
    "expl": true,
    "msmj": true,
    "sxdb": "true"
  }
]

HTTP Request

GET https://api.assurehire.com/v1/backgroundcheck_packages