Sterling

The Sterling On Demand API Developer Hub

Welcome to the Sterling On Demand API developer hub. You'll find comprehensive guides and documentation to help you start working with the Sterling Talent Solutions API as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    
Suggest Edits

Introduction

 

Overview

The Sterling API allows you to integrate background checks into your platform and manage the process form end-to-end.

Using the Sterling API, you can build applications that:

  • Perform background checks on participants in an online marketplace.
  • Schedule recurring screenings to proactively monitor changes in a candidate's status over time.
  • Receive real-time updates for the screenings you initiate.

Getting Started

Access to the Sterling API can be provided by sending a request to our team using the following link: Request Credentials

Once you receive your Client ID and Client Secret, here are the steps that API users typically follow to consume the Sterling APIs and perform end-to-end testing on your own.

  • Step 1: Get Authentication
    • Once you send an auth request with your Client ID and Client Secret, the response will contain an access token which can be used to send other requests to the API.
  • Step 2: GET /packages
    • Retrieve a list of the packages available to you (a package is a group of screening products). The response will also specify which fields are required on a candidate record in order to process the associated screening.
  • Step 3: POST /candidates
    • Create a candidate. Minimum fields for creation are (first name, last name, email, and clientReferenceId). Further fields will likely be needed to initiate a screening on the candidate. The required fields can be identified via GET /packages.
  • Step 4: POST /screenings
    • You will need a candidateId and packageId in order to create a screening. You have three workflow option for creating a screening. 1) Send the candidate an email invite. 2) Receive a link to a form which you can either open within your app or on a new tab. 3) If all required candidate fields already exist, simply initiate the screening. Additionally, you can specify a Callback URI in this request which will allow you to receive real-time updates for the screenings you initiate.
  • Step 5: Process screenings using the Developer Portal
    • Credentials to log into the Dev Portal are the same as your Client ID and Client Secret. The Dev Portal will allow you to manually set results for your screenings for end-to-end testing.
  • Step 6: Verify callbacks
    • In a POST /screenings request, you can set a Callback URI so that you can receive real-time updates for that screening.

Required Fields & Data Collection

Note: You’ll want to consider the required candidate fields so that you can design your application to collect the pertinent information.

Invite Feature: If you don't want to collect all of the required candidate information then the alternative is to have Sterling handle the data collection. To use this feature, set the attribute invite.method to "email" to send the candidate an email, or set invite.method to "link" to receive the form URL within the API response when you call POST /screenings.

Going Live

When going live, be sure to switch your host endpoint to the production environment. This will also require you to obtain authentication credentials for that environment. Unique IDs for packages will also differ between the test and production environments.

 
Suggest Edits

Authentication

 

Overview

The Sterling API uses an OAuth2 ("oauth") authentication scheme.

Requests to the Sterling API must be authenticated using short-lived bearer token in the Authorization header. Applications will obtain bearer tokens via the oauth endpoint. It is also required to set a "grant_type" field to "client_credentials', as shown in the curl auth request example below.

curl -X POST \
-H "Authorization: Basic <basic auth token>" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials' \
https://api-int.kennect.com/v2/oauth

When making a request to the oauth endpoint, the basic auth credentials must be a base64 encoded string in the format client_id:client_secret. These credentials are not provided through the API and must be obtained through Sterling Talent Solutions.

Base64

The base64 encoded string for the credentials will remain unchanged unless your client_secret is changed at your request.

For instance, [email protected]:86753O9 will always encode as ZXhhbXBsZUBleGFtcGxlLmNvbTo4Njc1M085.

If the provided credentials are valid, the oauth endpoint will provide a bearer token, along with an expiry time for the token (in seconds). An access_token will expire after 10 hours.

{
  "access_token": "RG8gcGVvcGxlIHJlYWxseSBkZWNvZGUgdGhlc2U/IEkgbWVhbiBzZXJpb3VzbHksIHRoaXMgaXMganVzdCBhIHRlc3QgaGFzaCEgV2VsbCwgaWYgeW91IG1hZGUgaXQgdGhpcyBmYXIsIGFsbG93IG1lIHRvIHJld2FyZCB5b3U6DQoNCmh0dHBzOi8vd3d3LnlvdXR1YmUuY29tL3dhdGNoP3Y9ZFF3NHc5V2dYY1E=",
  "token_type": "bearer",
  "expires_in": 36000
}

This token should be cached until it expires, and must be passed in the Authorization header of each request as follows:

curl -H "Authorization: Bearer RG8gcGVvcGxlIHJlYWxseSBkZWNvZGUgdGhlc2U/IEkgbWVhbiBzZXJpb3VzbHksIHRoaXMgaXMganVzdCBhIHRlc3QgaGFzaCEgV2VsbCwgaWYgeW91IG1hZGUgaXQgdGhpcyBmYXIsIGFsbG93IG1lIHRvIHJld2FyZCB5b3U6DQoNCmh0dHBzOi8vd3d3LnlvdXR1YmUuY29tL3dhdGNoP3Y9ZFF3NHc5V2dYY1E=" \
-H "Accept: application/json" \ 
https://api-int.kennect.com/v2/candidates/7212643

500 Errors

If you receive a 500 error on any API call using an Authorization header, please check that the format is "Bearer [base64]"

 
Suggest Edits

Screening Invite Method

 

Overview

Invite is an option that Sterling Talent Solutions provides to bridge the API to the underlying platforms. Using invite allows you to specify a method that a candidate can take to finish the screening process. Sterling's platforms will manage the candidate experience once the invite is accepted. This includes the collection of consent and disclosure electronically (if enabled), as well as the collection of any extra necessary information that is pertinent to the screening.

Screening Format

A POST to /screenings must include the object for invite.

{
  "id": "5787",
  "packageId": "64731",
  "candidateId": "864109",
  "callback": {
    "uri": "https://my-company.com/screenings-callback"
  },
  "invite": {
    "method": "link" | "email"
  }
}

The two supported options for method are link and email.

The link option will generate a tokenized link that will invite the candidate to create an account and log in to Screening Direct to complete their background screening.

The email option would instead email the candidate with a tokenized link to complete their background screening in Screening Direct.

{
    "id": "0020000008675309",
    "packageId": "161161",
    "candidateId": "57b8e8a9-bc8d-4a0e-9669-dbf89689c1ee",
    "status": "new",
    "result": "n/a",
    "invite": {
        "method": "link",
        "link": "https://qaworkforce.sterlingdirect.com/Account/Begin?PORTALDATA=yoDfSLYHSaTWCT6m25fPdfFtVXkMYlYeMKB1HVoVeISF0g1%7c0dq6jJADYm%7cWZVAC4Y4B8JL39u4OImvAj%2f4iLF3ABOnu2tpsPnDcqFsnfRc%3d"
    },
    "links": {
        "admin": {
            "web": "https://qasecure.sterlingdirect.com/sys/OneClick.aspx?METHOD=BGCHECK_PRTREPORT&CUSTID=Yvo0Re9cZczgNovyouJXWA%3d%3d&BGORDERID=tXMMH2L7L6ePzQ0myUvGng%3d%3d"
        }
    },
    "reportItems": [],
    "submittedAt": "2017-01-20T15:06:43Z",
    "updatedAt": "2017-01-20T15:06:43Z"
}
{
    "id": "0020000008675309",
    "packageId": "85685",
    "candidateId": "57b8e8a9-bc8d-4a0e-9669-dbf89689c1ee",
    "status": "PreDraft",
    "result": "Pending",
    "invite": {
        "method": "email"
    },
    "links": {
        "admin": {
            "web": "https://qasecure.sterlingdirect.com/sys/OneClick.aspx?METHOD=BGCHECK_PRTREPORT&CUSTID=tRi9fXj3E4zXUYZerPchlg%3d%3d&BGORDERID=UvDTODPDYmGQrF%7cDKpYSVA%3d%3d"
        }
    },
    "reportItems": [],
    "submittedAt": "0001-01-01T00:00:00Z",
    "updatedAt": "2019-05-24T15:01:00Z"
}

Invite Experience

Candidates invited via email will be met with a message that also includes the temporary password as mentioned above.

Both methods can be fully tested entirely in the integration testing environment.

Multiple Invites

invite cannot be retried, so every new call made to the /screenings endpoint with an invite method will begin an entirely new screening.

 
Suggest Edits

Callbacks

 

Background screenings involve gathering information from a variety of public and proprietary records, and as a result the response times for screenings can be unpredictable. As an API user, you can receive notifications when important events related to your screening occur. To receive update notifications, include a callback when creating a screening.

Callback Types

The callback type field supports future extensibility. At present, all callbacks are of the screening type.

Additional callback types may be introduced in the future. These new callback types will follow the same pattern as existing callbacks: the callback url will be specified in the POST request for the resource. This means that you are free to create one callback handling service exclusively for screenings and other services for each other callback type.

Alternatively, clients may implement a single general-purpose callback handler for all Sterling API callbacks. In that situation, the callback handler can use the type field to identify the message type and ensure that the intended parsing or business rules are applied only to the expected message types.

Retries

Callbacks will retry every 15 minutes until an HTTP 200 success response is returned from your server. The retries will attempt 9 more times after the original (for a total of 10 attempts).

Screening Callbacks

The most common callback type will be a screening, as it is the object that will receive the most changes over time. A sample JSON payload for a screening callback can be seen below.

{
  "type": "screening",
  "payload": {
    "id": "839472998",
    "packageId": "96193",
    "candidate": {
      "email": "[email protected]",
      "givenName": "John",
      "familyName": "Doe",
      "confirmedNoMiddleName":false,
      "dob":"1972-09-21",
      "ssn":"123456789",
      "phone":"17021234567",
      "address":{
        "addressLine":"123 Sterling St.",
        "municipality":"BOTHELL",
        "regionCode":"WA",
        "postalCode":"98011",
        "countryCode":"USA",
        "validFrom":"0001-01-01T00:00:00",
        "validTo":"0001-01-01T00:00:00"
      },
      "screeningIds":[],
      "driversLicense":{
        "type":"personal",
        "licenseNumber":"S1234567",
        "issuingAgency":""
      }
    },
    "candidateId":"faa75203-4c67-48da-b3b9-fbdd6b0c31ea",
    "status":"Complete",
    "result":"Clear",
    "links":{
      "admin":{
        "web":"https://qasecure.sterlingdirect.com/sys/OneClick.aspx?METHOD=BGCHECK_PRTREPORT&CUSTID=mwqMxus31%2fMcSKPxq6ZH4Q%3d%3d&BGORDERID=pMSMq00Kntb%2f0AM4ggigFkemex0roy%2fgXrfCXd77LLU%3d"
      }
    },
    "reportItems":[
      {
        "id":"11828946",
        "type":"SSN Trace",
        "status":"Complete",
        "result":"Complete",
        "updatedAt":"2018-11-15T17:32:00"
      },
      {
        "id":"11828947",
        "type":"Locator Select",
        "status":"Complete",
        "result":"Clear",
        "updatedAt":"2018-11-18T18:32:00"
      },
      {
        "id":"11828948",
        "type":"DOJ Sex Offender Search",
        "status":"Complete",
        "result":"Clear",
        "updatedAt":"2018-11-15T17:33:00"
      }
    ],
    "submittedAt":"2018-11-15T17:32:18",
    "updatedAt":"2018-11-15T17:33:00"
  }
}

Callback Statuses

Every screening callback will have a status property in it's payload. The value of status will change depending on the status of each item in reportItems.

Package(Payload) Statuses

PreDraft

Email sent; Information from candidate is required

Draft

Client information gathered; Ready to begin processing

Pending

Processing; At least 1 report item within this package has a status of pending

Cancelled

The candidate did not submit their data by the expiration date

Complete

All report items are set to complete within the package

Report Results

A report's result property will give a more detailed reason to why the report

Clear

Everything good, the screening passes.

Consider

Something found. The screening needs review.

Report Statuses

Each individual report may have their own statuses and these will vary upon the type of report processed.

If using these statuses it's best practice to only concern yourself with the most common values. Here's a list of the top common Report Status values

Complete

The report has completed and result property is populated

Pending

The report started but is not completed yet.

Expired

The report started but has expired due to inactivity.

Callback Consumption

Callbacks from the Sterling API support data consumption in chunked and non-chunked variants. Chunking is possible when the callback payload data exceeds 1MB in size.

 
Suggest Edits

Dev Portal

 

The Dev Portal's functionality is specific to Sterling's test environment. Credentials will be provided when you request developer credentials to access our API. The username and password will be the same as your Client ID and Client Secret.

 

Overview

Sterling uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate a success, codes in the 4xx range indicate a request that failed given the information provided (e.g. a required parameter was omitted, format issues, etc.), and codes in the 5xx range indicate an error with Sterling's servers.

When a request is valid but does not complete successfully, we return a 400# error code. Below you'll find more detailed information about the possible errors you can expect.

Error Format

The expected format for an error is as follows:

Error Format

{
      "code": "400#[optional-object]?[optional-reason]",
      "message": "[optional-message]"
}

Error Code Format

  • Example: 400#dob?format
  • HTTP error code (i.e. 400#)
  • Offending field when relevant (e.g. dob)
  • Brief message when applicable (e.g. format or required)

Error Message Format

  • The error message provides more context as to why the error occurred (e.g. "message": "dob must be in the format of YYYY-MM-DD")

Example:

{
      "code": "400#dob?format",
      "message": "dob must be in the format of YYYY-MM-DD"
}

Since the error message can change from time to time, we highly recommend you key off of the error code if you plan implement any automation for errors.

Candidate Validation Errors

Required Fields

code reason
400#address.addressLine addressLine is required if address is present
400#address.countryCode countryCode is required if address is present
400#address.postalCode postalCode is required if address is present
409#clientReferenceId?already-in-use clientReferenceId already in use
409#email?already-in-use email already in use

Examples

Error Message

{
  "errors": [
    {
      "code": "400#givenName",
      "message": "givenName is required"
    }
  ]
}

Solution

Include the "givenName" field in the candidate object:

{
    //...
    "givenName": "John",
    //...
}

Error Message

{
  "errors": [
    {
      "code": "400#address.addressLine",
      "message": "if address is provided, addressLine is required"
    }
  ]
}
Solution

In the "address" sub-object, include a "addressLine" field:

{
    //...
    "givenName": "John",
    //..
    "address": {
         "addressLine": "123 Example Street",
         "municipality": "ATLANTA",
         //..
     }
}

Format Validation Errors

code reason
400#dob?format dob must be in the format of YYYY-MM-DD
400#ssn?format ssn is not in the expected format
400#phone?format phone is not in the expected format
400#email?format email is not in the expected format
400#address.regionCode?format regionCode format
400#address.postalCode?format postalCode format
400#address.countryCode?format countryCode format
400#driversLicense.licenseNumber?format licenseNumber is not in the expected format
400#driversLicense.issuingAgency?format issuingAgency is not in the expected format
400#callback.uri?format callback.uri must be a valid https url

Screening Errors

code reason
400#candidateId?not-found candidateId must be a valid candidateId associated with the authenticated account
400#packageId?not-found packageId must be an active packageId associated with the authenticated account
400#documentType documentType must be one of: [end-user-agreement, disclosure-and-authorization]
400#screening?required-data Street address is required
400#screening?required-data Package requires city of residence of candidate
400#screening?required-data State is required
400#screening?required-data Zipcode is required
400#screening?required-data Package requires a valid date of birth of candidate
400#screening?required-data No Employer data provided
400#screening?required-data No Education data provided
 
Suggest Edits

Versioning

 

This document describes the Sterling API. The Sterling API follows semantic versioning, which means that we are committed to maintaining this API without breaking changes. It considers any removal or renaming of an API endpoint or JSON field from an API response to be a breaking change. Additions of new required input fields would also be incompatible with existing client code, so any newly-added input fields will always be optional.

Although fields will not be removed from responses, fields may be added to introduce new capabilities. Applications consuming this API should use permissive deserialization techniques when parsing JSON responses. It will always be safe to ignore unrecognized, optional fields.

Example of Permissive Deserialization

When using the Jackson JSON parsing library for Java, clients should disable the DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES flag.

 
 

A "package" is essentially a container for products/screenings. You can think of packages as your team's predefined background screening recipes. The Sterling API platform provides a number of components, which are individual searches that can be bundled up into a single package. Common components do things like check driving records or criminal records in various jurisdictions (like count, state, or federal courts). Packages are unique to your account and are used to standardize the checks your account uses to screen individuals based on your company or organization's needs.

A GET on the /packages endpoint provides a list of the packages defined for your account. The package response also lists the required candidate fields needed to initiate a screening with the package. Some components require more candidate data than others to successfully discover records related to the candidate, which means that different packages will have different required fields.

 
Suggest Edits

/packages

List of packages

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api-int.kennect.com/v2/packages
 
curl --request GET \
  --url https://api-int.kennect.com/v2/packages
var request = require("request");

var options = { method: 'GET',
  url: 'https://api-int.kennect.com/v2/packages' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-int.kennect.com/v2/packages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-int.kennect.com/v2/packages");

xhr.send(data);
import requests

url = "https://api-int.kennect.com/v2/packages"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

[
  {
    "id": "96193",
    "title": "My Screening Package",
    "active": true,
    "components": [
      "SSN Trace",
      "Criminal County Search (7-Year Address History)",
      "Federal Criminal Check",
      "Multi-State Instant Criminal Check With Verification",
      "Nationwide Sex Offender Registry Check"
    ],
    "requiredFields": [
      "givenName",
      "middleName",
      "familyName",
      "dob",
      "ssn",
      "address.addressLine",
      "address.postalCode"
    ]
  }
]
 
Suggest Edits

Candidates

 

A candidate is a person who will be the subject of a future screening. In many cases, a candidate will be created and screened immediately in a single session. Alternatively, a candidate can be created in advance for future screenings, screened with different packages over time as part of a role change, or may be screened every few months as part of an existing role.

By design, candidate records can be created with only a handful of required fields, to allow for use cases like step-by-step data collection across multiple user interactions. Because different kinds of screenings need different information about the candidate in order to effectively search for their background data, there is no single set of universally required fields for all screening types.

When building code to collect data from candidates within your own application, the best user experience in most cases is to collect all the data you will need in a single form. Because application developers typically know in advance what packages they will use to screen candidates, the best way to ensure that you are collecting all the data you need from your candidates is to look up the list of requiredFields using the Packages resource.

The candidate's email and clientReferenceId must be unique. When updating a candidate, all previously provided fields should be included in the request body with their desired values, not only those fields with intended changes.

 
Suggest Edits

/candidates

Create a candidate. The minimum requirements are labeled below. Additional fields (e.g., address, driversLicense, etc.) may be required depending on screening.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
posthttps://api-int.kennect.com/v2/candidates

Body Params

clientReferenceId
string
required

An identifier, such as a user id, to facilitate linking candidates back to entities in your own system. Must be unique.

givenName
string
required

The candidate's given or "first" name, such as "Tim" in "Tim Duncan".

middleName
string

The candidate's middle name, useful for differentiating between individuals with similar names in public record searches.

confirmedNoMiddleName
boolean

true if the the candidate has no legal name. false if the candidate may have a legal middle name.

familyName
string
required

The candidate's family name, such as "Rowling" in "Joanne K Rowling".

email
string
required

The email provided by the candidate. Must be a unique, valid email.

dob
string

Date of birth, formatted as an ISO-8601 date (without the time component). For example, July 4, 1979 would be represented as "1979-07-04".

phone
string

A phone number associated with the candidate, formatted as an E.164 string, such as +15555551234.

ssn
string

The social security number for the candidate, formatted as a series of numbers with no dashes 123551234.

address
object

The candidate's address. Please refer to Address.

 
driversLicense
object

Driver's license information. Please refer to DriversLicense.

 
aliases
object

List of candidate Aliases : Alternate information the candidate may also be known by. Please refer to CandiateAlias.

 
educationHistory
object

An array of objects with the candidate's education history. Please refer to EducationHistory.

 
employmentHistory
object

An array of objects containing the candidate's employment history. Please refer to EmploymentHistory.

 
licenses
object

An array of objects containing certifications or professional licenses the candidate has earned. Please refer to Licenses.

 

Request to create a new candidate

curl -X POST \
  https://api-int.kennect.com/v2/candidates \
  -d '{
    "clientReferenceId": "99912441",
    "givenName": "John",
    "confirmedNoMiddleName": true,
    "familyName": "Doe",
    "dob": "1990-01-20",
    "email": "[email protected]",
    "phone": "+14041231234",
    "ssn": "123456789",
    "address": {
      "addressLine": "123 Main Street",
      "municipality": "Orlando",
      "regionCode": "US-FL",
      "postalCode": "12345",
      "countryCode": "US"
    },
    "driversLicense": {
      "type": "personal",
      "licenseNumber": "S1234567",
      "issuingAgency": "CA"
    },
    "aliases": [
      {
        "givenName": "Robert",
        "familyName": "Saur",
        "middleName": "William",
        "confirmedNoMiddleName": false 
      },
      {
        "givenName": "Simon",
        "familyName": "Duck",
        "confirmedNoMiddleName": true
      }
    ],
    "educationHistory":[
      {
        "schoolName":"UW",
        "type" : "default",
        "schoolType" : "University",
        "degree" : {
          "major": "Software Systems",
          "degreeName": "B.S.",
          "degreeType": "Bachelors",
          "graduationDate": "2010-06-01",
          "degreeCompleted": true,
          "comments" : "something"
        },
        "schoolIDNumber" : "UW12345",
        "address": {
          "addressLine": "University District",
          "municipality": "SEATTLE",
          "regionCode": "US-WA",
          "postalCode": "98001",
          "countryCode": "US",
          "validFrom" : "2008-08-01"
        },
        "aliasGivenName" : "aliasFirstName1",
        "aliasFamilyName" : "aliasLastName1",
        "department" : "Computer Science",
        "startDate" : "2008-08-01",
        "endDate" : "2010-05-01",
        "email" : "[email protected]",
        "phone" : "14041231234",
        "fax" : "+1234567890",
        "notes" : "nothing"
      }
    ],
    "employmentHistory":[
      {
        "employerName" : "SomeEmployer",
        "currentEmployer" : true,
        "jobTitle" : "SomeJobTitle",
        "startDate" : "2008-10-02",
        "endDate" : "2012-10-25",
        "type" : "default",
        "employmentType" : "FullTime",
        "department" : "IT",
        "permissionToContact" : true,
        "reasonForLeaving" : "nothing",
        "salary" : {
          "currency" : "12345678",
          "startingSalary" : "140,000",
          "endingSalary" : "100,000"
        },
        "verification" : {
          "supervisorGivenName" : "supervisorFirstName",
          "supervisorFamilyName" : "supervisorLastName",
          "supervisorMiddleName" : "supervisorMiddleName",
          "address": {
            "addressLine": "ABC company",
            "municipality": "SEATTLE",
            "regionCode": "US-WA",
            "postalCode": "98001",
            "countryCode": "US",
            "validFrom" : "2008-08-01"
          },
          "email" : "[email protected]",
          "phone" : "14041231234",
          "fax" : "+1234567890"
        },
        "verifyEmployer" : true,
        "notes" : "nothing"
      }
    ],
    "licenses":[
      {
        "issuingAgency" : {
          "name" : "Some Institute",
          "address": {
            "addressLine": "ABC company",
            "municipality": "SEATTLE",
            "regionCode": "US-WA",
            "postalCode": "98001",
            "countryCode": "US",
            "validFrom" : "2008-08-01"
          }
        },
        "number" : "S12345",
        "name" : "Nursing Certification",
        "startDate" : "2016-01-01",
        "status" : "active",
        "notes" : "some notes"
      }
    ]
}'
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "3e4f84e3-9078-4451-a8b8-5897f4f4f4e3",
  "clientReferenceId": "999124441",
  "email": "[email protected]",
  "givenName": "John",
  "familyName": "Doe",
  "confirmedNoMiddleName": true,
  "dob": "1990-01-20",
  "ssn": "123456789",
  "phone": "+14041231234",
  "address": {
    "addressLine": "123 Main Street",
    "municipality": "Orlando",
    "regionCode": "US-FL",
    "postalCode": "12345",
    "countryCode": "US"
  },
  "aliases": [
    {
      "givenName": "Robert",
      "familyName": "Saur",
      "middleName": "William",
      "confirmedNoMiddleName": false
    },
    {
       "givenName": "Simon",
       "familyName": "Duck",
       "confirmedNoMiddleName": true
    }
  ],
  "educationHistory": [
    {
      "schoolName": "UW",
      "schoolType": "University",
      "degree": {
        "major": "Software Systems",
        "degreeName": "B.S.",
        "degreeType": "Bachelors",
        "graduationDate": "2010-06-01",
        "degreeCompleted": true,
        "comments": "something"
      },
      "schoolIDNumber": "UW12345",
      "address": {
        "addressLine": "University District",
        "municipality": "SEATTLE",
        "regionCode": "US-WA",
        "postalCode": "98001",
        "countryCode": "US",
        "validFrom": "2008-08-01"
      },
      "aliasGivenName": "aliasFirstName1",
      "aliasFamilyName": "aliasLastName1",
      "department": "Computer Science",
      "startDate": "2008-08-01",
      "endDate": "2010-05-01",
      "email": "[email protected]",
      "phone": "14041231234",
      "fax": "+1234567890",
      "notes": "nothing",
      "type": "default"
    }
  ],
  "employmentHistory": [
    {
      "employerName": "SomeEmployer",
      "currentEmployer": true,
      "jobTitle": "SomeJobTitle",
      "startDate": "2008-10-02",
      "endDate": "2012-10-25",
      "employmentType": "FullTime",
      "department": "IT",
      "permissionToContact": true,
      "reasonForLeaving": "nothing",
      "salary": {
        "currency": "12345678",
        "startingSalary": "140,000",
        "endingSalary": "100,000"
      },
      "verification": {
        "supervisorGivenName": "supervisorFirstName",
        "supervisorFamilyName": "supervisorLastName",
        "supervisorMiddleName": "supervisorMiddleName",
        "address": {
          "addressLine": "ABC company",
          "municipality": "SEATTLE",
          "regionCode": "US-WA",
          "postalCode": "98001",
          "countryCode": "US",
          "validFrom": "2008-08-01"
        },
        "email": "[email protected]",
        "phone": "14041231234",
        "fax": "+1234567890"
      },
      "verifyEmployer": true,
      "notes": "nothing",
      "type": "default"
    }
  ],
  "licenses": [
    {
      "issuingAgency": {
        "name": "Some Institute",
        "address": {
          "addressLine": "ABC company",
          "municipality": "SEATTLE",
          "regionCode": "US-WA",
          "postalCode": "98001",
          "countryCode": "US",
          "validFrom": "2008-08-01"
        }
      },
      "number": "S12345",
      "name": "Nursing Certification",
      "startDate": "2016-01-01",
      "status": "active",
      "notes": "some notes"
    }
  ],
  "screeningIds": [],
  "driversLicense": {
    "type": "personal",
    "licenseNumber": "S1234567",
    "issuingAgency": "CA"
  }
}
{
    "errors": [
        {
            "code": "409#email?already-in-use",
            "message": "email already in use"
        }
    ]
}
{
    "errors": [
        {
            "code": "400#givenName",
            "message": "givenName is required"
        }
    ]
}
 
Suggest Edits

/candidates/{id}

Update an existing candidate's information.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
puthttps://api-int.kennect.com/v2/candidates/id

Path Params

id
string
required

The unique identifier for the candidate resource, assigned by the Sterling API.

Body Params

clientReferenceId
string

An identifier, such as a user id, to facilitate linking candidates back to entities in your own system. Must be unique.

givenName
string
required

The candidate's given or "first" name.

middleName
string

The candidate's middle name, useful for differentiating between individuals with similar names in public record searches.

confirmedNoMiddleName
boolean

true if the the candidate has no legal name. false if the candidate may have a legal middle name.

familyName
string
required

The candidate's family name.

email
string
required

The email provided by the candidate. Must be a unique, valid email.

dob
string

Date of birth, formatted as an ISO-8601 date (without the time component). For example, July 4, 1979 would be represented as "1979-07-04".

phone
string

A phone number associated with the candidate, formatted as an E.164 string, such as +15555551234.

ssn
string

The social security number for the candidate, formatted as a series of numbers with no dashes 123551234.

address
object

Address of candidate. Please refer to Address.

 
driversLicense
object

Driver's license information of candidate. Please refer to DriversLicense.

 
aliases
object

List of candidate Aliases : Alternate information the candidate may also be known by. Please refer to CandiateAlias.

 
educationHistory
object

An array of objects with the candidate's education history. Please refer to EducationHistory.

 
employmentHistory
object

An array of objects containing the candidate's employment history. Please refer to EmploymentHistory.

 
licenses
object

An array of objects containing certifications or professional licenses the candidate has earned. Please refer to Licenses.

 
 
curl -X PUT \
  https://api-int.kennect.com/v2/candidates/733d9194-f36b-4468-9219-af45e27257b5 \
  -d '{
  "clientReferenceId": "e4e1ffda-caa3-ea6d-c095-be8429b31154",
  "email": "[email protected]",
  "givenName": "John",
  "familyName": "Doe",
  "confirmedNoMiddleName": true,
  "dob": "1998-07-18",
  "ssn": "123456789",
  "phone": "+14041231234",
  "address": {
   "addressLine": "123 Main Street",
   "municipality": "Orlando",
   "regionCode": "US-FL",
   "postalCode": "12345",
   "countryCode": "US"
  },
  "driversLicense": {
    "type": "personal",
    "licenseNumber": "S1234567",
    "issuingAgency": "CA"
  },
  "aliases": [
    {
      "givenName": "Chris",
      "familyName": "Jenkins",
      "confirmedNoMiddleName": true
    },
   {
      "givenName": "Duke",
      "familyName": "Duck",
      "confirmedNoMiddleName": true
    }
  ],
  "educationHistory": [
    {
      "schoolName": "UW",
      "type": "default",
      "schoolType": "University",
      "degree": {
        "major": "Software Systems",
        "degreeName": "B.S.",
        "degreeType": "Bachelors",
        "graduationDate": "2010-07-01",
        "degreeCompleted": true,
        "comments": "Graduated with a 3.89 GPA."
      },
      "schoolIDNumber": "UW54321",
      "address": {
        "addressLine": "675 University District",
        "municipality": "SEATTLE",
        "regionCode": "US-WA",
        "postalCode": "98001",
        "countryCode": "US",
        "validFrom": "2008-08-01"
      },
      "aliasGivenName": "aliasFirstName2",
      "aliasFamilyName": "aliasLastName2",
      "department": "Computer Engineering",
      "startDate": "2008-08-01",
      "endDate": "2010-05-01",
      "email": "[email protected]",
      "phone": "14041231234",
      "fax": "+1234567890",
      "notes": "nothing of note."
    }
  ],
  "employmentHistory": [
    {
      "employerName": "AnotherEmployer",
      "currentEmployer": false,
      "jobTitle": "Manager",
      "startDate": "2008-06-07",
      "endDate": "2012-11-12",
      "type": "default",
      "employmentType": "FullTime",
      "department": "IT",
      "permissionToContact": false,
      "reasonForLeaving": "Moved",
      "salary": {
        "currency": "$180,000",
        "startingSalary": "$140,000",
        "endingSalary": "$180,000"
      },
      "verification": {
        "supervisorGivenName": "supervisorFirstName",
        "supervisorFamilyName": "supervisorLastName",
        "supervisorMiddleName": "supervisorMiddleName",
        "address": {
          "addressLine": "786 Address Road",
          "municipality": "SEATTLE",
          "regionCode": "US-WA",
          "postalCode": "98040",
          "countryCode": "US",
          "validFrom": "2008-08-01"
        },
        "email": "[email protected]",
        "phone": "+14041231234",
        "fax": "+1234567890"
      },
      "verifyEmployer": true,
      "notes": "none."
    }
  ],
  "licenses": [
    {
      "issuingAgency": {
        "name": "License Place",
        "address": {
          "addressLine": "8274 License Way #345",
          "municipality": "SEATTLE",
          "regionCode": "US-WA",
          "postalCode": "98001",
          "countryCode": "US",
          "validFrom": "2008-08-01"
        }
      },
      "number": "S54321",
      "name": "Nursing Certification II",
      "startDate": "2016-01-02",
      "status": "active",
      "notes": "More Notes."
    }
  ]
}'
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "733d9194-f36b-4468-9219-af45e27257b5",
  "clientReferenceId": "e4e1ffda-caa3-ea6d-c095-be8429b31154",
  "email": "[email protected]",
  "givenName": "John",
  "familyName": "Doe",
  "confirmedNoMiddleName": true,
  "dob": "1998-07-18",
  "ssn": "123456789",
  "phone": "+14041231234",
  "address": {
    "addressLine": "123 Main Street",
    "municipality": "Orlando",
    "regionCode": "US-FL",
    "postalCode": "12345",
    "countryCode": "US"
  },
  "aliases": [
    {
      "givenName": "Chris",
      "familyName": "Jenkins",
      "confirmedNoMiddleName": true
    },
    {
      "givenName": "Duke",
      "familyName": "Duck",
      "confirmedNoMiddleName": true
    }
  ],
  "educationHistory": [
    {
      "schoolName": "UW",
      "schoolType": "University",
      "degree": {
        "major": "Software Systems",
        "degreeName": "B.S.",
        "degreeType": "Bachelors",
        "graduationDate": "2010-07-01",
        "degreeCompleted": true,
        "comments": "Graduated with a 3.89 GPA."
      },
      "schoolIDNumber": "UW54321",
      "address": {
        "addressLine": "675 University District",
        "municipality": "SEATTLE",
        "regionCode": "US-WA",
        "postalCode": "98001",
        "countryCode": "US",
        "validFrom": "2008-08-01"
      },
      "aliasGivenName": "aliasFirstName2",
      "aliasFamilyName": "aliasLastName2",
      "department": "Computer Engineering",
      "startDate": "2008-08-01",
      "endDate": "2010-05-01",
      "email": "[email protected]",
      "phone": "14041231234",
      "fax": "+1234567890",
      "notes": "nothing of note.",
      "type": "default"
    }
  ],
  "employmentHistory": [
    {
      "employerName": "AnotherEmployer",
      "currentEmployer": false,
      "jobTitle": "Manager",
      "startDate": "2008-06-07",
      "endDate": "2012-11-12",
      "employmentType": "FullTime",
      "department": "IT",
      "permissionToContact": false,
      "reasonForLeaving": "Moved",
      "salary": {
        "currency": "$180,000",
        "startingSalary": "$140,000",
        "endingSalary": "$180,000"
      },
      "verification": {
        "supervisorGivenName": "supervisorFirstName",
        "supervisorFamilyName": "supervisorLastName",
        "supervisorMiddleName": "supervisorMiddleName",
        "address": {
          "addressLine": "786 Address Road",
          "municipality": "SEATTLE",
          "regionCode": "US-WA",
          "postalCode": "98040",
          "countryCode": "US",
          "validFrom": "2008-08-01"
        },
        "email": "[email protected]",
        "phone": "+14041231234",
        "fax": "+1234567890"
      },
      "verifyEmployer": true,
      "notes": "none.",
      "type": "default"
    }
  ],
  "screeningIds": [],
  "driversLicense": {
    "type": "personal",
    "licenseNumber": "S1234567",
    "issuingAgency": "CA"
  }
}
 
Suggest Edits

/candidates/{id}

Retrieve a candidate by their unique identifier. This will return all the most recent information on the candidate.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api-int.kennect.com/v2/candidates/id

Path Params

id
string
required

candidate id

 
curl -X GET \
  'https://api-int.kennect.com/v2/candidates/733d9194-f36b-4468-9219-af45e27257b5'
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "733d9194-f36b-4468-9219-af45e27257b5",
  "clientReferenceId": "e4e1ffda-caa3-ea6d-c095-be8429b31154",
  "email": "[email protected]",
  "givenName": "John",
  "familyName": "Doe",
  "confirmedNoMiddleName": true,
  "dob": "1998-07-18",
  "ssn": "123456789",
  "phone": "+14041231234",
  "address": {
    "addressLine": "123 Main Street",
    "municipality": "Orlando",
    "regionCode": "US-FL",
    "postalCode": "12345",
    "countryCode": "US"
  },
  "aliases": [
    {
      "givenName": "Robert",
      "middleName": "Saur",
      "confirmedNoMiddleName": false,
      "familyName": "William"
    },
    {
      "givenName": "Simon",
      "familyName": "Duck",
      "confirmedNoMiddleName": true
    }
  ],
  "educationHistory": [
    {
      "schoolName": "UW",
      "type": "default",
      "schoolType": "University",
      "degree": {
        "major": "Software Systems",
        "degreeName": "B.S.",
        "degreeType": "Bachelors",
        "graduationDate": "2010-07-01",
        "degreeCompleted": true,
        "comments": "Graduated with a 3.89 GPA."
      },
      "schoolIDNumber": "UW54321",
      "address": {
        "addressLine": "675 University District",
        "municipality": "SEATTLE",
        "regionCode": "US-WA",
        "postalCode": "98001",
        "countryCode": "US",
        "validFrom": "2008-08-01"
      },
      "aliasGivenName": "aliasFirstName2",
      "aliasFamilyName": "aliasLastName2",
      "department": "Computer Engineering",
      "startDate": "2008-08-01",
      "endDate": "2010-05-01",
      "email": "[email protected]",
      "phone": "14041231234",
      "fax": "+1234567890",
      "notes": "nothing of note."
    }
  ],
  "employmentHistory": [
    {
      "employerName": "AnotherEmployer",
      "currentEmployer": false,
      "jobTitle": "Manager",
      "startDate": "2008-06-07",
      "endDate": "2012-11-12",
      "type": "default",
      "employmentType": "FullTime",
      "department": "IT",
      "permissionToContact": false,
      "reasonForLeaving": "Moved",
      "salary": {
        "currency": "$180,000",
        "startingSalary": "$140,000",
        "endingSalary": "$180,000"
      },
      "verification": {
        "supervisorGivenName": "supervisorFirstName",
        "supervisorFamilyName": "supervisorLastName",
        "supervisorMiddleName": "supervisorMiddleName",
        "address": {
          "addressLine": "786 Address Road",
          "municipality": "SEATTLE",
          "regionCode": "US-WA",
          "postalCode": "98040",
          "countryCode": "US",
          "validFrom": "2008-08-01"
        },
        "email": "[email protected]",
        "phone": "+14041231234",
        "fax": "+1234567890"
      },
      "verifyEmployer": true,
      "notes": "none."
    }
  ],
  "licenses": [
    {
      "issuingAgency": {
        "name": "License Place",
        "address": {
          "addressLine": "8274 License Way #345",
          "municipality": "SEATTLE",
          "regionCode": "US-WA",
          "postalCode": "98001",
          "countryCode": "US",
          "validFrom": "2008-08-01"
        }
      },
      "number": "S54321",
      "name": "Nursing Certification II",
      "startDate": "2016-01-02",
      "status": "active",
      "notes": "More Notes."
    }
  ],
  "screeningIds": [],
  "driversLicense": {
    "type": "personal",
    "licenseNumber": "S1234567",
    "issuingAgency": "CA"
  }
}
 
Suggest Edits

/candidates/?email={email}

Retrieve candidate by their primary email address.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api-int.kennect.com/v2/candidates/?email=email

Query Params

email
string
required

The candidate's primary email address.

 
curl -X GET \
  'https://api-int.kennect.com/v2/[email protected]'
  
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "733d9194-f36b-4468-9219-af45e27257b5",
  "clientReferenceId": "e4e1ffda-caa3-ea6d-c095-be8429b31154",
  "email": "[email protected]",
  "givenName": "John",
  "familyName": "Doe",
  "confirmedNoMiddleName": true,
  "dob": "1998-07-18",
  "ssn": "123456789",
  "phone": "+14041231234",
  "address": {
    "addressLine": "123 Main Street",
    "municipality": "Orlando",
    "regionCode": "US-FL",
    "postalCode": "12345",
    "countryCode": "US"
  },
  "aliases": [
    {
      "givenName": "Robert",
      "middleName": "Saur",
      "confirmedNoMiddleName": false,
      "familyName": "William"
    },
    {
      "givenName": "Simon",
      "familyName": "Duck",
      "confirmedNoMiddleName": true
    }
  ],
  "educationHistory": [
    {
      "schoolName": "UW",
      "type": "default",
      "schoolType": "University",
      "degree": {
        "major": "Software Systems",
        "degreeName": "B.S.",
        "degreeType": "Bachelors",
        "graduationDate": "2010-07-01",
        "degreeCompleted": true,
        "comments": "Graduated with a 3.89 GPA."
      },
      "schoolIDNumber": "UW54321",
      "address": {
        "addressLine": "675 University District",
        "municipality": "SEATTLE",
        "regionCode": "US-WA",
        "postalCode": "98001",
        "countryCode": "US",
        "validFrom": "2008-08-01"
      },
      "aliasGivenName": "aliasFirstName2",
      "aliasFamilyName": "aliasLastName2",
      "department": "Computer Engineering",
      "startDate": "2008-08-01",
      "endDate": "2010-05-01",
      "email": "[email protected]",
      "phone": "14041231234",
      "fax": "+1234567890",
      "notes": "nothing of note."
    }
  ],
  "employmentHistory": [
    {
      "employerName": "AnotherEmployer",
      "currentEmployer": false,
      "jobTitle": "Manager",
      "startDate": "2008-06-07",
      "endDate": "2012-11-12",
      "type": "default",
      "employmentType": "FullTime",
      "department": "IT",
      "permissionToContact": false,
      "reasonForLeaving": "Moved",
      "salary": {
        "currency": "$180,000",
        "startingSalary": "$140,000",
        "endingSalary": "$180,000"
      },
      "verification": {
        "supervisorGivenName": "supervisorFirstName",
        "supervisorFamilyName": "supervisorLastName",
        "supervisorMiddleName": "supervisorMiddleName",
        "address": {
          "addressLine": "786 Address Road",
          "municipality": "SEATTLE",
          "regionCode": "US-WA",
          "postalCode": "98040",
          "countryCode": "US",
          "validFrom": "2008-08-01"
        },
        "email": "[email protected]",
        "phone": "+14041231234",
        "fax": "+1234567890"
      },
      "verifyEmployer": true,
      "notes": "none."
    }
  ],
  "licenses": [
    {
      "issuingAgency": {
        "name": "License Place",
        "address": {
          "addressLine": "8274 License Way #345",
          "municipality": "SEATTLE",
          "regionCode": "US-WA",
          "postalCode": "98001",
          "countryCode": "US",
          "validFrom": "2008-08-01"
        }
      },
      "number": "S54321",
      "name": "Nursing Certification II",
      "startDate": "2016-01-02",
      "status": "active",
      "notes": "More Notes."
    }
  ],
  "screeningIds": [],
  "driversLicense": {
    "type": "personal",
    "licenseNumber": "S1234567",
    "issuingAgency": "CA"
  }
}
 
Suggest Edits

Screenings

A screening is a background check on a candidate with a specific package.

Once a candidate is created and a package has been selected, the screening can be initiated on that candidate by calling the POST /v2/screenings endpoint. The turnaround time for completion of a screening is variable. Most screening reports are returned within 24-72 hours, and the results can be found by calling GET /v2/screenings/{id}, where {id} is the identifier for the screening.

An application can subscribe to updates on the fulfillment of a screening using the callback field. Callbacks will be POSTed to the provided URL for any changes screening status, including changes to the report items. (See Callbacks)

 

The API also supports Idempotency for safely retrying screening requests without accidentally performing the same operation twice.

 
Suggest Edits

/screenings

Create a new screening for a candidate.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
posthttps://api-int.kennect.com/v2/screenings

Body Params

packageId
string
required

The unique identifier for the package the candidate will be screened against.

candidateId
string
required

The unique identifier of the candidate to be screened.

callback
object

The url where webhook notifications should be posted for this screening. Please refer to Callback.

 
invite
object

Invite allows you to specify a method that a candidate can take to finish the screening process. Please refer to Invite.

 
billCode
string

Client specified code.

jobPosition
string

Position that the candidate is being screened for.

customFields
object

Custom fields can be attached to a screening and can contain any key and value. Please refer to CustomFields.

 
requester
object

Information about the user who is creating the screening on a candidate. Please refer to Requester.

 
selfDisclosures
array

To disclose the candidate's convictions and aliases. Please refer to SelfDisclosures.

Headers

idempotency-key
string

The API supports idempotency for safely retrying screening requests without accidentally performing the same operation twice.

The status and result of a Screening response depends on the data submitted to the Screening.
Some of the attribute values :

Attribute
Values

status

PreDraft
Draft
Pending
Complete
Cancelled
Expired

result

Pending
Clear
Consider

curl -X POST https://api.kennect.com/v2/screenings \
  -H 'authorization: Bearer <Token>' \
  -H 'content-type: application/json' \
  -d '{
    "candidateId": "e4e0d15d-843c-44bb-a7d6-3bbf069857e2",
    "packageId": "92979",
    "callback": {
      "uri": "https://my-company.com/screenings-callback",
      "credentials": {
          "basic-auth": "narf:zort"
      }
    },
    "jobPosition" : "Education Package",
    "customFields":[
      {
        "fieldName":"Job Opening ID",
        "fieldValue":"28374953"
      },
      {
        "fieldName":"Hiring Manager",
        "fieldValue":"Jane Doe"
      },
      {
        "fieldName":"Department",
        "fieldValue":"Engineering"
      }
    ],
    "requester" : {
      "email" : "[email protected]",
      "givenName" : "abcFirstName",
      "familyName" : "abcLastName",
      "middleName" : "abcMiddleName"
    }
}'
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id":"900000000",
  "packageId":"92979",
  "candidateId":"e4e0d15d-843c-44bb-a7d6-3bbf069857e2",
  "status":"Pending",
  "result":"Pending",
  "jobPosition":"Education Package",
  "links":{
    "admin":{
      "web":"https://qasecure.sterlingdirect.com/sys/OneClick.aspx?METHOD=BGCHECK_PRTREPORT&CUSTID=lQoNLe4hwyodcFNuY0dYJg%3d%3d&BGORDERID=LqEPJWgb52OG6GXeeZb%7cDw%3d%3d"
    }
  },
  "callback":{
    "uri":"https://requestinspector.com/inspect/01cxecye2vb813b7t7ysz077dn"
  },
  "reportItems":[
    {
      "id":"11522030",
      "type":"Education Verification",
      "status":"pending",
      "result":null,
      "updatedAt":"2019-04-18T19:11:00Z"
    }
  ],
  "submittedAt":"2019-04-12T18:10:42Z",
  "updatedAt":"2019-04-18T19:11:00Z"
}
{
    "id": "9000000000",
    "packageId": "85685",
    "candidateId": "57b8e8a9-bc8d-4a0e-9669-dbf89689c1ee",
    "status": "PreDraft",
    "result": "Pending",
    "invite": {
        "method": "email"
    },
    "links": {
        "admin": {
            "web": "https://qasecure.sterlingdirect.com/sys/OneClick.aspx?METHOD=BGCHECK_PRTREPORT&CUSTID=tRi9fXj3E4zXUYZerPchlg%3d%3d&BGORDERID=UvDTODPDYmGQrF%7cDKpYSVA%3d%3d"
        }
    },
    "reportItems": [],
    "submittedAt": "0001-01-01T00:00:00Z",
    "updatedAt": "2019-05-24T15:01:00Z"
}
{
  "errors": [
    {
      "code": "400#callback.uri?format",
      "message": "callback.uri must be a valid https url"
    }
  ]
}
{
    "errors": [
        {
            "code": "400#billingCode?invalid",
            "message": "Invalid Billing Code"
        }
    ]
}
{
    "errors": [
        {
            "code": "400#referenceCodes?required",
            "message": "Reference Codes required"
        }
    ]
}
{
    "id": "900000000",
    "packageId": "85685",
    "candidateId": "57b8e8a9-bc8d-4a0e-9669-dbf89689c1ee",
    "status": "PreDraft",
    "result": "Pending",
    "invite": {
        "method": "link",
        "link": "https://qaworkforce.sterlingdirect.com/Account/Begin?PORTALDATA=yoDfSLYHSaTWCT6m25fPdfFtVXkMYlYeMKB1HVoVeISF0g1%7c0dq6jJADYm%7cWZVAC4Y4B8JL39u4OImvAj%2f4iLF3ABOnu2tpsPnDcqFsnfRc%3d"
    },
    "links": {
        "admin": {
            "web": "https://qasecure.sterlingdirect.com/sys/OneClick.aspx?METHOD=BGCHECK_PRTREPORT&CUSTID=Yvo0Re9cZczgNovyouJXWA%3d%3d&BGORDERID=tXMMH2L7L6ePzQ0myUvGng%3d%3d"
        }
    },
    "reportItems": [],
    "submittedAt": "0001-01-01T00:00:00Z",
    "updatedAt": "2019-05-24T14:41:00Z"
}
 
Suggest Edits

/screenings/{id}

Retrieve a screening by unique identifier.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api-int.kennect.com/v2/screenings/id

Path Params

id
string
required

Unique identifier of the screening.

 
curl -X GET \
  'https://api-int.kennect.com/v2/screenings/900010449' 
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "900010449",
  "packageId": "164741",
  "candidateId": "927084",
  "status": "pending",
  "result": "alert",
  "reportItems": [
    {
      "id": "62555551",
      "type": "SSN Trace",
      "status": "complete",
      "result": "no data",
      "updatedAt": "2016-11-15T00:30:49Z"
    },
    {
      "id": "62555552",
      "type": "Criminal Check by Jurisdiction",
      "status": "complete",
      "result": "alert",
      "updatedAt": "2016-11-15T00:31:25Z"
    },
    {
      "id": "62555553",
      "type": "Federal Criminal Check",
      "status": "pending",
      "result": "n/a",
      "updatedAt": "2016-11-15T00:30:36Z"
    },
    {
      "id": "62555554",
      "type": "Multi-State Instant Criminal Check",
      "status": "pending",
      "result": "n/a",
      "updatedAt": "2016-11-15T00:30:36Z"
    },
    {
      "id": "62555555",
      "type": "Nationwide Sex Offender Registry Check",
      "status": "pending",
      "result": "n/a",
      "updatedAt": "2016-11-15T00:30:36Z"
    }
  ],
  "submittedAt": "2016-11-15T00:30:36Z",
  "updatedAt": "2016-11-15T00:31:35Z",
  "dispute": {
    "status": "active",
    "createdAt": "2016-12-01T21:03:00Z"
  },
  "links": {
    "admin": {
      "web": "https://integration.talentwise.com/screening/report.php?ApplicantID=8675309",
      "pdf": "https://integration.talentwise.com/screening/pdf-report.php?ApplicantID=8675309"
    }
  },
  "callback": {
    "uri": "https://mockbin.org/bin/b87c5aec-cb87-4dfc-8550-031bbe560407"
  }
}
{
  "errors": [
    {
      "code": "400#callback.uri?format",
      "message": "callback.uri must be a valid https url"
    }
  ]
}
 
Suggest Edits

/screenings/{id}/report

Generate the screening report.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api-int.kennect.com/v2/screenings/id/report

Path Params

id
string
required

Unique identifier of the screening.

This request accepts the Authorization header and allows retrieving a screening report with no restrictions on time or use.

curl -X GET \
  https://api-int.kennect.com/v2/screenings/{id}/report\
  -H 'authorization: Bearer token-hash' \
  -H 'content-type: application/pdf' 
A binary file was returned

Your OAuth2 token is incorrect or has expired

Try the API to see results
 
Suggest Edits

/bill-codes

Retrieve the bill codes associated with the API account.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api-int.kennect.com/v2/bill-codes
 
curl --request GET \
  --url https://api-int.kennect.com/v2/bill-codes
var request = require("request");

var options = { method: 'GET',
  url: 'https://api-int.kennect.com/v2/bill-codes' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-int.kennect.com/v2/bill-codes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-int.kennect.com/v2/bill-codes");

xhr.send(data);
import requests

url = "https://api-int.kennect.com/v2/bill-codes"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "billCodes": [
    "billCode1",
    "billCode2"
  ]
}
 
Suggest Edits

/screenings/{id}/documents

In some cases, supporting documents may need to be attached to a screening. This endpoint will allow you to attach PDF or TIFF files containing a resume, driver license, passport, consent, or other.

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
posthttps://api-int.kennect.com/v2/screenings/id/documents

Path Params

id
string
required

Supported document types and attachments

Form Key
Acceptable Values

documentType

resume, drivers-license, passport, consent, other

attachment

.pdf or .tiff

curl -X POST https://api.kennect.com/v2/screenings/900128351/documents \
  -H 'authorization: Bearer <Token>' \
  -H 'content-type: multipart/form-data' \
  -F documentType=passport \
  -F '[email protected]/Users/johnsmith/API/test.pdf'
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
    "id": "6223706",
    "fileName": "passport_test.pdf",
    "createdAt": "2020-01-09T23:45:32Z",
    "updatedAt": "2020-01-09T23:45:32Z"
}
{
    "errors": [
        {
            "code": "400#attachment",
            "message": "Attachment is missing. Please upload a PDF or TIFF"
        }
    ]
}
{
    "errors": [
        {
            "code": "400#documentType",
            "message": "documentType must be one of: [resume, drivers-license, passport, consent, other]"
        }
    ]
}
 
Suggest Edits

Address

An address associated with a candidate object, their education history, employment history, or licensing agency.

 
Attribute
Type
Description

addressLine*

string

The candidate's residential street address, such as "123 Main Street". Or the address associated with another object.

municipality

string

The city or town of the address.

regionCode

string

The ISO 3166-2 region, such as a US state, where the candidate lives. In the US, this is the combination of "US", a dash, and the state or territory's two-letter postal code. For example, Texas is "US-TX" and Puerto Rico is "US-PR".

postalCode*

string

The 5 or 9 digit zip code for the address, with no dashes.

countryCode

string

The two-letter ISO short code for the country of the address, such as "US".

validFrom

string

This field is not for a candidate address but is associated with education, employment, and licensing addresses. Format should be "YYYY-MM-DD".

"address": {
  "addressLine": "675 University District",
  "municipality": "SEATTLE",
  "regionCode": "US-WA",
  "postalCode": "98001",
  "countryCode": "US",
  "validFrom": "2008-08-01"
}
 
Suggest Edits

DriversLicense

 

The candidate's driver's license.

Attribute
Type
Description

type

enum[string]

Type of license should be "personal".

licenseNumber*

string

Driver's license number.

issuingAgency*

string

Driver's license issuing agency. It is the ISO 3166-2 region.

"driversLicense": {
  "type": "personal",
  "licenseNumber": "S1234567",
  "issuingAgency": "CA"
}
 
Suggest Edits

CandidateAlias

 

Alternate information the candidate may also be known by.

Attribute
Type
Description

givenName*

string

The candidate's alternate first name.

familyName*

string

The candidate's alternate last name.

middleName

string

The candidate's alternate middle name.

confirmedNoMiddleName

boolean

Set to true if the candidate has no alternate middle name.

"aliases": [
    {
        "givenName": "GivenAlias1",
        "familyName": "FamilyNameAlias1",
        "middleName": "MiddleNameAlias1",
        "confirmedNoMiddleName": false
    },
    {
        "givenName": "GivenAlias2",
        "familyName": "FamilyNameAlias2",
        "confirmedNoMiddleName": true
    }
]
 
Suggest Edits

CallbackRequest

 

The url where webhook notifications should be posted for this screening. Please refer to Callbacks for more details.

Attribute
Type
Description

uri

string

A uri on a server that you control where you expect to receive callback updates related to screenings. Must be an https uri.

credentials

callback when creating a screening.

"callback": {
  "uri": "https://my-company.com/screenings-callback",
  "credentials": {
    "basic-auth": "narf:zort!"
  }
}
 
Suggest Edits

CallbackCredentials

 

Auth credentials for callback authentication.

Attribute
Type
Description

basicAuth

string

HTTP Basic Auth credentials for callback authentication. Requests sent from Sterling API to the callback endpoint will include these credentials in the Authorization header.

"credentials": {
  "basic-auth": "narf:zort!"
}
 

Invite for screening. Please refer to Invite for more details.

Attribute
Type
Description

method

String

Possible values : "link", "email"

link

String

"invite": {
    "method": "email",
    "link": "https://portal.integration.talentwise.com/438a7d2ee6/ptl/ticketeda.php?ID=MTY5MDIzODA&code=7C3bGnsqq1Zw8jUQ&ticket=423829&&Sender=16902380&Email=deckarda7b83455-07e6-818f-d474-293605e7d663%40example.com&OverrideCandidateID=864109&KennectApiToken=token-hash"
}
"invite": {
    "method": "email"
}
 
Suggest Edits

EducationHistory

The candidate's education information.

 
Attribute
Type
Description

schoolName*

string

The name of the school.

schoolType*

string

Type of school such as university.

degree*

object (EducationDegree)

Degree received upon completion of education.

schoolIDNumber*

string

The unique ID of the school within your platform.

address

object(Address)

Address of the place of education.

aliasGivenName

string

If another first name was used while attending the place of education.

aliasFamilyName

string

If another last name was used while attending the place of education.

department

string

The department of education from which the candidate graduated.

startDate

string

Date that education at this institution started. Format must be YYYY-MM-DD.

endDate

string

Date that education at this institution was completed. Format must be YYYY-MM-DD.

email

string

The school email address of the candidate.

phone

string

Phone number of the institution.

fax

string

Fax number of the institution.

notes

string

Any additional notes to add pertaining to a specific education instance.

type

string

Type must be "faa" or "default".

"educationHistory": [
	{
    "schoolName":"UW",
    "schooType":"University",
    "degree":{
      "major":"Software Systems",
      "degreeName":"Bachelors",
      "degreeType":"B.S.",
      "graduationDate":"2010-06-01",
      "degreeCompleted":true,
      "comments":"something"
    },
    "schoolIDNumber":"UW12345",
    "address":{
      "addressLine":"University District",
      "municipality":"SEATTLE",
      "regionCode":"US-WA",
      "postalCode":"98001",
      "countryCode":"US",
      "validFrom":"2008-08-01"
    },
    "type":"default",
    "aliasGivenName":"Steve",
    "aliasFamilyName":"Smith",
    "department":"Computer Science",
    "startDate":"2008-08-01",
    "endDate":"2010-05-01",
    "email":"[email protected]",
    "phone":"11234567890",
    "fax":"+1234567890",
    "notes":"nothing"
  }
]
 
Suggest Edits

EducationDegree

Information about the candidate's education degree.

 
Attribute
Type
Description

major

string

Degree major such as "Software Systems".

degreeName

string

Name of degree such as "Bachelors" or "Masters".

degreeType

string

Type such as "B.S." or "M.S.".

graduationDate

string

Format must be YYYY-MM-DD.

degreeCompleted

boolean

A boolean to confirm whether the candidate has completed their education and received their degree.

comments

string

Any additional comments about a degree instance.

"degree" : {
    "major": "Software Systems",
    "degreeName": "Bachelors",
    "degreeType": "B.S.",
    "graduationDate": "2010-06-01",
    "degreeCompleted": true,
    "comments" : "something"
}
 
Suggest Edits

EmploymentHistory

The candidate's employment history.

 
Attribute
Type
Description

employerName

string

Name of previous employer.

currentEmployer

boolean

A boolean to confirm whether this is the candidate's current employer.

jobTitle

string

Candidate's job title under this employment.

startDate

string

Start date of employment. Format must be YYYY-MM-DD.

employmentType

string

Type of employment such as "contract" or "full time".

department

string

Department candidate worked under.

permissionToContact

boolean

Whether candidate gave permission to contact their previous employer.

reasonForLeaving

string

Candidate's reason for leaving employer.

salary

Candidate's salary at this place of employment.

verification

Supervisor or manager information.

verifyEmployer

boolean

notes

string

Any additional notes on this employer.

type

string

Type must be "faa" or "default" or "dot".

"employmentHistory":[  
  {  
    "employerName":"SomeEmployer",
    "currentEmployer":true,
    "jobTitle":"SomeJobTitle",
    "startDate":"2008-10-02",
    "endDate":"2012-10-25",
    "employmentType":"FullTime",
    "department":"IT",
    "permissionToContact":true,
    "reasonForLeaving":"nothing",
    "salary":{  
      "currency":"USD",
      "endingSalary":"140,000",
      "startingSalary":"100,000"
    },
    "type":"default",
    "verification":{  
      "supervisorGivenName":"supervisorFirstName",
      "supervisorFamilyName":"supervisorLastName",
      "supervisorMiddleName":"supervisorMiddleName",
      "address":{  
        "addressLine":"ABC company",
        "municipality":"SEATTLE",
        "regionCode":"US-WA",
        "postalCode":"98001",
        "countryCode":"US",
        "validFrom":"2008-08-01"
      },
      "email":"[email protected]",
      "phone":"+11234567890",
      "fax":"+11234567891"
    },
    "verifyEmployer":true,
    "notes":"nothing"
  }
]
 
Suggest Edits

EmploymentSalary

Amount made under a given employer within the EmploymentHistory array of objects.

 
Attribute
Type
Description

currency*

string

Salary made under a specific employer.

startingSalary

string

Starting salary at this place of employment.

endingSalary

string

Ending salary at this place of employment.

"salary" : {
  "currency" : "USD",
  "startingSalary" : "100,000",
  "endingSalary" : "140,000"
}
 
Suggest Edits

EmploymentVerification

A supervisor or manager who can be contacted to verify employment.

 
Attribute
Type
Description

supervisorGivenName*

string

First name of supervisor.

supervisorFamilyName*

string

Last name of supervisor.

supervisorMiddleName

string

Middle name of supervisor.

address

object(Address)

Address of employment.

email

string

Supervisor's email address.

phone

string

Supervisor's phone number.

fax

string

Supervisor's fax number.

"verification":{  
  "supervisorGivenName":"supervisorFirstName",
  "supervisorFamilyName":"supervisorLastName",
  "supervisorMiddleName":"supervisorMiddleName",
  "address":{  
    "addressLine":"ABC company",
    "municipality":"SEATTLE",
    "regionCode":"US-WA",
    "postalCode":"98001",
    "countryCode":"US",
    "validFrom":"2008-08-01"
  },
  "email":"[email protected]",
  "phone":"+11234567890",
  "fax":"+11234567891"
}
 
Suggest Edits

Licenses

Array of certifications or professional licenses the candidate has earned.

 
Attribute
String
Description

issuingAgency*

The agency that issued the license.

number

string

License number.

name

string

License name.

startDate

string

Start date from when license is valid.

status

string

Must be "active" or "inactive".

notes

string

Any additional notes on a given license.

"licenses":[
  {
    "issuingAgency":{
      "name":"Some Institute",
      "address":{
        "addressLine":"ABC company",
        "municipality":"SEATTLE",
        "regionCode":"US-WA",
        "postalCode":"98001",
        "countryCode":"US",
        "validFrom":"2008-08-01"
      }
    },
    "number":"S12345",
    "name":"Nursing Certification",
    "startDate":"2016-01-01",
    "status":"active",
    "notes":"some notes"
  }
]
 
Suggest Edits

LicenseIssuingAgency

Issuing agency for a candidate's license.

 
Attribute
Type
Description

name*

string

Name of issuing agency.

address

object(Address)

Address of licensing agency.

"issuingAgency":{
  "name":"Some Institute",
  "address":{
    "addressLine":"ABC company",
    "municipality":"SEATTLE",
    "regionCode":"US-WA",
    "postalCode":"98001",
    "countryCode":"US",
    "validFrom":"2008-08-01"
  }
}
 
Suggest Edits

CustomFields

Custom fields can be attached to a screening request.

 
Attribute
Type
Description

fieldName

string

The name of the custom field.

fieldValue

string

The value of the custom field.

"customFields":[
  {
    "fieldName":"Job Opening ID",
    "fieldValue":"28374953"
  },
  {
    "fieldName":"Hiring Manager",
    "fieldValue":"Jane Doe"
  },
  {
    "fieldName":"Department",
    "fieldValue":"Engineering"
  }
]
 
Suggest Edits

Requester

Information about the user requesting a screening on a candidate.

 
Attribute
Type
Description

email*

string

Email of the user requesting screening on a candidate.

givenName*

string

First name of the user requesting screening on a candidate.

familyName*

string

Last name of the user requesting screening on a candidate.

middleName

string

Middle name of the user requesting screening on a candidate.

"requester" : {
  "email" : "[email protected]",
  "givenName" : "abcFirstName",
  "familyName" : "abcLastName",
  "middleName" : "abcMiddleName"
}
 
Suggest Edits

SelfDisclosures

An array of objects to disclosing aliases and convictions in a POST /screenings request.

 
Attribute
Type
Description

address

object(Address)

Candidate's address during the time of the conviction or during the time they used the alias.

aliasFamilyName

string

First name of alias.

aliasGivenName

string

Last name of alias.

aliasMiddleName

string

Middle name of alias.

isAliasCurrentName

boolean

Boolean to confirm whether the alias is same as current name.

conviction

Information about a past conviction.

notes

string

Any additional notes.

"selfDisclosures"[
  {
    "address":{
      "addressLine":"University District",
      "municipality":"SEATTLE",
      "regionCode":"US-WA",
      "postalCode":"98001",
      "countryCode":"US",
      "validFrom":"2008-08-01"
    },
    "aliasFamilyName":"Steve",
    "aliasGivenName":"Rogers",
    "aliasMiddleName":"K",
    "isAliasCurrentName":false,
    "conviction":{
      "arrestDate":"1990-12-01",
      "caseCounty":"King",
      "convicted":false,
      "convictionDetails":"Found not guilty",
      "currentlyOnProbation":false,
      "dispositionDate":"1991-31-03",
      "offenseLevel":"Class B Felony",
      "offenseDate":"1990-29-11",
      "sentenceDate":"1990-20-04",
      "summary":"Arrest occurred but candidate was found not guilty."
    },
    "notes":"nothing"
  }
]
 
Suggest Edits

SelfDisclosureConviction

A conviction disclosed within a SelfDisclosure object in a POST /screenings request.

 
Attribute
Type
Description

arrestDate

string

Date of arrest format should be "YYYY-MM-DD".

caseCounty

string

County which has the arrest record.

convicted

boolean

Boolean confirming whether there was a conviction.

convictionDetails

string

Any additional details about the conviction.

currentlyOnProbation

boolean

Boolean confirming whether candidate is currently on probation.

dispositionDate

string

Date of final court decision on the case. Format should be "YYYY-MM-DD".

offenseLevel

string

Level of offense such as "Category IV".

offenseDate

string

Date offense was committed. Format should be "YYYY-MM-DD".

sentenceDate

string

Date of sentence format should be "YYYY-MM-DD".

summary

string

Summary of conviction.

"conviction":{
  "arrestDate":"1990-01-12",
  "caseCounty":"King",
  "convicted":false,
  "convictionDetails":"Found not guilty",
  "currentlyOnProbation":false,
  "dispositionDate":"1991-03-31",
  "offenseLevel":"Class B Felony",
  "offenseDate":"1990-11-29",
  "sentenceDate":"1990-04-20",
  "summary":"Arrest occurred but candidate was found not guilty."
}