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:

{
    "type": "candidate.created",
    "data": {
        "id": "018e6289-78e9-45b8-9c8e-9d78f8b4fba4",
        "account_id": "cc0df11d-a502-47ec-8aa1-ba0738030ca7",
        "invitation_id": "18e00b78-e620-4ecf-a01a-eb810f1b6751",
        "ssn": "111-22-3333",
        "first_name": "Jack",
        "middle_name": "Roy",
        "last_name": "Carter",
        "address1": "14918 Goodrich Creek Ln",
        "address2": "",
        "city": "Eureka",
        "state": "OR",
        "zip_code": "97833",
        "email_address": "jack.carter@globaldynamics.com",
        "phone": "541-555-6802",
        "date_of_birth": "1969-05-13",
        "driver_license_number": "",
        "driver_license_state": "",
        "previous_driver_license_number": "",
        "previous_driver_license_state": "",
        "copy_requested": true,
        ....
    }
}

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:

{
    "type": "report.created",
    "data": {
        "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"
            },
            ...
        ],
        ...
    }
}

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.

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.

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

Pagination

All top-level API resources have support for bulk fetches via list API methods. Yardstik uses page-based pagination via the page and per_page parameters. For instance, you can list invitations, candidates, and reports. The list API methods share a common structure, taking at least these parameters: page and per_page.

Example Paginated Request

curl -X GET https://api.yardstik.com/invitations?page=2&per_page=25 \
    -H 'Authorization: Account [YOUR_API_KEY]' \
    -H 'Accept: application/json'

Standard list API Request Parameters:

Parameter Description
page The page number to retrieve.
type: integer
default: 1
per_page The number of records per page.
type: integer
default: 50
minimum: 1
maximum: 100

The page parameter determines which page of results will be returned in the response and defaults to 1 if not set or set to an invalid type. If the value the value of page exceeds the total_number of pages available the response will include an empty data array.

The per_page parameter determines the maximum number of results include in each response. If there are fewer resources available than the per_page value, the response will include all available resources. The maximum value allowed is 100 with a default value of 50. If the per_page value is an invalid type, the default value of 50 is used.

Example Paginated Response

{
    "object": "list",
    "meta": {
        "page": 2,
        "per_page": 25,
        "total_count": 137,
        "total_pages": 6
    },
    "data": [
        {
            "object": "invitation",
            "id": "18e00b78-e620-4ecf-a01a-eb810f1b6751",
            ... additional response attributes based on resource schema
        },
        {
            "object": "invitation",
            "id": "d0102680-e2de-4af8-9034-f88ccb4ad267",
            ... additional response attributes based on resource schema
        },
        ... additional resources in the page
    ]
}

Standard list API Response Structure

The standard response for all top-level list API requests will include at least these attributes:

Attribute Description
object The type of object returned.
type: string
default: "list"
meta Metadata associated with the response.
Attributes:
Attribute Description
page The page number of the response.
type: integer
per_page The number of results per page.
type: integer
total_count The total number of resources available.
type: integer
total_pages The total number of pages available.
type: integer
data An array of the requested resources.
type: array
Notes: May be an empty array [] if no resources are available.

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

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
[
  • {
    }
]

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",
  • "configurations": {
    },
  • "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",
  • "configurations": {
    },
  • "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
{
  • "theme_base": 1,
  • "logo": null
}

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
{
  • "theme_base": 2
}

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
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

The candidate id.

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
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

The candidate id.

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
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

The candidate id.

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
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

The address id.

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

The candidate id.

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

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
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

The invitation id.

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
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

The invitation id.

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
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

The invitation id

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
[
  • {
    }
]