Yardstik Api (1.0)

Introduction

Yardstik is a modern, RESTful API-driven background screening service.
Yardstik uses resource-oriented URLs, supports authentication via a single header API Key, and leverages JSON in all responses passed back.

Authentication

Yardstik uses API keys to authenticate your API requests.
All API requests require an API key and an Accept: header set to application/json.
An authentication error will be returned if you do not include a key when making a request.

SecretApiKey

When your account is created, you are given your first secret API key. Also you may generate additional API keys and delete API keys (as you may need to rotate your keys in the future).
You may view and manage your API keys in your dashboard under Developer Settings.

Security Scheme Type API Key
Header parameter name: Authorization

Keep your keys safe

Access to your API keys should be granted only to those who need to make API requests on your behalf. API keys are able to perform any API request to the Yardstik API without restriction. API keys should be kept confidential and only stored on your own servers.

Getting Started

This will walk you through the steps necessary to successfully run a background check using Yardstik

Get your Account

Before being able to use the Yardstik APIs and Dashboard, each account must be properly verified. To create an account, you must work with a Yardstik Account Executive or Customer Success representative. Yardstik complies with laws and regulations of federal, state, local governments and makes it easy for you to comply with all applicable laws and regulations.

In the United States this is primarily regulated by the Fair Credit Report Act (FCRA). The FCRA requires that you establish a legitimate "permissible purpose" before running a background screen on an individual. Permissible purposes include employment screen, extending credit, or a "legitimate business purpose".

Yardstik works with you to establish a permissible purpose by collection and confirming your information. If you have created a custom user experience within your application, the Yardstik Customer Success team will work with you to ensure that it is coompliant with all laws and regulations which may impact you.

Get your API key

Managing your API keys is always available on your account dashboard. Once your Yardstik account has been created, login to your dashboard and go to Developer Settings and create your first API key. For more information on the types of API keys, see Authenticantion above.

Authenticate with Yardstik

Example Authenticated Response:

[
    {
        "id": "cc0df11d-a502-47ec-8aa1-ba0738030ca7",
        "account_name": "Global Dynamics",
        "first_name": "Nathan",
        "last_name": "Stark",
        "email_address": "nathan.stark@globaldynamics.com",
        "url": "https://www.globaldynamics.com",
        "tech_email_address": "it@globaldynamics.com",
        "support_email_address": "support@globaldynamics.com",
        "support_phone": "541-555-4376",
        "actions_email_address": "hr@globaldynamics.com",
        "compliance_email_address": "hr@globaldynamics.com",
        "logo": "https://vignette.wikia.nocookie.net/eureka/images/d/dd/Global_dynamics.jpg",
        ...
    },
    ...
]

Yardstik uses HTTP API key authentication. Authentication with Yardstik is easy, simply include an account API key from your Developer Settings in the header of all your API requests.

Example Authenticated Request:

curl -X GET https://api.yardstik.com/accounts \
    -H 'Authorization: Account [YOUR_API_KEY]' \
    -H 'Accept: application/json'

Create an Invitation

Example Invitation Response:

{
    "id": "18e00b78-e620-4ecf-a01a-eb810f1b6751",
    "email_address": "jack.carter@globaldynamics.com",
    "name": "Jack Carter",
    "package_id":"04689d9c-a3c8-4b96-9662-53d972f14122",
    "expires_at": "2020-06-17T20:37:20.485Z",
    "candidate_id": null,
    "invitation_code": null,
    "required_fields": [
        "first_name",
        "last_name",
        "ssn",
        "email_address",
        "city",
        "state",
        "zip_code",
        "date_of_birth"
    ],
    ...
}

Start a background check by sending an invitation to an candidate.

See Invitations for more information.

Note:

  • The email_address attribute is required.
  • The name attribute is required and represent the candidates full name.
  • The package_id attribute is required. See Packages for more information.

Example Invitation Request:

curl -X POST https://api.yardstik.com/invitations \
    -H 'Authorization: Account [YOUR_API_KEY]' \
    -H 'Accept: application/json'
    -H 'Content-Type: application/json' \
    --data-raw '{
        "email_address": "jack.carter@globaldynamics.com",
        "name": "Jack Carter",
        "package_id":"04689d9c-a3c8-4b96-9662-53d972f14122",
    }'
## Listen for Webhooks

Example Retrieve Webhook Types Response:

[
    {
        "id": "2c188600-e7ff-4039-bcb2-03a6dab99c13",
        "system_name": "candidate.created",
        "description": "A new candidate has been created."
    },
    {
        "id": "48a9b600-e7ff-4039-bcb2-04cddab97ba8",
        "system_name": "report.completed",
        "description": "A new report has been completed."
    }
]

Yarstik uses webhooks to push events to your webhook URLs when various events occur related to your resources. The webhooks that are supported may be retrieve by making a GET request. After registering a webhook for a specific webhook type, the URL you register will receive POST requests when events occur.

See Webhooks for more information.

Example Retrieve Webhook Types Request:

curl -X GET https://api.yardstik.com/webhook_types \
    -H 'Authorization: Account [YOUR_API_KEY]' \
    -H 'Accept: application/json'

As you can see from the response each webhook type will have an associated id, system_name, and description. You may use the id or system_name when referencing the webhook type when creating new webhooks.

Retrieve the Report

Webhooks

Listening for candidate.created Webhook

Example Create candidate.created Webhook Response:

{
    "id": "a87b1e1a-e9aa-4929-9f30-ad1f9b481a8c",
    "url": "https://www.yourcompany.com/webhooks/candidate_created",
    "webhook_type": "candidate.created"
}

Example candidate.created Webhook POST body:

{
  "id": "dcd9a3db-d885-4695-8a92-5556126000c5",
  "event": "created",
  "resource_id": "67cae505-0bac-4eaf-a255-95421d04e303",
  "account_id": "e829bc40-89eb-4054-94e3-7e826373f8ec",
  "account_name": "Venture Industries",
  "resource_type": "candidate",
  "resource_url": "https://api.yardstik.com/candidates/67cae505-0bac-4eaf-a255-95421d04e303"
}

For example you may register a webhook for candidate.created by registering a webhook for your account. Webhooks may be created at the account level.

Example Create candidate.created Webhook Request:

curl -X POST https://api.yardstik.com/accounts/[YOUR_ACCOUNT_ID]/webhooks \
    -H 'Authorization: Account [YOUR_API_KEY]' \
    -H 'Accept: application/json'
    -H 'Content-Type: application/json' \
    --data-raw '{
        "webhook_type_id": "2c188600-e7ff-4039-bcb2-03a6dab99c13",
        "url": "https://www.yourcompany.com/webhooks/candidate_created"
    }'

Listening for report.created Webhook

Example Create report.created Webhook Response:

{
    "id": "89ade71a-e9aa-4929-9f30-ad1f93245abf",
    "url": "https://www.yourcompany.com/webhooks/report_completed",
    "webhook_type": "report.created"
}

Example report.created Webhook POST body:

{
  "id": "e7331072-7865-4dca-9cd2-1643656a84c7",
  "event": "created",
  "resource_id": "e7e0b119-7714-44a2-900e-9b98a4e5b1c6",
  "account_id": "e829bc40-89eb-4054-94e3-7e826373f8ec",
  "account_name": "Venture Industries",
  "resource_type": "report",
  "resource_url": "https://api.yardstik.com/reports/e7e0b119-7714-44a2-900e-9b98a4e5b1c6"
}

You will also want to listen for report.created events so that you are notified when a background report is completed. To do so register a webhook for report.created event.

Example Create report.report Webhook Request:

curl -X POST https://api.yardstik.com/accounts/[YOUR_ACCOUNT_ID]/webhooks \
    -H 'Authorization: Account [YOUR_API_KEY]' \
    -H 'Accept: application/json'
    -H 'Content-Type: application/json' \
    --data-raw '{
        "webhook_type_id": "48a9b600-e7ff-4039-bcb2-04cddab97ba8",
        "url": "https://www.yourcompany.com/webhooks/report_created"
    }'

All Different Types of Webhooks

Webhook Type Description
candidate.created A candidate has been created.
candidate.updated A candidate has been updated.
candidate.deleted A candidate has been deleted.
transaction.created A payment transaction has been created.
transaction.updated A payment transaction has been updated.
transaction.deleted A payment transaction has been deleted.
invitation.created When a invitation is created
invitation.updated When an invitation is updated
invitation.deleted When an invitation is deleted
report.created When a report is created
report.updated When a report is updated
report.deleted When a report is deleted
account.updated When a Account is updated

Example Report Response

{
    "id": "74deed63-8bae-431f-ab56-af2139e261e4",
    "reference_id": null,
    "candidate_id": "018e6289-78e9-45b8-9c8e-9d78f8b4fba4",
    "account_id": "cc0df11d-a502-47ec-8aa1-ba0738030ca7",
    "status": "completed",
    "decision": "clear",
    "account_name": "General Dynamics",
    "report_url": "[URL to Report PDF]"
    "adverse_action_id": null,
    "report_screenings": [
        {
            "screening": "NationalCriminal"
        },
        ...
    ],
    ...
}

Once an candidate has submitted their information for an invitation and the report has been completed, you may view the report results by retrieving the report.

Types of status:

Status Definition
pre_adverse There is an action that may disqualify the Candidate, and the account needs to determine what do with the Candidate
final_adverse The Candidate responded to the pre-adverse action. The Account admin needs to decline them or move them to proceed (clear)to approve the Candidate.
consider The Report has come back with some violations that may disqualify the Candidate, needs to be reviewed.
unknown Error condition. Unable to determine the status of the Report (contact support).
created The Report was successfully created by request. Processing has not begun.
exception There is an issue with the Report (i.e., SSN is incorrect).
canceled The Report was Cancelled through user action or API request.
processing Our Verification Specialists are researching the Report.
pending The Report is finished but needs final verification by a Yardstik Operations team member.
queued The Report is in the queue to be investigated by a Verification Specialist.
archived The Report is stored but is not active.
clear The Screenings in the Report are complete and clear. The research process did not produce any disqualifying information about the Candidate.
proceed The Report has come back with some data that may disqualify the Candidate, but the Account User decided those data was not sufficient to disqualify the candidate and the Account Owner decided to proceed with it.

See Reports for more information.

Example Report Request

curl -X GET https://api.yardstik.com/reports/74deed63-8bae-431f-ab56-af2139e261e4 \
    -H 'Authorization: Account [YOUR_API_KEY]' \
    -H 'Accept: application/json'

Sample Redirect Flow

The general route that can be used to create an candidate is to collect the candidates information then send the information gathered to our /candidate route via a POST method. This will be processed by our systems and return a candidate JSON, you would save the candidate ID in your application. This can and will be used for other flows that you would utilize.

Once you are ready to screen the candidate you will use the Candidate ID to generate the reports that you want to run against the candidate. Send the candidate ID along with the account package ID and your Account ID to the /reports end-point this will generate the Apply link

The apply link can be handed off to the candidate you wish to screen and they can go and fill out the information and we will handle the rest.

alt text

Adverse Action Process

When a report comes back with the status of consider, this indicates that there were some violations that may disqualify the candidate from being considered from the position.

From here the candidate is reviewed by either a Client user or an API user to make the final determination on whether the candidate is disqualified. If the candidate is set to pre-advised then as required by the FCRA, a pre-adverse action email will be sent on your behalf to the candidate based on the timeline selected (days). The number of days provides time for the candidate to respond to you with any further information to use in the decision process. If there is no response, the final adverse action will be sent automatically following the number of days selected.

When creating an adverse action you must consider that not all adverse actions act the same. the vast majority will work the way presented above and below. But for something like tenents for an apartment complex, there is no need to have this system. so they will go directly into final adverse. When the tenet is placed directly into final adverse a reason will need to be choosen. this will be presented to the denied tenent.

Note that only reports set to consider can be placed in pre-adverse

Adverse Action Flow

Example Adverse action Error Response

{
   {
      "title": "Report Not Foud",
      "detail": "The report was not found",
      "meta": {
        "report_id": "INVALID_REPORT_ID"
       },
    "src": {},
    "status": 404
  }
}

Errors

The Yardstik API may return a number of standard HTTP errors due to invalid requests. Some common errors are described below to help you with building with Yardstik.

Bad Request

The server cannot process the request. This error is most likely due to malformed request syntax.

  • code: 400
  • status: Bad Request

Unauthorized

Similar to a 403 Forbidden, but specifically when authentication is provided and has failed or not been provided. This error is most likely due to not including your API key in the request header.

  • code: 401
  • status: Unauthorized

Unauthorized

Response Schema: application/json
errors
Array of strings
Content type
application/json
{
  • "errors": [
    ]
}

Forbidden

The request was valid, but you are unable to execute the request. This error is most likely due to the API key that was used not having the necessary permissions or you are attempting a prohibited action such as creating a duplicate record where one already exists.

  • code: 403
  • status: Forbidden

Not Found

The requested resource could not be found but may be available in the future. This error is most likely due to request a resource by id that does not exist. You will want to double check that your are referencing the correct id and that it exists on your account.

  • code: 404
  • status: Not Found

Unprocessable Entity

The request was well-formed, but was unable to be processed due to semantic errors. This error is most likely due to including invalid data in POST, PATCH, and PUT requests. Double check the request documentation to make sure you are supplying the required attributes and that they attribute types are correct.

  • code: 422
  • status: Unprocessable Entity

Internal Server Error

An internal server error occurred due to an unexpected condition. This error is most likely due to an issue with our servers. If you encounter such an error, please reach out to support@yardstik.com and we will work with you to resolve the issue.

  • code: 500
  • status: Internal Server Error

Embedable Views

Yardstik has published a public npm library for utilizing Yardstik embedable views:

https://www.npmjs.com/package/@yardstik/embedable-sdk

Installation

The Yardstik embedable-sdk library is available as an npm package.

  • with npm npm i @yardstik/embedable-sdk

  • with yarn yarn add @yardstik/embedable-sdk

Getting Started

Here is a quick example to get you started, it's all you need:

import { Yardstik } from '@yardstik/embedable-sdk';

Available Views

Each available page view is a separate method on the exported Yardstik library object. The currently supported views are as follows:

  1. CandidateReportIframe: Allows the user to view and interact with a candidate report.
  2. AccountDisclosuresIframe: Allows the user to view and agree to account level agreements and terms.

Creating an Instance of an Available View

To create an instance of the desired view, which will be attached to a specified container on your page, call the applicable method and pass in the configuration object. For example:

    const yardstikReport = new Yardstik.CandidateReportIframe(
      {
        token: myToken,
        reportId: myReportId, 
        container: containerRef.current, 
        domain: myDomain 
      }
    );

CandidateReportIframe

The config object for the CandidateReportIframe takes the following parameters:

token: string - JWT for authorization

reportId: string - The ID of the report that you would like to review

container: HTMLElement - Container to which the iframe will be attached.

domain: string - Yardstik domain that you would like to call.

width?: string - Optional width of the iframe

height?: string - Optional height of the iframe

fullScreen?: boolean - Optional, if true, iframe will fill the entire page

AccountDisclosureIframe

The config object for the CandidateReportIframe takes the following parameters:

token: string - JWT for authorization

accountId: string - The ID of the account that you would like to review

container: HTMLElement - Container to which the iframe will be attached.

domain: string - Yardstik domain that you would like to call.

width?: string - Optional width of the iframe

height?: string - Optional height of the iframe

fullScreen?: boolean - Optional, if true, iframe will fill the entire page

Obtaining JWT

To obtain a JWT to include in the config object, in your backend, post a request to the relevant Yardstik API route, using your API token for authorization. See the resources section below for more information.

Shared Methods For Use By Parent Page

Each view has a shared method that can be called by the parent page and utilized for customization and performance.

destroy: When called, the destroy method will remove the iframe from its parent container. This method can be used by the parent page for clean-up.

yardstikReport.destroy()

Message Events

Each iframe view is set up to post certain message events to the parent page in which it is contained in order to allow the parent to take action.

loaded: Each iframe instance will post a 'loaded' message event when the iframe content has fully loaded. The parent page could listen for this event to trigger an action, such as rendering the iframe visible or turning off a loading animation. For example:

    yardstikReport.on('loaded', () => { 
      console.log("The iframe is ready."); 
      setIframeReady(true)
    ;})

expiration: Each iframe instance will post an 'expiration' message event when the authorization token has expired. The parent can listen for this event to trigger an action, such as requesting a new JWT from your backend to refresh the session or instructing the user to refresh the page, so that a new token is generated. For example:

    yardstikReport.on('expiration', () => { 
    console.log("The JWT has expired."); 
    setTokenExpired(true);
  })

Accounts

List all Accounts

List all accounts that you have access to.

Authorizations:

Responses

Request samples

curl -i -X GET \
  https://api.yardstik.com/accounts \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
[
  • {
    }
]

List Sub Accounts

List all sub accounts that your account is parent of.

Authorizations:

Responses

Request samples

curl -i -X GET \
  https://api.yardstik.com/sub_accounts \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
[
  • {
    }
]

Get an SubAccount

SubAccount details

Authorizations:
path Parameters
sub_account_id
required
string

Responses

Request samples

curl -i -X GET \
  https://api.yardstik.com/sub_accounts/:sub_account_id \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "id": "string",
  • "account_name": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "owner_email": "string",
  • "email_address": "string",
  • "url": "string",
  • "tech_email_address": "string",
  • "support_email_address": "string",
  • "support_phone": "string",
  • "actions_email_address": "string",
  • "compliance_email_address": "string",
  • "email_configurations": { },
  • "address": { },
  • "logo": "string",
  • "permissible_purposes": { }
}

Get an Account

Account ID details

Authorizations:
path Parameters
accountId
required
string

Responses

Request samples

curl -i -X GET \
  https://api.yardstik.com/accounts/:accountId \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "account_name": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "owner_email": "user@example.com",
  • "email_address": "user@example.com",
  • "url": "string",
  • "tech_email_address": "user@example.com",
  • "support_email_address": "user@example.com",
  • "support_phone": "string",
  • "compliance_email_address": "user@example.com",
  • "actions_email_address": "user@example.com",
  • "address": {
    },
  • "logo": "string",
  • "meta": { },
  • "permissible_purposes": [
    ]
}

Create a Sub-Account

Create a sub-account from a parent account. Permissions are set by the onboarding coach, if permissions need to be added or removed, please contact your onboarding coach or support personal.

Authorizations:
path Parameters
accountId
required
string
Request Body schema: form-data
account_name
string

name of the sub account

actions_email_address
string

actions email address of the sub account

compliance_email_address
string

compliance email address of the sub account

email_address
string

email of the primary contact

first_name
string

first name of the sub account primary contact

last_name
string

first name of the sub account primary contact

logo
string

optional logo that will be shown to the candidates

permissible_purpose_id
string <UUID>

the id for the permissable purpose that you want to give the sub account

support_email_address
string

support email address of the sub account

support_phone
string

support phone number of the sub account

tech_email_address
string

tech email address of the sub account

url
string

Relevant url for sub account

Responses

Request samples

curl -i -X POST \
  https://api.yardstik.com/accounts/:accountId/accounts \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: form-data'

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "account_name": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "owner_email": "user@example.com",
  • "email_address": "user@example.com",
  • "url": "string",
  • "tech_email_address": "user@example.com",
  • "support_email_address": "user@example.com",
  • "support_phone": "string",
  • "compliance_email_address": "user@example.com",
  • "actions_email_address": "user@example.com",
  • "address": {
    },
  • "logo": "string",
  • "meta": { },
  • "permissible_purposes": [
    ]
}

Create an API Key

Generate a new API key.

Authorizations:
path Parameters
accountId
required
any
Request Body schema: application/json
name
string

name of the api package

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "70adc786-904b-4954-9adb-0ede9f949c62",
  • "api_token": "c6b6e55f-5b3a-479a-9ea8-d95d13856c7d",
  • "name": "Checking x",
  • "header": "Authorization: User c6b6e55f-5b3a-479a-9ea8-d95d13856c7d"
}

Get all Settings

Accounts settings for a given account id.

Authorizations:
path Parameters
accountId
required
string

Responses

Request samples

curl -i -X GET \
  https://api.yardstik.com/accounts/:accountId/settings \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "styles": {
    },
  • "invitations": {
    },
  • "report_notifications": {
    }
}

Get an account Setting

Get a single account setting for the given account id and setting key.

Authorizations:
path Parameters
accountId
required
string
settingKey
required
string

Responses

Request samples

curl -i -X GET \
  https://api.yardstik.com/accounts/:accountId/settings/:settingKey \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "primary_color": "FFCD01",
  • "secondary_color": "FFCD01"
}

Update an account Setting

Update an account setting for the given account id and setting key.

Authorizations:
path Parameters
accountId
required
string
settingKey
required
string
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "primary_color": "FFCD01"
}

Response samples

Content type
application/json
{
  • "theme_base": 2,
  • "logo": null
}

Candidates

Candidates represent people who have agreed to a background check. Use the Candidate object to collect all Personally Identifiable Information (PII) for a candidate.

List Candidates

Retrieve a paginated list of candidates. See Pagination.

Authorizations:
query Parameters
page
integer

The page number to retrieve.

per_page
integer

The maximum number of results per page.

Responses

Request samples

curl -i -X GET \
  'https://api.yardstik.com/candidates?page=0&per_page=0' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "object": "list",
  • "data": [
    ]
}

Create a Candidate

The required attributes for a candidate vary depending on its intended use.

If this resource is to be used in conjunction with the Invitations API (in which the invitation apply form collects the Applicant's personal information), the only strictly required Candidate attributes are:

  • first_name,
  • last_name,
  • email

If this resource is to be used to generate any other report type, other personal information is also required.

Attributes required to generate a Report include:

  • first_name
  • middle_name
  • last_name
  • date_of_birth

Attributes required to generate a Report with a criminal check screening:

  • ssn
  • zip_code

Attributes required to generate a report with a Motor Vehicle Record (MVR) screening:

  • driver_license_number
  • driver_license_state

Attributes recommended to generate a report with an Identity Document Verification screening:

  • phone (mobile phone number)
Authorizations:
Request Body schema: application/json
Array of objects

The addresses of the candidate.

date_of_birth
string <date-time> Nullable

The date of birth of the candidate.

driver_license_number
string Nullable

The drivers license number of the candidate.

driver_license_state
string Nullable

The state the candidates drivers license is issued by as ISO 3166-2 two letter code.

email
required
string

The email address of the candidate.

first_name
required
string

The first name of the candidate.

gender
string Nullable

The gender of the candidate.

last_name
required
string

The last name of the candidate.

meta
object

relevent links for the candidate

middle_name
string Nullable

The middle name of the candidate.

phone
string Nullable

The primary phone number of the candidate.

previous_driver_license_number
string Nullable

The previous drivers license number of the candidate.

previous_driver_license_state
string Nullable

The state the candidates previous drivers license is issued by as ISO 3166-2 two letter code.

ssn
string

The social security number of the candidate.

Responses

Request samples

Content type
application/json
{
  • "first_name": "string",
  • "middle_name": "string",
  • "last_name": "string",
  • "email": "jack.carter@globaldynamics.com",
  • "phone": "string",
  • "ssn": "string",
  • "date_of_birth": "2019-08-24T14:15:22Z",
  • "gender": "string",
  • "driver_license_number": "string",
  • "driver_license_state": "string",
  • "previous_driver_license_number": "string",
  • "previous_driver_license_state": "string",
  • "meta": { },
  • "addresses": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "object": "candidate",
  • "first_name": "string",
  • "middle_name": "string",
  • "last_name": "string",
  • "email": "jack.carter@globaldynamics.com",
  • "phone": "string",
  • "ssn_masked": "string",
  • "date_of_birth": "2019-08-24T14:15:22Z",
  • "gender": "string",
  • "driver_license_number": "string",
  • "driver_license_state": "string",
  • "previous_driver_license_number": "string",
  • "previous_driver_license_state": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "meta": { },
  • "addresses": {
    }
}

Get a Candidate

Retrieve a candidate with the given id.

Authorizations:
path Parameters
candidate_id
required
string <uuid> (ResourceId) <= 50 characters

The candidate id.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Responses

Request samples

curl -i -X GET \
  https://api.yardstik.com/candidates/:candidate_id \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "object": "candidate",
  • "first_name": "string",
  • "middle_name": "string",
  • "last_name": "string",
  • "email": "jack.carter@globaldynamics.com",
  • "phone": "string",
  • "ssn_masked": "string",
  • "date_of_birth": "2019-08-24T14:15:22Z",
  • "gender": "string",
  • "driver_license_number": "string",
  • "driver_license_state": "string",
  • "previous_driver_license_number": "string",
  • "previous_driver_license_state": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "meta": { },
  • "addresses": {
    }
}

Update a Candidate

Update a candidate with the given id.

Authorizations:
path Parameters
candidate_id
required
string <uuid> (ResourceId) <= 50 characters

The candidate id.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Request Body schema: application/json
Array of objects

The addresses of the candidate.

date_of_birth
string <date-time> Nullable

The date of birth of the candidate.

driver_license_number
string Nullable

The drivers license number of the candidate.

driver_license_state
string Nullable

The state the candidates drivers license is issued by as ISO 3166-2 two letter code.

email
required
string

The email address of the candidate.

first_name
required
string

The first name of the candidate.

gender
string Nullable

The gender of the candidate.

last_name
required
string

The last name of the candidate.

meta
object

relevent links for the candidate

middle_name
string Nullable

The middle name of the candidate.

phone
string Nullable

The primary phone number of the candidate.

previous_driver_license_number
string Nullable

The previous drivers license number of the candidate.

previous_driver_license_state
string Nullable

The state the candidates previous drivers license is issued by as ISO 3166-2 two letter code.

ssn
string

The social security number of the candidate.

Responses

Request samples

Content type
application/json
{
  • "first_name": "string",
  • "middle_name": "string",
  • "last_name": "string",
  • "email": "jack.carter@globaldynamics.com",
  • "phone": "string",
  • "ssn": "string",
  • "date_of_birth": "2019-08-24T14:15:22Z",
  • "gender": "string",
  • "driver_license_number": "string",
  • "driver_license_state": "string",
  • "previous_driver_license_number": "string",
  • "previous_driver_license_state": "string",
  • "meta": { },
  • "addresses": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "object": "candidate",
  • "first_name": "string",
  • "middle_name": "string",
  • "last_name": "string",
  • "email": "jack.carter@globaldynamics.com",
  • "phone": "string",
  • "ssn_masked": "string",
  • "date_of_birth": "2019-08-24T14:15:22Z",
  • "gender": "string",
  • "driver_license_number": "string",
  • "driver_license_state": "string",
  • "previous_driver_license_number": "string",
  • "previous_driver_license_state": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "meta": { },
  • "addresses": {
    }
}

Delete a Candidate

Permanently delete a candidate with the given id.

Authorizations:
path Parameters
candidate_id
required
string <uuid> (ResourceId) <= 50 characters

The candidate id.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Responses

Request samples

curl -i -X DELETE \
  https://api.yardstik.com/candidates/:candidate_id \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "object": "candidate",
  • "first_name": "string",
  • "middle_name": "string",
  • "last_name": "string",
  • "email": "jack.carter@globaldynamics.com",
  • "phone": "string",
  • "ssn_masked": "string",
  • "date_of_birth": "2019-08-24T14:15:22Z",
  • "gender": "string",
  • "driver_license_number": "string",
  • "driver_license_state": "string",
  • "previous_driver_license_number": "string",
  • "previous_driver_license_state": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "meta": { },
  • "addresses": {
    }
}

Delete a Candidate's address

Permanently delete a candidate's address by the given address id

Authorizations:
path Parameters
address_id
required
string <uuid> (ResourceId) <= 50 characters

The address id.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
candidate_id
required
string <uuid> (ResourceId) <= 50 characters

The candidate id.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Responses

Request samples

curl -i -X DELETE \
  https://api.yardstik.com/candidates/:candidate_id/addresses/:address_id \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "object": "address",
  • "line1": "string",
  • "line2": "string",
  • "city": "string",
  • "state": "string",
  • "zip_code": "string",
  • "country": "string"
}

Proceed a Report

Proceed a Candidate for a Report. For more information about Proceed a Candidate

Authorizations:
path Parameters
candidateId
required
string
Request Body schema: application/json
report_id
required
string <UUID>

the unique identifier for the report

Responses

Request samples

Content type
application/json
{
  • "report_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "object": "candidate",
  • "first_name": "string",
  • "middle_name": "string",
  • "last_name": "string",
  • "email": "jack.carter@globaldynamics.com",
  • "phone": "string",
  • "ssn_masked": "string",
  • "date_of_birth": "2019-08-24T14:15:22Z",
  • "gender": "string",
  • "driver_license_number": "string",
  • "driver_license_state": "string",
  • "previous_driver_license_number": "string",
  • "previous_driver_license_state": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "meta": { },
  • "addresses": {
    }
}

Invitations

Invitations are used to invite candidates to complete a background check with Yardstik. When an invitation is created, the candidate will receive an email asking them to complete the screening package the invitation was created with.

Note: By default, the invitation will expire 7 days after creation. The default invitation expiration settings may changed in your dashboard in General Settings. Changing invitation expiration settings in your dashboard are only automatically applied to new invitations and will not impact existing invitations.

List Invitations

Retrieve a paginated list of invitations. See Pagination.

Authorizations:
query Parameters
page
integer

The page number to retrieve.

per_page
integer

The maximum number of results per page.

Responses

Request samples

curl -i -X GET \
  'https://api.yardstik.com/invitations?page=0&per_page=0' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "object": "list",
  • "meta": {
    },
  • "data": [
    ]
}

Create an Invitation

Creates a new invitation and emails the candidate asking them to complete a background check.

Authorizations:
Request Body schema: application/json
account_package_id
string <uuid>

pacakage ID you want to use for this candidate

candidate_id
string <uuid>

ID of the candidate you created

invitation_code
string Nullable

that is the code we show after the PII is completed

Responses

Request samples

Content type
application/json
{
  • "account_package_id": "263fabf2-df86-40fd-8915-3ea60c091d57",
  • "candidate_id": "2f28f791-f0fd-4155-a356-c24e996beeda",
  • "invitation_code": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "string",
  • "invitation_code": "string",
  • "external_id": "string",
  • "platform_service_id": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "canceled_at": "2019-08-24T14:15:22Z",
  • "confirmation_code": "string",
  • "account_id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "account_name": "string",
  • "logo": "string",
  • "report_urls": [ ],
  • "styles": {
    },
  • "candidate": {
    },
  • "account": {
    },
  • "meta": {
    },
  • "report": {
    }
}

Get an Invitation

Retrieve an invitation with the given id.

Authorizations:
path Parameters
invitation_id
required
string <uuid> (ResourceId) <= 50 characters

The invitation id.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Responses

Request samples

curl -i -X GET \
  https://api.yardstik.com/invitations/:invitation_id \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "string",
  • "invitation_code": "string",
  • "external_id": "string",
  • "platform_service_id": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "canceled_at": "2019-08-24T14:15:22Z",
  • "confirmation_code": "string",
  • "account_id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "account_name": "string",
  • "logo": "string",
  • "report_urls": [ ],
  • "styles": {
    },
  • "candidate": {
    },
  • "account": {
    },
  • "meta": {
    },
  • "report": {
    }
}

Delete an Invitation

Permanently delete an invitation with the given id.

Authorizations:
path Parameters
invitation_id
required
string <uuid> (ResourceId) <= 50 characters

The invitation id.

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Responses

Request samples

curl -i -X DELETE \
  https://api.yardstik.com/invitations/:invitation_id \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Cancel an Invitation

Cancel an invitation with the given id..

Authorizations:
path Parameters
invitation_id
required
string <uuid> <= 50 characters

The invitation id

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

Responses

Request samples

curl -i -X PATCH \
  https://api.yardstik.com/invitations/:invitation_id/cancel \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "string",
  • "invitation_code": "string",
  • "external_id": "string",
  • "platform_service_id": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "canceled_at": "2019-08-24T14:15:22Z",
  • "confirmation_code": "string",
  • "account_id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "account_name": "string",
  • "logo": "string",
  • "report_urls": [ ],
  • "styles": {
    },
  • "candidate": {
    },
  • "account": {
    },
  • "meta": {
    },
  • "report": {
    }
}

Packages

List Packages for an Account

List available packages for the given account id.

Authorizations:
path Parameters
accountId
required
string

Responses

Request samples

curl -i -X GET \
  https://api.yardstik.com/accounts/:accountId/packages \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Reports

Reports are the initialization record of the screening service. It will have the details in the packages. See Status Summaries Reports

List all Reports

List all reports.

Authorizations:

Responses

Request samples

curl -i -X GET \
  https://api.yardstik.com/reports \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
[
  • {
    }
]

Create a Report

Create a new report. The report will be generated based on an candidate id submission. And the screening packages that will be set are based on the selected in the Account.

Authorizations:
Request Body schema: application/json
account_package_id
required
string <UUID>

The Account package id, for the package you want to create a report for

candidate_id
required
string <UUID>

the unique identifier for the candidate

reference_id
string

A reference_id that can be used for your applicaiton

Responses

Request samples

Content type
application/json
{
  • "candidate_id": "string",
  • "account_package_id": "string",
  • "reference_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "reference_id": "string",
  • "candidate_id": "string",
  • "status": "string",
  • "response_status": "string",
  • "adjudication": "string",
  • "submitted_at": "string",
  • "completed_at": "string",
  • "created_at": "string",
  • "decision": "string",
  • "usage_amount": 0,
  • "process_sequentially": true,
  • "permissible_purpose": "string",
  • "created_by": "string",
  • "candidate": {
    },
  • "account_id": "string",
  • "account_name": "string",
  • "report_url": "string",
  • "adverse_action_id": "string",
  • "report_screenings": [ ],
  • "elapsed_timing": "string",
  • "package_name": "string",
  • "comments": [ ],
  • "meta": { },
  • "adverse_action_settings": "string"
}

Get a Report

Get a report with the given id.

Authorizations:
path Parameters
reportId
required
string

Responses

Request samples

curl -i -X GET \
  https://api.yardstik.com/reports/:reportId \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "id": "string",
  • "reference_id": "string",
  • "candidate_id": "string",
  • "status": "string",
  • "response_status": "string",
  • "adjudication": "string",
  • "submitted_at": "string",
  • "completed_at": "string",
  • "created_at": "string",
  • "decision": "string",
  • "usage_amount": 0,
  • "process_sequentially": true,
  • "permissible_purpose": "string",
  • "created_by": "string",
  • "candidate": {
    },
  • "account_id": "string",
  • "account_name": "string",
  • "report_url": "string",
  • "adverse_action_id": "string",
  • "report_screenings": [ ],
  • "elapsed_timing": "string",
  • "package_name": "string",
  • "comments": [ ],
  • "meta": { },
  • "adverse_action_settings": "string"
}

Create a Adverse Action

Create a Adverse Action on a report with the given id. For more information about Adverse Action

Authorizations:
path Parameters
reportId
required
string

Responses

Request samples

curl -i -X POST \
  https://api.yardstik.com/reports/:reportId/adverse_actions \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "string",
  • "title": "string",
  • "text": "string",
  • "expires_at": "string",
  • "created_at": "string",
  • "updated_at": "string",
  • "violations": [
    ],
  • "comments": [
    ],
  • "applicant_first_name": "string",
  • "account_name": "string",
  • "logo": "string",
  • "styles": { }
}

Cancel a Adverse Action

Cancel a Adverse Action on a report with the given id. For more information about Adverse Action

Authorizations:
path Parameters
adverse_action_id
required
string

Responses

Request samples

curl -i -X PATCH \
  https://api.yardstik.com/adverse_actions/:adverse_action_id/cancel \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "string",
  • "title": "string",
  • "text": "string",
  • "expires_at": "string",
  • "created_at": "string",
  • "updated_at": "string",
  • "violations": [
    ],
  • "comments": [
    ],
  • "applicant_first_name": "string",
  • "account_name": "string",
  • "logo": "string",
  • "styles": { }
}

Webhooks

Webhooks are used to notify you of events which have occurred related to various resources.

List all Webhooks

Retrieve a list of webhooks for the given account id.

Authorizations:

Responses

Request samples

curl -i -X GET \
  https://api.yardstik.com/webhooks \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
[
  • {
    }
]

Create a Webhook

Create a webhook

Authorizations:
Request Body schema: application/json
url
string
webhook_type_id
string

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "e8b57b13-0038-4c69-99ee-1dae304afd80",
  • "webhook_type": "candidate.created",
}

Show a Webhook

Show a specific webhook given a webhook_id

Authorizations:
path Parameters
webhook_id
required
string

Responses

Request samples

curl -i -X GET \
  https://api.yardstik.com/webhooks/:webhook_id \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
[
  • {
    }
]

Update a webhook

Update a webhook given an ID

Authorizations:
path Parameters
webhook_id
required
string
Request Body schema: application/json
enabled
boolean

turn on and off the webhook

url
string

update the webhook url

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "e8b57b13-0038-4c69-99ee-1dae304afd80",
  • "webhook_type": "candidate.created",
}

delete a webhook

delete a webhook given an Id

Authorizations:
path Parameters
webhook_id
required
string

Responses

Request samples

curl -i -X DELETE \
  https://api.yardstik.com/webhooks/:webhook_id \
  -H 'Authorization: YOUR_API_KEY_HERE'

List all Webhook Types

List all webhook types enabled for your account.

Authorizations:

Responses

Request samples

curl -i -X GET \
  https://api.yardstik.com/webhook_types \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
[
  • {
    }
]

JWT

A JWT is required to access the Yardstik embedable views.

Get a JWT

Authorizations:
Request Body schema: application/json
user_email
string

Responses

Request samples

Content type
application/json
{
  • "user_email": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]