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:

  • Perform background checks on participants in an online marketplace.
  • Create 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

How do I get access?

To gain access to the On Demand API you will need an API Client ID and Client Secret.
We provide these upon approval and a request can be made on our Developer Signup page.

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

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

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

new

A new package was created

complete

All report items are set to complete within the package

pending

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

release

A report item within this package is awaiting onset form

cancelled

The candidate did not submit their data by the expiration time

n/a, error, other

Any other status should be treated as an error

Report Results

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

clear

Everything good, the screening passes.

alert

Something found. The screening needs review.

client criteria

Check clientCriteriaResult which will have more information on whether or not the result meets a custom criteria

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.

Other

Any other status should be treated as an error

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

E-Commerce

On-Demand Javascript Widget

 

Overview

The On-Demand Javascript Widget is a Javascript component that can be deployed inside of your web site. The component allows your site to interact directly with Sterling, removing complex integration steps for you.
Key benefits of this component:
• Enables payments in compliance with PCI with no requirement for you.
• Enables candidates to pay for their own screening simplifying your finances.
• Encapsulates all the complexities in an easy to use Javascript component. Javascript event-driven flow.

Definitions

Page

A UI displayed to the end user that waits for interaction (eg a button click) before advancing the end user to another page.

Module

A specialized component of the Javascript workflow that usually performs a single task. (eg "submit a screening", "collect and create a candidate", "collect payment information"). A module may have between 0 and many pages.

Workflow

A series of modules that pass data to each other in a specific order. Modules can pass data to the next module in the workflow either automatically (eg after an API is returned) or after UI interactions (eg clicking "next")

General Technical Overview

The Javascript component enables an end-user's browser to make calls directly to the On-Demand API. In order to create trust between Sterling and the browser, the client server needs to request an "access token". This token grants very limited scope to make calls to On-Demand.

End User Browser -> Clients Server: Requests page
Client's Server -> On-Demand API: Requests an "Access Token" for the end-user
On-Demand API -> Client's Server: Returns "Access Token"
Client's Server -> End User Browser : returns a webpage contaning the javascript code and "Access Token"
End User Browser -> On-Demand API: Javascript Application can use the "Access Token" to make limited API calls.

 
Suggest Edits

Getting an Access Token

 

OAuth2 Auth

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

Body Params

subject
string

An arbitrary value that represents a unique identifier on the client's system. Two distinct end users should not share the same value. The same end user should use the same value each time. One possible solution is to use a UserID or similar unique identifier.

data
object
 
data.package
object

Package Id

 
data.candidate
object

Candidate Id

 

As the Javascript application needs an Access Token to operate, this must be created via server-side call to the On-Demand API. This token is then sent to the end-user. The access token is also used to configure some aspects of the javascript application.

Some Workflows will require a Package object or Candidate object in place of an Id

{
    "subject": "myCompanyUserId",
    "data": {
        "package": {
            "id" : "8395748"
        },
        "candidate": {
            "id" : "988054280"
        }
    }
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
    "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL2FwaS5rZW5uZWN0LmNvbS8iLCJzdWIiOiJvbmRlbWFuZHxteUNvbXBhbnlVc2VySWR8MTY5MDIzODAiLCJyb2xlcyI6WyIvaW50djEvR0VUL3BhY2thZ2VzL3thbnl9L3ByaWNlIl0sImRhdGEiOnsiYmFzZVVybCI6Imh0dHA6Ly9sb2NhbGhvc3QvcHJveHkucGhwP3VybD1odHRwczovL2FwaS1kZXYua2VubmVjdC5jb20vdjF3IiwicGFja2FnZSI6eyJpZCI6IjE2NDc0MSJ9LCJjYW5kaWRhdGUiOnsiaWQiOiIzMzI5NjYxIn19LCJpYXQiOjE1MjI4NjgzNDQsImV4cCI6MTUyMjg3MTk0NH0.RX_GDaKCEkla0U3cEJYWcTfsQo-EB7bgw0HUwT_XruM",
    "token_type": "bearer"
}
 
Suggest Edits

Adding the Javascript to a page

 

Including the javascript onto a webpage requires a script tag, and a callback function that will execute after the Javascript application is fully loaded.

<!DOCTYPE html>
<html>
<body>

<script>
    function init() {
        /* Code to go here */
    }
</script>

<script async defer src="//js.api.sterlingts.com/static/js/sterling.js?callback=init"></script>

</body>
</html>
 
Suggest Edits

Configuring the application

 

The javascript application attaches itself to the "sterlingts" namespace. In that namespace is a Config object that needs to be setup before any modules or workflows can be used. The access token aquired in step 1 would replace "ACCESS_TOKEN" in the example below.

<!DOCTYPE html>
<html>
<body>

<script>
    function init() {
        var config = new sterlingts.Config("ACCESS_TOKEN");
    /* Code to go here */
    }
</script>

<script async defer src="//js.api.sterlingts.com/static/js/sterling.js?callback=init"></script>

</body>
</html>
 
Suggest Edits

Setting up the candidate pay workflow

 

First, the Candidate pay Workflow requires an Access Token configured with a package and candidate.

Next, the candidate workflow requires an HTML DOM element to be defined. The Workflow will render to this element.

workflowOptions

Name
Description
type
required

element

required by any workflow that renders to a DOM element

Javascript DOM Element

Y*

<!DOCTYPE html>
<html>
<body>

<script>
    function init() {
        var config, workflowOptions;

        config = new sterlingts.Config("ACCESS_TOKEN");
        workflowOptions = {
            element: document.getElementById('candidatePay')
        };
      /* Code to go here */
    }
</script>

<div id="candidatePay"></div>
<script async defer src="//js.api.sterlingts.com/static/js/sterling.js?callback=init"></script>

</body>
</html>

then call the steringts.workflow.GetWorkflow object. The GetWorkflow object takes 2 arguments:

sterlingts.workflow.GetWorkflow(workflowType, workflowOptions)

argument
type
required

workflowType

sterlingts.workflow.WorkflowType

Y

workflowOptions

workflowOptions object

Y

<!DOCTYPE html>
<html>
<body>

<script>
    function init() {
        var config, workflowOptions, workflow;

        config = new sterlingts.Config("ACCESS_TOKEN");
        workflowOptions = {
            element: document.getElementById('candidatePay')
        };

        workflow = new sterlingts.workflow.GetWorkflow(
            sterlingts.workflow.WorkflowType.CREATE_SCREENING_WITH_APPLICANT_PAY,
            workflowOptions
        );
        /* Code to go here */
    }
</script>

<div id="candidatePay"></div>
<script async defer src="//js.api.sterlingts.com/static/js/sterling.js?callback=init"></script>

</body>
</html>

Finally, to have the workflow begin its experience. Call initialize();

<!DOCTYPE html>
<html>
<body>

<script>
    function init() {
        var config, workflowOptions, workflow;

        config = new sterlingts.Config("ACCESS_TOKEN");
        workflowOptions = {
            element: document.getElementById('candidatePay')
        };

        workflow = new sterlingts.workflow.GetWorkflow(
            sterlingts.workflow.WorkflowType.CREATE_SCREENING_WITH_APPLICANT_PAY,
            workflowOptions
        );

        workflow.initialize();
    }
</script>

<div id="candidatePay"></div>
<script async defer src="//js.api.sterlingts.com/static/js/sterling.js?callback=init"></script>

</body>
</html>

To get information out of the Workflow (eg screeningId after a screening is completed), this will require setting up some event handlers.
Event handlers are added by calling ".on" on the workflow object.

workflow.on(eventName, callback)

argument
type
required

eventName

String

Y

callback

function

Y

<!DOCTYPE html>
<html>
<body>

<script>
    function init() {
        var config, workflowOptions, workflow;

        config = new sterlingts.Config("ACCESS_TOKEN");
        workflowOptions = {
            element: document.getElementById('candidatePay')
        };

        workflow = new sterlingts.workflow.GetWorkflow(
            sterlingts.workflow.WorkflowType.CREATE_SCREENING_WITH_APPLICANT_PAY,
            workflowOptions
        );

        workflow.on('complete', function(output) {
            console.log("Workflow Complete:");
            console.log(output);
            console.log("Screening ID:");
            console.log(output.screening.id);
            /* Typically this callback would post relevant information back to your server for processing */
        });

        workflow.initialize();
    }
</script>

<div id="candidatePay"></div>
<script async defer src="//js.api.sterlingts.com/static/js/sterling.js?callback=init"></script>

</body>
</html>

Workflow Events

Name
When Triggered

ready

When the workflow is no longer rendering to the UI, and is ready for user interaction.

complete

When the workflow has the information it was trying to collect.

close

When the user no longer wants to conitnue with the workflow.
This usually occurs at the end of a workflow when the user clicks "done".
This event is can be used to take over the UI experiance from the JS application.

Some example uses for events:

<!DOCTYPE html>
<html>
<body>

<script>
    function init() {
        var config, workflowOptions, workflow;
      
        config = new sterlingts.Config("ACCESS_TOKEN");
        workflowOptions = {
            element: document.getElementById('candidatePay')
        };

        workflow = new sterlingts.workflow.GetWorkflow(
            sterlingts.workflow.WorkflowType.CREATE_SCREENING_WITH_APPLICANT_PAY,
            workflowOptions
        );

        workflow.on('complete', function(output) {
            console.log("Workflow Complete:");
            console.log(output);
            console.log("Screening ID:");
            console.log(output.screening.id);
            /* Typically this callback would post relevant information back to your server for processing */
        });

        workflow.on('ready', function(data) {
            console.log('Workflow Ready');
        });

        workflow.on('close', function() {
            alert('User says they are done. This could be a point where you take over the UI again');
        });

        workflow.initialize();
    }
</script>

<div id="candidatePay"></div>
<script async defer src="//js.api.sterlingts.com/static/js/sterling.js?callback=init"></script>

</body>
</html>
 
Suggest Edits

Adding the Javascript to a page

 

Including the javascript onto a webpage requires a script tag, and a callback function that will execute after the Javascript application is fully loaded.

<!DOCTYPE html>
<html>
<body>

<script>
    function init() {
      /* Code to go here */
    }
</script>

<script async defer src="//js.api.sterlingts.com/static/js/sterling.js?callback=init"></script>

</body>
</html>
 
Suggest Edits

Configuring the application

 

The javascript application attaches itself to the "sterlingts" namespace. In that namespace is a Config object that needs to be setup before any modules or workflows can be used. The access token aquired in step 1 would replace "ACCESS_TOKEN" in the example below.

<!DOCTYPE html>
<html>
<body>

<script>
    function init() {
        var config = new sterlingts.Config("ACCESS_TOKEN");
        /* Code to go here */
    }
</script>

<script async defer src="//js.api.sterlingts.com/static/js/sterling.js?callback=init"></script>

</body>
</html>
 
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?candidateId=candidateId

Path Params

id
string
required

package id to be priced

Query Params

candidateId
string
required

candidate id you are looking to price

 
curl --request GET \
  --url 'https://api-int.kennect.com/v1/packages/id/price?candidateId=candidateId'
var request = require("request");

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

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/id/price?candidateId=candidateId")

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/id/price?candidateId=candidateId");

xhr.send(data);
import requests

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

querystring = {"candidateId":"candidateId"}

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

print(response.text)
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
    }
  ]
}
{
    "errors": [
        {
            "code": "409#email?already-in-use",
            "message": "email already in use"
        }
    ]
}
{
    "errors": [
        {
            "code": "400#givenName",
            "message": "givenName is required"
        }
    ]
}
 
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)

Screening can be initiated with a charge Id ( See Charges) if you had been set up to enable ECommerce. The card token submitted to the charge object would be authorized and funds would be captured. An email receipt would be sent to the candidate on successful capture of funds.

 

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

Charge Id can also be used as Idempotency key to retry the screenings.

 
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.

chargeId
string

The charge Id generated after submitting credit card token through Sterling eCommerce widget. Please refer to Charges for more details

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",
  "chargeId": "ch_1CHgloKJBtIdnISbvHPgjG3K",
  "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"
  },
  "chargeId": "ch_1CHgloKJBtIdnISbvHPgjG3K",
  "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"}}
 
 

The candidate can pay for his background check.

The eCommerce feature shows a web component provided by Sterling for registering a card. With card registration you receive a token that can be used for payments. Call Charges to pay for the cost of the screening. The API validates the token and charges the cost of the screening to your credit card.

Please refer to E-Commerce documentation for more details.

 
 

OAuth2 Auth

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

Body Params

tokenId
string

Credit card token

amount
int64

Amount to be charged. A positive integer in the smallest currency unit (e.g., 100 cents to charge $1.00). The minimum amount is $0.50 USD

 
curl -X POST \
  https://api-dev.kennect.com/v1/charges \
  -d '{
  "tokenId": "tok_1BHflKKJBtIdnISbp5Va1gdo",
  "amount": 6601
}'
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
    "id": "ch_1CFfloKJBtIdnISbvHPgjG3K",
    "status": "succeeded"
}
 
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. In order to start an adverse action, phone number is required on the candidate.

 
 
 
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

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

In some cases you may want to collect data for every screening on one endpoint. Webhooks provide this capability and will include additional information apart from just screening updates

Any number of Webhook endpoints can be created and begin with a simple POST request.

Upon creation of the Webhook, any and all screening updates will be posted to the URI provided in the payload.

 
Suggest Edits

Create Webhook

 

OAuth2 Auth

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

Add a global webhook for all screenings.

{
  "uri": "https://www.example.com",
  "credentials": {
    "basic-auth": "narf:zort!"
  }
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "432153",
  "uri": "https://www.example.com",
  "credentials": {
    "basic-auth": "narf:zort!"
  }
}
 
Suggest Edits

Get Webhook

 

OAuth2 Auth

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

Path Params

id
string
required

Id of Webhook to look up

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

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

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/config/webhooks/1")

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/config/webhooks/1");

xhr.send(data);
import requests

url = "https://api-int.kennect.com/v1/config/webhooks/1"

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

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "432153",
  "uri": "https://www.example.com",
  "credentials": {
    "basic-auth": "narf:zort!"
  }
}
 
Suggest Edits

Update Webhook

 

OAuth2 Auth

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

Path Params

id
string
required

Id of Webhook to configure

 
{
  "uri": "https://www.example.com",
  "credentials": {
    "basic-auth": "narf:zort!"
  }
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "432153",
  "uri": "https://www.example.com",
  "credentials": {
    "basic-auth": "narf:zort!"
  }
}
 
Suggest Edits

Delete Webhook

 

OAuth2 Auth

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

Path Params

id
string
required

Id of Webhook to remove

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

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

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/config/webhooks/1")

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/config/webhooks/1");

xhr.send(data);
import requests

url = "https://api-int.kennect.com/v1/config/webhooks/1"

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