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

 

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

Using the Sterling On Demand API, you can build applications that:

  • performs background checks on participants in an online marketplace.
  • creates trusted end users, which enables members in your marketplace to screen other members in your marketplace.
  • schedule recurring screenings to proactively monitor changes in a candidate's status over time.
Suggest Edits

Getting Started

 

Below you'll find a brief overview of how API users typically consume the Sterling On Demand APIs and how you can conduct end-to-end testing on your own.

Already familiar with RESTful APIs? Great! Follow these steps to get rolling:

  • Step 1: Get Authentication
  • Step 2: GET /packages
  • Step 3: POST /candidates
  • Step 4: POST /screenings
  • Step 5: Process report using the developer portal
  • Step 6: Verify callbacks

Standard Process

  1. To get started, you’ll need your authentication credentials. Once you have that, you can jump right in.
  2. You’ll first want to call GET /packages to determine your available packages through the API. This endpoint will also specify the required candidate fields you’ll need to provide in order to initiate the screening with the associated package(s).
  3. Next, you’ll make a call to POST /candidates with the relevant fields to initiate the screening package you’ve selected. You may also first create a candidate with the minimum required fields (first name, last name, and email address). If you choose this method then you’ll need to make a call to PUT /candidates with the rest of the required fields in order to initiate the screening with the selected package (unless you use invite - see note below).
  4. Once you’ve received the candidateId from POST /candidates and packageId from GET /packages, you’ll make a call to POST /screenings with the candidateId, packageId, and callback (if desired).
  5. If the screening submission is successful then you'll receive a screeningId in the JSON payload. The next step is to process the screening so that you can complete the testing process. Login to the developer portal using your username (email) and password (apiKey). Next, locate your screeningId and process the report (e.g. alert/clear).
  6. Processing either a reportItemId(s) or the entire screening will initiate a callback. Verify you receive the callback and that you can access the report link.
  7. If applicable, test POST /screenings/{id}/adverse-actions and again use the developer portal to process the adverse action from initiated to completed.

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. This feature will need to be configured on your account first. Once configured, include the attribute "invite": "true" 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.

Suggest Edits

Authentication

 

Overview

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

Requests to the Sterling On Demand API must be authenticated using short-lived bearer token in the Authorization header. Applications will obtain bearer tokens via the oauth endpoint:

curl -X POST -H "Authorization: Basic <basic auth token>" \
-d 'grant_type=client_credentials' \
https://api-int.kennect.com/oauth/token

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, example@example.com: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).

{
  "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/v1/candidates/7212643
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 or subscription.

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 On Demand 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": "001000063194810",
    "packageId": "101337",
    "candidateId": "8675309",
    "status": "complete",
    "result": "alert",
    "reportItems": [
      {
        "id": "62113371",
        "type": "Multi-State Instant Criminal Check",
        "status": "complete",
        "result": "no data",
        "updatedAt": "2016-07-08T21:42:46Z"
      },
      {
        "id": "62113372",
        "type": "Nationwide Sex Offender Registry Check",
        "status": "complete",
        "result": "alert",
        "updatedAt": "2016-07-08T21:42:46Z"
      }
    ],
    "submittedAt": "2017-04-26T20:41:27Z",
    "updatedAt": "2017-04-26T20:42:16Z",
    "dispute": {
      "status": "active",
      "createdAt": "2017-04-26T20:41:27Z"
    },
    "links": {
      "admin": {
        "web": "https://integration.talentwise.com/screening/report.php?ApplicantID=63194810",
        "pdf": "https://integration.talentwise.com/screening/pdf-report.php?ApplicantID=63194810"
      }
    },
    "adverseActions": [
      {
        "id": "001000063194810",
        "status": "awaiting-dispute",
        "updatedAt": "2017-04-26T20:41:27Z",
        "reportItemIds": [
          "62113372"
        ]
      }
    ]
  }
}

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

Screening Invite Method

 

Overview

Invite is an option that Sterling Talent Solutions provides to bridge the API to the SterlingONE platform. Using invite allows you to specify a method that a candidate can take to finish the screening process. SterlingONE 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, one-time use link that will expire without use after 10 minutes.

The email option will email the candidate a message inviting them to log into SterlingONE with a temporary password to complete their background screening.

{
    "id": "0020000008675309",
    "packageId": "161161",
    "candidateId": "864109",
    "status": "new",
    "result": "n/a",
    "submittedAt": "2017-01-20T15:06:43Z",
    "updatedAt": "2017-01-20T15:06:43Z",
    "invite": {
        "method": "link",
        "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=TWFuIEkgbG92ZSB0YWNvcy4gVGhleSByZWFsbHkgYXJlIGp1c3Qgb25lIG9mIHRoZSBtb3N0IGlkZWFsIGZvb2RzIG9uIHRoZSBwbGFuZXQuIEV2ZW4gdGhlIGdyZWFzeSBzdHJlZXQgb25lcyBhcmUgYXdlc29tZS4gWW91J3JlIGF3ZXNvbWUgdG9vIGZvciBsb29raW5nIHRoaXMgdXAu"
    },
    "callback": {
        "uri": "https://my-company.com/screenings-callback"
    },
    "adverseActions": []
}
{
    "id": "0020000008675309",
    "packageId": "161161",
    "candidateId": "864109",
    "status": "new",
    "result": "n/a",
    "submittedAt": "2017-01-20T15:06:43Z",
    "updatedAt": "2017-01-20T15:06:43Z",
		"invite": {
        "method": "email"
    },
    "callback": {
        "uri": "https://my-company.com/screenings-callback"
    },
    "adverseActions": []
}

Invite Experience

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

Candidates that are given an invite link will be directed to this page to start the screening flow:

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.

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
400#candidate?required-fields=address.city Candidate is missing required field for identity verification: address.city
400#candidate?required-fields=address.addressLine Candidate is missing required field for identity verification: address.addressLine
400#candidate?required-fields=address.state Candidate is missing required field for identity verification: address.state
400#candidate?required-fields=address.zip Candidate is missing required field for identity verification: address.zip
400#candidate?required-fields=dob Candidate is missing required field for identity verification: dob
400#candidate?required-fields=dob Candidate is missing required field for package: dob
400#candidate?required-fields=middleName Candidate is missing required field for package: middleName (or confirmedNoMiddleName set to true)

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

Screening Errors

code reason
400#adverse-action-already-in-process An adverse action has already been initiated for this screening
400#adverse-action?configuration Adverse Action has not been configured for this account
400#report-status-not-ready Screening is not eligible for adverse action at this time
400#reportItemIds?not-allowed This report does not allow you to include the reason for initiating Adverse Action. Please remove the reportItemId(s) and resubmit.
409#clientReferenceId?already-in-use clientReferenceId already in use
409#email?already-in-use email already in use
400#identityId Trusted identifier already assigned to this candidate
400#fileName fileName is required
400#fileName fileName is required
400#driversLicense.licenseNumber?format licenseNumber is not in the expected format
400#driversLicense.issuingAgency?format issuingAgency is not in the expected format
400#kba.answers?failed Too many incorrect answers
400#kba.answers?invalid-selection Answer given for questionId {1-4} does not match any option
400#candidate?required-fields=address.city Candidate {id} is missing required field for identity verification: address.city
400#candidate?required-fields=address.addressLine Candidate {id} is missing required field for identity verification: address.addressLine
400#candidate?required-fields=address.state Candidate {id} is missing required field for identity verification: address.state
400#candidate?required-fields=address.postalCode Candidate {id} is missing required field for identity verification: address.postalCode
422#identity?retry-limit-exceeded Retry limit exceeded
400#candidateId?not-found candidateId must be a valid candidateId associated with the authenticated account
400#kba.answers All kba questions must be answered
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#trustedUserId?not-found trusted user must be a valid, active trusted user
400#documentType documentType must be one of: [end-user-agreement, disclosure-and-authorization]
400#party party must be one of: [candidate, trusted-user]
400#candidateId?not-found candidateId must be a valid candidateId associated with the authenticated account
400#ticketing Invalid value some-bad-value in field: ticketing
400#documentType documentType must be one of: [end-user-agreement, disclosure-and-authorization]
400#trustedUserId?not-found trusted user must be a valid, active trusted user
400#party party must be one of: [candidate, trusted-user]
400#schedule.startAt?format schedule.startAt must be a UTC time with date, hours, and minutes, like 2016-10-30T20:00:00.000Z
400#candidate-and-package-already-subscribed A subscription already exists for this candidate and package
400#schedule.endAt?format schedule.endAt must be a UTC time with date, hours, and minutes, like 2016-10-30T20:00:00.000Z
400#candidate-and-package-already-subscribed A subscription already exists for this candidate and package
400#candidate?required-fields=dob Candidate {id} is missing required field for package {id}: dob.
400#candidate?required-fields=middleName Candidate {id} is missing required field for package {id}: middleName.
400#identityId Trusted identifier already assigned to this candidate
400#identityId identity id must belong to a verified identity
Suggest Edits

Versioning

 

This document describes Sterling On Demand API version 1. The Sterling On Demand API follows semantic versioning, which means that we are committed to maintaining this API without breaking changes. The Sterling On Demand API 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.

 

You can think of packages as your team's predefined background screening recipes. The Sterling On Demand 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/v1/packages
curl --request GET \
  --url https://api-int.kennect.com/v1/packages
var request = require("request");

var options = { method: 'GET',
  url: 'https://api-int.kennect.com/v1/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/v1/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/v1/packages");

xhr.send(data);
import requests

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

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

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

[
  {
    "id": "1234",
    "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

/packages/{id}/price

Get the price of a screening

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api-int.kennect.com/v1/packages/id/price

Path Params

id
string
required

package id to be priced

Query Params

candidateId
string
required

candidate id you are looking to price

curl -X GET \
  'https://api-int.kennect.com/v1/packages/{id}/price?candidateId={candidateId}' 
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "currencyType": "USD",
  "total": 195.16
}
{
  "errors": [
    {
      "code": "400#candidateId?not-found",
      "message": "candidateId must be a valid candidateId associated with the authenticated account"
    }
  ]
}
{
    "errors": [
        {
            "code": "400#candidate?required-fields=address.addressLine",
            "message": "Candidate {{id}} is missing required field for package {{id}}: address.addressLine."
        },
        {
            "code": "400#candidate?required-fields=dob",
            "message": "Candidate {{id}} is missing required field for package {{id}}: dob."
        },
        {
            "code": "400#candidate?required-fields=ssn",
            "message": "Candidate {{id}} is missing required field for package {{id}}: ssn."
        },
        {
            "code": "400#candidate?required-fields=address.postalCode",
            "message": "Candidate {{id}} is missing required field for package {{id}}: 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

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
posthttps://api-int.kennect.com/v1/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

A Candidate Address. Please refer to Address

 
address.addressLine
string
required

The candidate's residential street address, such as "123 Main Street"

address.municipality
string

The city or town of the address

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"

address.postalCode
string
required

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

address.countryCode
string
required

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

driversLicense
object

Driver's license information. Please refer to DriversLicense

 
driversLicense.type
string

Driver's license type (personal or commercial)

driversLicense.licenseNumber
string
required

Driver's license number

driversLicense.issuingAgency
string
required

Driver's license issuing agency - ISO 3166-2 region

aliases
object

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

 
aliases.givenName
string
required

The Candidate's alternate first name

aliases.familyName
string
required

The Candidate's alternate last name

aliases.middleName
string

The Candidate's alternate middle name

aliases.confirmedNoMiddleName
boolean

Set to 'True' if the Candidate has no alternate middle name

Request to create a new candidate

curl -X POST \
  https://api-int.kennect.com/v1/candidates \
  -d '{
 "clientReferenceId": "e4e1ffda-caa3-ea6d-c095-be8429b31154,
 "givenName": "John",
 "confirmedNoMiddleName": true,
 "familyName": "Doe",
 "dob": "1998-07-18",
 "email": "john@example.com",
 "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
  }]
}'
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "10001",
  "clientReferenceId": "e4e1ffda-caa3-ea6d-c095-be8429b31154",
  "email": "john@example.com",
  "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": "Robert",
      "middleName": "William",
      "confirmedNoMiddleName": false,
      "familyName": "Saur"
    },
    {
      "givenName": "Simon",
      "familyName": "Duck",
      "confirmedNoMiddleName": true
    }
  ]
}
Suggest Edits

/candidates/{id}

 

OAuth2 Auth

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

Path Params

id
string
required

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

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

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

 
address.addressLine
string
required

The candidate's residential street address, such as "123 Main Street"

address.municipality
string

The city or town of the address

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"

address.postalCode
string
required

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

address.countryCode
string
required

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

driversLicense
object

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

 
driversLicense.type
string

Driver's license type (personal or commercial)

driversLicense.licenseNumber
string
required

Driver's license number

driversLicense.issuingAgency
string
required

Driver's license issuing agency - ISO 3166-2 region

aliases
object

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

 
aliases.givenName
string
required

The Candidate's alternate first name

aliases.familyName
string
required

The Candidate's alternate last name

aliases.middleName
string

The Candidate's alternate middle name

aliases.confirmedNoMiddleName
boolean

Set to 'True' if the Candidate has no alternate middle name

curl -X PUT \
  https://api-int.kennect.com/v1/candidates/1226939 \
  -d '{
  "id": "10001",
  "clientReferenceId": "e4e1ffda-caa3-ea6d-c095-be8429b31154",
  "email": "john@example.com",
  "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"
  }
}'
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "10001",
  "clientReferenceId": "e4e1ffda-caa3-ea6d-c095-be8429b31154",
  "email": "john@example.com",
  "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": "Robert",
      "middleName": "William",
      "confirmedNoMiddleName": false,
      "familyName": "Saur"
    },
    {
      "givenName": "Simon",
      "familyName": "Duck",
      "confirmedNoMiddleName": true
    }
  ]
}
Suggest Edits

/candidates/{id}

Get the candidate with the unique identifier

 

OAuth2 Auth

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

Path Params

id
string
required

candidate id

curl -X GET \
  https://api-int.kennect.com/v1/candidates/{id}
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "10001",
  "clientReferenceId": "e4e1ffda-caa3-ea6d-c095-be8429b31154",
  "email": "john@example.com",
  "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"
  },
  "screenings": [],
  "aliases": [
    {
      "givenName": "Robert",
      "middleName": "Saur",
      "confirmedNoMiddleName": false,
      "familyName": "William"
    },
    {
      "givenName": "Simon",
      "familyName": "Duck",
      "confirmedNoMiddleName": true
    }
  ]
}
Suggest Edits

/candidates

List Candidates

 

OAuth2 Auth

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

Query Params

clientReferenceId
string

filter by the provided clientReferenceId value

email
string

filter by the provided email value

givenName
string

filter by the provided given name

familyName
string

filter by the provided family name

limit
string

limit results to the specified number

offset
string

offset the results by the specified number

curl --request GET \
  --url https://api-int.kennect.com/v1/candidates
var request = require("request");

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

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/v1/candidates")

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/v1/candidates");

xhr.send(data);
import requests

url = "https://api-int.kennect.com/v1/candidates"

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

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "10001",
  "clientReferenceId": "e4e1ffda-caa3-ea6d-c095-be8429b31154",
  "email": "john@example.com",
  "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"
  }
}
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 /v1/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 /v1/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 adverse actions and disputes as well as 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

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
posthttps://api-int.kennect.com/v1/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

 
callback.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.

callback.credentials
object

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

 
invite
object

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

 
invite.method
string

method in which to invite the candidate to complete information - can be 'email' or 'link'

referenceCodes
array of strings

Client specified codes

billingCode
string

Client specified code

endUserCertificate
string

Screening has to be submitted with end user agreement in non-invite flow. true if the end user agreement is present. false if end user agreement/certificate may not be present

trustedUserId
string

Once a candidate has passed identity verification, the candidate can be granted trust. An application can then submit screening requests on behalf of the trusted user.

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

pending
complete
canceled

result

n/a
client criteria

clientCriteriaResult

does not meet criteria - review (if the result is client criteria)

{
  "packageId": "64731",
  "candidateId": "864109",
  "endUserCertificate": "true",
  "callback": {
    "uri": "https://my-company.com/screenings-callback",
    "credentials": {
        "basic-auth": "narf:zort!"
    }
  },
  "referenceCodes": [
    "US",
    "WA",
    "Seattle"
  ],
  "billingCode": "Northwest"
}
curl -X POST \
  https://api-int.kennect.com/v1/screenings \
  -H 'idempotency-key: {idempotencyKey}' \
  -H 'authorization: Bearer token-hash' \
  -H 'content-type: application/json' \
  -d '{ 
    "candidateId": "927084",
    "packageId": "164741",
    "endUserCertificate":"true",
    "callback": {
      "uri": "https://my-company.com/screenings-callback",
      "credentials": {
        "basic-auth": "narf:zort!"
      }
    }
}'
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "001000063225945",
  "packageId": "164741",
  "candidateId": "927084",
  "status": "pending",
  "result": "n/a",
  "reportItems": [
    {
      "id": "63225946",
      "type": "Criminal Check by Jurisdiction",
      "status": "pending",
      "result": "n/a",
      "updatedAt": "2017-05-04T20:36:33Z"
    },
    {
      "id": "63225947",
      "type": "Federal Criminal Check",
      "status": "pending",
      "result": "n/a",
      "updatedAt": "2017-05-04T20:36:33Z"
    },
    {
      "id": "63225948",
      "type": "Multi-State Instant Criminal Check",
      "status": "pending",
      "result": "n/a",
      "updatedAt": "2017-05-04T20:36:33Z"
    },
    {
      "id": "63225949",
      "type": "Nationwide Sex Offender Registry Check",
      "status": "pending",
      "result": "n/a",
      "updatedAt": "2017-05-04T20:36:33Z"
    }
  ],
  "submittedAt": "2017-05-04T20:36:33Z",
  "updatedAt": "2017-05-04T20:36:33Z",
  "dispute": {
    "status": "active",
    "createdAt": "2017-05-04T20:36:34Z"
  },
  "links": {
    "admin": {
      "web": "https://integration.talentwise.com/screening/report.php?ApplicantID=63225945",
      "pdf": "https://integration.talentwise.com/screening/pdf-report.php?ApplicantID=63225945"
    }
  },
  "callback": {
    "uri": "https://mockbin.org/bin/b87c5aec-cb87-4dfc-8550-031bbe560407"
  },
  "adverseActions": []
}
{
  "id": "001000063225945",
  "packageId": "164741",
  "candidateId": "927084",
  "status": "new",
  "result": "n/a",
  "submittedAt": "2017-05-04T20:38:05Z",
  "updatedAt": "2017-05-04T20:38:05Z",
  "invite": {
        "method": "email"
    },
  "callback": {
    "uri": "https://mockbin.org/bin/b87c5aec-cb87-4dfc-8550-031bbe560407"
  },
  "adverseActions": []
}
{
  "id": "001000063225945",
  "packageId": "164741",
  "candidateId": "927084",
  "status": "new",
  "result": "n/a",
  "submittedAt": "2017-05-04T20:38:05Z",
  "updatedAt": "2017-05-04T20:38:05Z",
  "invite": {
        "method": "link",
        "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=TWFuIEkgbG92ZSB0YWNvcy4gVGhleSByZWFsbHkgYXJlIGp1c3Qgb25lIG9mIHRoZSBtb3N0IGlkZWFsIGZvb2RzIG9uIHRoZSBwbGFuZXQuIEV2ZW4gdGhlIGdyZWFzeSBzdHJlZXQgb25lcyBhcmUgYXdlc29tZS4gWW91J3JlIGF3ZXNvbWUgdG9vIGZvciBsb29raW5nIHRoaXMgdXAu"
    },
  "callback": {
    "uri": "https://mockbin.org/bin/b87c5aec-cb87-4dfc-8550-031bbe560407"
  },
  "adverseActions": []
}
{
  "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"
        }
    ]
}
Suggest Edits

/screenings/{id}

Request to fetch the screening using the unique Identifier

 

OAuth2 Auth

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

Path Params

id
string
required

id of the screening to look up

curl -X GET \
  https://api-int.kennect.com/v1/screenings/{id} 
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "00100008675309",
  "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"
  },  
  "referenceCodes": [
        {
            "code": "US"
        },
        {
            "code": "WA"
        },
        {
            "code": "Seattle"
        }
    ],
  "adverseActions": [
    {
      "id": "00100006255586",
      "status": "pending",
      "updatedAt": "2016-11-28T18:25:11Z"
    }
  ]
}
{
  "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/v1/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/v1/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
 

Address of the candidate

Attribute
Type
Description

addressLine*

string

The candidate's residential street address, such as "123 Main Street"

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"

"address": {
        "addressLine": "123 PEACHTREE PLACE",
        "municipality": "ATLANTA",
        "regionCode": "US-GA",
        "postalCode": "12345",
        "countryCode": "US"
    }
Suggest Edits

DriversLicense

 

The candidate's driver's license

Attribute
Type
Description

type

enum[string]

Driver's license type (personal or commercial)

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 On Demand 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

legacyInvite

boolean

"invite": {
        "method": "link",
        "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

/screenings/{id}/invite

Create invite for existing screening

 

OAuth2 Auth

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

Path Params

id
string
required

id of the screening

Body Params

invite
object
 
invite.method
string

method in which to invite the candidate to complete information - can be 'email' or 'link'

curl -X POST \
  https://api-int.kennect.com/v1/screenings/{id}/invite 
  -d '{
	"invite":{
        "method":"link"
    }
A binary file was returned

Your OAuth2 token is incorrect or has expired

{"invite":{"method":"link","link": "https://portal.integration.talentwise.com/438a7d2ee6/ptl/ticketeda.php?ID=MTY5MDIzODA&code=FwLsDCxhI804fEiZ&ticket=472316&&Sender=18902380&Email=515d9b1e-f197-464f-9bdc-2258520d7fac%40example.com&OverrideCandidateID=3317606&KennectApiToken=hash-token"}}
Suggest Edits

Subscriptions

The subscriptions resource allow for recurring screenings of candidates at a fixed interval. Creating a subscription requires a candidate and a package, just like a screening, and inherits all the validations that apply to a screening. Additionally, they require a schedule that defines the start date and repeat interval of the subscription, including an optional end date. The candidate must have all the required fields for the package, just like when creating a screening.

Candidates can be updated after a screening is created, which may be necessary if the candidate moves or changes their name. When updating a candidate who is the subject of a subscription, the Sterling On Demand API will validate that all required fields for the subscription package are still present.

Subscriptions can be disabled by using the DELETE method. Disabled subscriptions cannot be renabled, but the schedule definition and event history remain available for future reference.

 
Suggest Edits

/subscriptions

 

OAuth2 Auth

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

Body Params

screening
object
 
screening.packageId
string
required

Package Id of the Screening

screening.candidateId
string
required

Candidate Id of the screening

screening.callback
object

Callbacks

 
screening.callback.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.

screening.callback.credentials
object

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

 
schedule
object
 
schedule.startAt
date

date to begin the subscription, as an ISO-8601 string

schedule.endAt
date

date to end the subscription, as an ISO-8601 string

schedule.interval
object

Interval

 
schedule.interval.unit
string
required

enum[string] - must be days, weeks, or months

schedule.interval.value
integer
required

Interval value

{
  "screening": {
    "packageId": "123456",
    "candidateId": "9876543",
    "callback": {
      "uri": "https://clients.domain.com/path?parameters"
    }
  },
  "schedule": {
    "startAt": "2016-01-30T00:00:00Z",
    "endAt": "2018-01-30T00:00:00Z",
    "interval": {
      "unit": "months",
      "value": 3
    }
  }
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "46",
  "status": "enabled",
  "screening": {
    "packageId": "123456",
    "candidateId": "9876543",
    "callback": {
      "uri": "https://clients.domain.com/path?parameters"
    }
  },
  "schedule": {
    "startAt": "2016-01-30T00:00:00Z",
    "endAt": "2018-01-30T00:00:00Z",
    "interval": {
      "unit": "months",
      "value": 3
    }
  },
  "createdAt": "2016-12-02T20:11:23.634Z",
  "updatedAt": "2016-12-02T20:11:23.634Z",
  "nextRunAt": "2016-12-01T20:55:20.281Z"
}
Suggest Edits

/subscriptions/{id}

Request to fetch the subscription using the unique Identifier

 

OAuth2 Auth

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

Path Params

id
string
required

.

curl --request GET \
  --url https://api-int.kennect.com/v1/subscriptions/id
var request = require("request");

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

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/v1/subscriptions/id")

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/v1/subscriptions/id");

xhr.send(data);
import requests

url = "https://api-int.kennect.com/v1/subscriptions/id"

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

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "46",
  "status": "enabled",
  "screening": {
    "packageId": "164741",
    "candidateId": "1123597",
    "callback": {
      "uri": "https://clients.domain.com/path?parameters"
    }
  },
  "schedule": {
    "startAt": "2016-01-30T00:00:00Z",
    "endAt": "2018-01-30T00:00:00Z",
    "interval": {
      "unit": "months",
      "value": 3
    }
  },
  "createdAt": "2016-12-02T20:11:23.634Z",
  "updatedAt": "2016-12-02T20:11:23.634Z",
  "nextRunAt": "2016-12-01T20:55:20.281Z"
}
Suggest Edits

/subscriptions/{id}

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
deletehttps://api-int.kennect.com/v1/subscriptions/id

Path Params

id
string
required
curl --request DELETE \
  --url https://api-int.kennect.com/v1/subscriptions/id
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api-int.kennect.com/v1/subscriptions/id' };

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/v1/subscriptions/id")

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

request = Net::HTTP::Delete.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("DELETE", "https://api-int.kennect.com/v1/subscriptions/id");

xhr.send(data);
import requests

url = "https://api-int.kennect.com/v1/subscriptions/id"

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

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

Try the API to see results
Suggest Edits

Adverse Action

Under the Fair Credit Reporting Act, candidates are entitled to receive notice when there is a chance that they could be denied an opportunity based in whole or in part on the contents of a background report. This process is called “Adverse Action”, and includes an initial “pre-adverse” notice to the candidate with an opportunity to dispute the contents of the report. A successful dispute can overturn the adverse action, but a failed dispute or an undisputed adverse action will lead to a final notice of adverse action.

The applicant is given a chance to review their background report, and dispute the findings if it is incomplete or inaccurate before a final decision is made.

 
Suggest Edits

/screenings/{id}/adverse-actions

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
posthttps://api-int.kennect.com/v1/screenings/id/adverse-actions

Path Params

id
string
required

screening id

Body Params

reportItemIds
array of strings

List of report item ids that will be receiving adverse action

comment
string

Text explaining the reason for the adverse action (not every item can take a reason)

{
  "reportItemIds": [
    "62604058"
  ],
  "comment": "This is a reason for the adverse action"
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

Try the API to see results
Suggest Edits

Documents

 

In some cases, supporting documents must be provided for a candidate or a screening to be completed and made available to requesters. The payload of the POST request should be the binary file contents, represented as a stream or array of bytes. Avoid encoding the payload as text, as this will result in blank, unreadable PDF files.

Care should be taken with binary file contents, as some languages may change encoding internally. Check your library's documentation for handling binary data.

File Requirements

The maximum file size is 10MB. Files larger than 10MB will result in a 413 error response.
Files must be in .pdf format

Suggest Edits

/screenings/{id}/documents

 

OAuth2 Auth

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

Path Params

id
string
required

the unique identifier of the screening you wish to include documents for

Body Params

documentType
string
required

Possible values: disclosure-and-authorization, end-user-agreement

party
string
required

Possible values: candidate , trusted-user

curl --request POST \
  'https://api-int.kennect.com/v1/screenings/{id}/documents?documentType={documentType}&party={party}' \
  -H 'authorization: Bearer token-hash' \
  -H 'content-type: application/octet-stream' \
  --data-binary '@{filename.ext}'
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "errors": [
    {
      "code": "400",
      "message": "Body must include binary file"
    }
  ]
}
{
  "errors": [
    {
      "code": "415#requires-octet-stream",
      "message": "this endpoint requires content type application/octet-stream."
    }
  ]
}
Suggest Edits

/screenings/{id}/documents

List all the documents of a Screening

 

OAuth2 Auth

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

Path Params

id
string
required

the unique identifier of the screening you wish to fetch the documents for

curl -X GET \
  https://api-int.kennect.com/v1/screenings/002000001135011/documents 
A binary file was returned

Your OAuth2 token is incorrect or has expired

[
    {
        "id": "1234567",
        "candidateId": "123456789",
        "fileName": "Filename1.cvs",
        "fileType": "Electronic Disclosure",
        "createdAt": "2018-01-23T00:31:28Z",
        "updatedAt": "2018-01-23T00:31:28Z"
    },
    {
        "id": "1234567",
        "candidateId": "987928030",
        "fileName": "Filename2.pdf",
        "fileType": "Electronic Disclosure",
        "createdAt": "2018-01-23T00:24:59Z",
        "updatedAt": "2018-01-23T00:24:59Z"
    },
    {
        "id": "1234567",
        "candidateId": "987928030",
        "fileName": "Filename3-20180122155242.pdf",
        "fileType": "Electronic Disclosure",
        "createdAt": "2018-01-22T23:52:42Z",
        "updatedAt": "2018-01-22T23:52:42Z"
    }
]
Suggest Edits

/screenings/{id}/documents/{attachmentId}

Request to fetch the document associated with screening

 

OAuth2 Auth

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

Path Params

id
string
required

the unique identifier of the screening you wish to fetch documents for

attachmentId
string
required

the unique identifier of the attachment

curl -X GET \
  https://api-dev.kennect.com/v1/screenings/{id}/documents/{attachmentId} \
  -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

/candidates/{id}/documents

Request to add document of a Candidate

 

OAuth2 Auth

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

Path Params

id
string
required

the unique identifier of the candidate you wish to include documents for

Body Params

fileName
string

The file name

curl -X POST \
  'https://api-int.kennect.com/v1/candidates/123456789/documents?fileName=filename.pdf' \
  -H 'authorization: Bearer token-hash' \
  -H 'content-type: application/octet-stream'
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "errors": [
    {
      "code": "400#fileName",
      "message": "fileName is required"
    }
  ]
}
{
  "errors": [
    {
      "code": "400#fileAttachment",
      "message": "file must be attached"
    }
  ]
}
Suggest Edits

/candidates/{id}/documents

Request to fetch the all the documents associated to a Candidate

 

OAuth2 Auth

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

Path Params

id
string
required

the unique identifier of the candidate you wish to fetch documents for

curl -X GET \
  https://api-dev.kennect.com/v1/candidates/{id}/documents \
  -H 'accept: application/json' \
  -H 'authorization: Bearer token-hash' 
A binary file was returned

Your OAuth2 token is incorrect or has expired

[
    {
        "id": "1111111",
        "candidateId": "912345678",
        "fileName": "filename1.pdf",
        "createdAt": "2018-03-30T19:11:51Z",
        "updatedAt": "2018-03-30T19:11:51Z"
    },
    {
        "id": "2222222",
        "candidateId": "912345678",
        "fileName": "filename2.pdf",
        "createdAt": "2018-03-30T18:02:53Z",
        "updatedAt": "2018-03-30T18:02:53Z"
    }
]
Suggest Edits

Identity

The /identities resource allows Sterling Talent Solutions to verify the identity of a user. In the context of the Sterling On Demand API, identity verification is one prerequisite for granting trusted status.

Unlike a background screening, identity verification does not imply that the individual has passed a background check. Instead, identity verification allows a user to establish that the candidate is who they say they are.

 

Identity Retries and Offline Verification

If the candidate fails after these attempts, an offline verification method is highly recommended through your support teams. If a candidate is verified in this manner, a POST to /identities does not have to be made.

We require the allocation of three attempts for candidates to complete their identity verification before failing over to a manual approach.

Suggest Edits

/identities

Request to fetch verify an identity

 

OAuth2 Auth

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

Body Params

candidateId
string
required

the candidate seeking verification

type
string

Possible values: kba or client verified

{
  "candidateId": "123124"
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "1123123",
  "candidateId": "123124",
  "status": "pending",
  "kba": {
    "questions": [
      {
        "id": "1",
        "prompt": "What's your favorite number?",
        "answers": [
          "14",
          "42",
          "tau",
          "e",
          "planck's constant"
        ]
      },
      {
        "id": "2",
        "prompt": "Where do you live?",
        "answers": [
          "mercury",
          "venus",
          "earth",
          "mars",
          "oort cloud"
        ]
      }
    ]
  }
}
{
    "errors": [
        {
            "code": "400#candidateId",
            "message": "Candidate already has an identity record"
        }
    ]
}
Suggest Edits

/identities/{id}

Request to fetch the identity using the unique Identifier

 

OAuth2 Auth

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

Path Params

id
string
required

the unique identifier for the identity resource

curl --request GET \
  --url https://api-int.kennect.com/v1/identities/id
var request = require("request");

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

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/v1/identities/id")

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/v1/identities/id");

xhr.send(data);
import requests

url = "https://api-int.kennect.com/v1/identities/id"

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

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "1123123",
  "candidateId": "123124",
  "status": "pending",
  "kba": {
    "questions": [
      {
        "id": "1",
        "prompt": "What's your favorite number?",
        "answers": [
          "14",
          "42",
          "tau",
          "e",
          "planck's constant"
        ]
      },
      {
        "id": "2",
        "prompt": "Where do you live?",
        "answers": [
          "mercury",
          "venus",
          "earth",
          "mars",
          "oort cloud"
        ]
      }
    ]
  }
}
Suggest Edits

/identities/{id}/retry

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
posthttps://api-int.kennect.com/v1/identities/id/retry

Path Params

id
string
required

the unique identifier for the identity resource attempting retry

curl --request POST \
  --url https://api-int.kennect.com/v1/identities/id/retry
var request = require("request");

var options = { method: 'POST',
  url: 'https://api-int.kennect.com/v1/identities/id/retry' };

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/v1/identities/id/retry")

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

request = Net::HTTP::Post.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("POST", "https://api-int.kennect.com/v1/identities/id/retry");

xhr.send(data);
import requests

url = "https://api-int.kennect.com/v1/identities/id/retry"

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

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "1123123",
  "candidateId": "123124",
  "status": "pending",
  "kba": {
    "questions": [
      {
        "id": "1",
        "prompt": "What's your favorite number?",
        "answers": [
          "14",
          "42",
          "tau",
          "e",
          "planck's constant"
        ]
      },
      {
        "id": "2",
        "prompt": "Where do you live?",
        "answers": [
          "mercury",
          "venus",
          "earth",
          "mars",
          "oort cloud"
        ]
      }
    ]
  }
}
Suggest Edits

/identities/{id}/verification

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
puthttps://api-int.kennect.com/v1/identities/id/verification

Path Params

id
string
required

the unique identifier for the identity resource

{
  "kba": {
    "questions": [
      {
        "prompt": "In which county have you lived?",
        "id": "1",
        "answers": [
          "DIVIDE",
          "FULTON",
          "MARSHALL",
          "None of the above"
        ]
      },
      {
        "prompt": "Between 1999 and 2002, in which State did you live?",
        "id": "2",
        "answers": [
          "MISSOURI",
          "NEW YORK",
          "OKLAHOMA",
          "None of the above"
        ]
      },
      {
        "prompt": "What type of residence is 4545 MAPLE VIEW PLACE?",
        "id": "3",
        "answers": [
          "Single Family Residence",
          "Apartment",
          "Condominium",
          "None of the above"
        ]
      }
    ],
    "answers": [
      {
        "questionId": "1",
        "response": "FULTON"
      },
      {
        "questionId": "2",
        "response": "NEW YORK"
      },
      {
        "questionId": "3",
        "response": "Single Family Residence"
      }
    ]
  }
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "867",
  "candidateId": "1191285",
  "status": "verified"
}
{
    "errors": [
        {
            "code": "422#expired",
            "message": "Questions for identity {{identityId}} have expired. Please initiate a retry using /identities/{{identityId}}/retry"
        }
    ]
}
Suggest Edits

Trust

Once a candidate has passed identity verification, the candidate can be granted trust. An application can then submit screening requests on behalf of the trusted user. This trust, along with a permissible purpose, allows the trusted user to review the screening report and approve or reject the candidate for that purpose.

Trust can be revoked by making a request to the DELETE endpoint.

 
Suggest Edits

/candidates/{id}/trust

create trust for a trusted user

 

OAuth2 Auth

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

Path Params

id
string
required

Candidate ID

Body Params

identityId
string
required

id for identity verification; result must = verified in order to create trust

{
  "identityId": "10103"
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "123",
  "identityId": "10103"
}
Suggest Edits

/trusted-users/{id}

lookup a trusted user

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api-int.kennect.com/v1/trusted-users/id

Path Params

id
string
required

Trusted user ID

curl --request GET \
  --url https://api-int.kennect.com/v1/trusted-users/id
var request = require("request");

var options = { method: 'GET',
  url: 'https://api-int.kennect.com/v1/trusted-users/id' };

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/v1/trusted-users/id")

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/v1/trusted-users/id");

xhr.send(data);
import requests

url = "https://api-int.kennect.com/v1/trusted-users/id"

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

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "123",
  "identityId": "10103"
}
Suggest Edits

/trusts/{id}

revoke trust from a trusted user

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
deletehttps://api-int.kennect.com/v1/trusts/id

Path Params

id
string
required

trust id

curl --request DELETE \
  --url https://api-int.kennect.com/v1/trusts/id
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api-int.kennect.com/v1/trusts/id' };

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/v1/trusts/id")

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

request = Net::HTTP::Delete.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("DELETE", "https://api-int.kennect.com/v1/trusts/id");

xhr.send(data);
import requests

url = "https://api-int.kennect.com/v1/trusts/id"

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

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

Try the API to see results
Suggest Edits

Codes

A pair of GETs for billing-codes and reference-codes, respectively, are available to allow for the listing of existing billing or reference codes available to your account.

 
Suggest Edits

/reference-codes

Get the reference codes associated with the API account

 

OAuth2 Auth

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

var options = { method: 'GET',
  url: 'https://api-int.kennect.com/v1/reference-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/v1/reference-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/v1/reference-codes");

xhr.send(data);
import requests

url = "https://api-int.kennect.com/v1/reference-codes"

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

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "referenceCodes": [
    {
      "code": "US",
      "codes": [
        {
          "code": "WA",
          "codes": [
            {
              "code": "Bellevue"
            },
            {
              "code": "Bothell"
            },
            {
              "code": "Seattle"
            }
          ]
        },
        {
          "code": "NY",
          "codes": [
            {
              "code": "New York"
            }
          ]
        },
        {
          "code": "CO",
          "codes": [
            {
              "code": "Denver"
            }
          ]
        },
        {
          "code": "CA",
          "codes": [
            {
              "code": "San Diego"
            },
            {
              "code": "San Francisco"
            }
          ]
        }
      ]
    }
  ]
}
Suggest Edits

/billing-codes

Get the billing codes associated with the API account

 

OAuth2 Auth

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

var options = { method: 'GET',
  url: 'https://api-int.kennect.com/v1/billing-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/v1/billing-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/v1/billing-codes");

xhr.send(data);
import requests

url = "https://api-int.kennect.com/v1/billing-codes"

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

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
    "billingCodes": [
        "Bellevue-WA",
        "New Offer Program"
    ]
}