Yardstik Api (1.0)

Introduction

Yardstik is a modern, RESTful API-driven background screening service offering many screens and services to run against potential employees, tenants, or other use cases. Yardstik utilizes resource-oriented URLs, we authenticate these routes via a single API key, and leverage JSON in all responses, making integration seamless into your application.

Yardstik was founded in 2020, and over this time many companies from a wide variety of industries have utilized our human security platform.

Other resources:

For more information, please checkout our website or if you need more of a personal touch feel free to reach out to our support team and they will get in contact with our engineering team!

Understanding our Job

To help with the integration of your application to ours it would help if you understand the process that we go through. When you have a candidate that you want to perform a background check on, these are the steps that one would follow to trigger the background check.

  1. An applicant/candidate is selected to perform a background check on.
  2. You create an invitation for the candidate.
  3. The candidate receives an invite email, leading them to the candidate intake forum.
  4. The candidate fills out the required information needed to perform the background checks requested.
  5. Once the candidate signs the legal forum and all information is provided, it is sent to our background verification team who will perform a background check on the candidate and rely a status depending on what is returned
  6. From there you can decide what to do with the results

Note: If the candidate has payments, this will be asked for while the candidate is filling in there information. This will occure either before or after depending on what your company prefers.

The screens and information gathered are determined by the account package that is used. This contains information on what is required for each step and will automatically add these collection steps to the same forum leading to a fluid experience for the candidate.

Getting Credentialed

Before you can begin in the amazing world of background check integrations you must first become registered and credentialed to use our product. To do this you must reach out to our account executive team. Reach out to support@yardstik.com to get in contact with someone that will help you out.

To make the process go faster here is some of the information that is required to make an account.

Permissible purpose:

Since we are a company registered in the United States, we are heavily regulated by federal, state, and local levels of government, and primarily by the Fair Credit Reporting Act (FCRA). In this law you must supply the candidate with the reason why the background check is being performed.

Some examples

Permissible Purpose Description
Tenant if this candidate is a tenant for your building and you want to run a background check
Employment if this candidate is a potential candidate for your company

Legal Business Name: The name of the company that you wish to use and what is registered to the state

Owners Email: The owner of the account who will set up other users on the account.

First and Last Name: What do you go by so we can properly be introduced!

With this information we can get your account set up rather quickly even if the business aspect may need some more time.

Dashboard

Although we are an API first company we do have a GUI that you can access to manage your account, this is also where you will go to view reports ( unless you are using the embedded views). In the dashboard you can do many things. You can create new API keys, manage candidate invites manually, view reports of the results, and make decisions on the candidate, along with many other things. You can use this link to access the Dashboard (assuming that you have a user account)

Authentication

Here at Yardstik, we uses API keys to authenticate your API requests.
all API requests require an API key, this will be passed in the header of the request under the Authentication: Account [YOUR API KEY]. Along with this it is recommended that you also include a Accept: application/json if you do not you may have some unexpected errors thrown in your application.

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

How to get your first API key

So you have an account, got credentialed, and are able to log in. Great, now we can get to the fun parts!

To get your first API key is as simple as signing into the Dashboard and going to the developers tab. From here make your way down to API keys, after that create a name for the API key and click 'Create'. After this an API key will appear.

NOTE: WE DO NOT SAVE API KEYS, MAKE SURE YOU COPY THE API KEY BEFORE CLOSING THE WINDOW OR IT WILL NOT BE SAVED.

Keeping Your API Key safe

It is good practice not to give your API keys to anyone who wouldn't need them. If someone gets access to an API key they have complete access to all API calls on your companies behalf. We recommend not hardcoding the API Key anywhere in your application and to not send the API key on any platform that isn't secure.

If you believe that your API key may be compromised, you can decommission it from the Dashboard and remake a new API key. If you need help, dont hesitate to reach out to support and they will see if they can help you or get you in touch with someone that can.

API Key Best Practices

  • Do not embed API keys directly in code.
  • Do not store API keys in files inside your source code.
  • Delete unused API keys.
  • Regenerate your API keys periodically.
  • Always store your API keys encrypted.
  • Restrict access to the API keys to only those who need it.
  • Do not share your API keys, not even with us.

Getting Started

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

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 Authentication above.

Authenticate with Yardstik

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'

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

If you are seeing a response similar to this one then you are authenticated and able to make requests to the API 🎉

Create an Invitation Flow

This is a sample of how to create an invitation using the API. There are 2 steps in this process, first you must create a Candidate. A candidate can be created by using the Create Candidate Route

After you compete this request you should see a response that looks like below.

Example Candidate Response:

{
"id":  "1111111-23c9-4f70-bcd3-332d6dd9aacf",
"object":  "candidate",
"full_name":  "Kirk Boehm",
"first_name":  "Kirk",
"middle_name":  null,
"no_middle_name":  false,
"last_name":  "Boehm",
"email":  "Jameson_Grimes@example.net",
"phone":  "+7514747858",
"ssn_masked":  null,
"additional_data":  {},
"guardian":  {},
"account":  {
    "id":  "15d9fd10-3927-4de6-a504-221971680f0e",
    "account_name":  "Company"
},
...
}
}

Now that you have a candidate created you can invite that candidate to complete their form using the invitation route, you will need the Candidate id from the previous request along with the account package id that includes the screens to be run on the candidate.

Note:

  • The candidate_id attribute is required.
  • The account_package_id attribute is required. See Packages for more information.

Example Invitation Request:

curl --location --request POST 'https://api.yardstik.com/invitations' \
--header 'Authorization: Account [API KEY HERE]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "account_package_id": "ID",
    "candidate_id": "ID",
    "invitation_code": "" optional
}'

Example Invitation Response:

{
    "id": "ID",
    "status": "invite_sent",
    "invitation_code": null,
    "external_id": null,
    "platform_service_id": null,
    "expires_at": "2021-08-25T21:40:56.062Z",
    "canceled_at": null,
    "confirmation_code": "VWJ-14798",
    "account_id": "ID",
    "account_name": "",
    "logo": "URL",
    "report_urls": [],
    "styles": {
        "primary_color": "#007BFF",
        "secondary_color": "#FFCD01"
    },
    "candidate": {
       ...
    },
    "account": {
        "account_name": "example Company",
        "support_email_address": "",
        "support_phone": "+111111111"
    },
    "meta": {
        "entity": "https://app.yardstik-staging.com/invitations/ID",
        "apply": "https://profile.yardstik-staging.com/candidates/ID/apply?report_id=ID&account_package_id=ID"
    },
    "report": {
        "id": "ID",
        "status": "created"
    }
}

Now the Candidate will receive an email asking them to complete the form. in the meta tag of the response there is a key named apply that is the link that they will be sent.

See Invitations for more information.

Listen for Webhooks

Yardstik uses webhooks to push events to your application when various events occur related to your resources. After registering a webhook for a specific webhook type, the URL you register will receive POST requests when the event occurs in your account.

See Webhooks for more information.

Webhooks Types

Webhook Type Description
candidate.created A candidate has been created.
candidate.updated A candidate has been updated.
candidate.deleted A candidate has been deleted.
candidate.consented Candidate has completed their PII, signed their disclosures, and consented to the background check.
candidate.paid Candidate has paid for their background check.
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
sub_account.active The Subaccount was activated by a Yardstik Agent.

Example Retrieve Webhook Types Request:

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

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

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.

Using webhooks

Listening for candidate.created Webhook

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. this will trigger when a new candidate is created.

you can create a new webhook using the Create Webhook Route

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

Now that the webhook was triggered you should receive the body presented above you can use this to get the candidate from the resouce_url key.

Listening for report.created Webhook

Now for a different example, Let's say 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.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": "48a9b600-e7ff-4039-bcb2-04cddab97ba8",
        "url": "https://www.yourcompany.com/webhooks/report_created"
    }'

Again you would create a webhook for report.created.

Example Create report.created Webhook Response:

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

And once a report is created you will be sent this.

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

Listening for sub_account.active Webhook

Now let's say that you are a platform account and want to manage your subaccount but know when one is created you can do that with a sub_account.active webhook. If you are unsure if you are a platform account there is more information here

Example Create sub_account.active 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/sub_account_active"
    }'

Example Create sub_account.active Webhook Response:

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

Example sub_account.active Webhook POST body:

{
  "id": "ca64ad1a-2018-41c4-b369-dd5c3c1581dc",
  "event": "active",
  "resource_id": "21e2830c-b886-4234-a31d-5fa316069b21",
  "account_id": "e829bc40-89eb-4054-943-7e826373f8ec",
  "account_name": "Venture Capital",
  "resource_type": "sub_account",
  "resource_url": "https://api.yardstik-staging.com/accounts/21e2830c-b88e-42e-a5ed-5e316069b21"
}

This is a webhook that can be used to determine when a subaccount that is under your platform account is created so that you can perform whatever operations are needed.

Reports

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

Example Report Request

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

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

Now once a report is completed it will be assigned a status based on what is found. The possible statuses are below.

Report Status

Status Types: There are many different statuses that a candidates report can be placed in. Below is a table that describes what each of the statuses mean.

Status Definition
pre_adverse The account has decided that there is violations that could disqualify the candidate from employment. this starts a timer to allow the candidate to respond.
final_adverse The candidate pre_adverse reposonse time window has expired and they either didnt reply or they didnt give enough evidence to go into proceed
consider The Report has come back with some violations that may disqualify the Candidates. Needs review.
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.
info_requested The information that the candidate originally supplied was not enough to complete the verification, a specialist has reached out to them to gather the rest of the required information.
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.

Sample Redirect Flow

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.

Here is the route documentation in how to Create a Adverse Action for a Report.

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_adverse 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 tenants for an apartment complex, there is no need to have this system. so they will go directly into final adverse. When the tenant is placed directly into final adverse a reason will need to be choosen. This will be presented to the denied tenant.

Note that only reports set to consider can be placed in pre_adverse

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.

Here is the route documentation in how to Create a Adverse Action for a Report.

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_adverse 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 tenants for an apartment complex, there is no need to have this system. so they will go directly into final adverse. When the tenant is placed directly into final adverse a reason will need to be choosen. This will be presented to the denied tenant.

Note that only reports set to consider can be placed in pre_adverse.

Adverse Action Flow

Example Adverse action Error Response

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

Adverse Action Violations

During the creation Adverse Action you may or may not have to provide a list of violations.

Here is the route documentation in how to Create a Adverse Action for a Report.

If a report comes back with the status of consider then your account can either proceed with the candidate if the violations don't disqualify the candidate, or you need to create an Adverse Action Letter.

When an Adverse Action letter is created in Yardstik, an email is sent to the candidate telling them that there were some things found that could disqualify them from the position and what they can do.

If the candidate is from the state of Georgia or California then when you create the Adverse Action email you need to provide an explanation of what specifically disqualified them from the position. When you try to create an Adverse Action and it fails a proper message will be returned to you, check the 422 Unprocessable Entity Response at Create a Adverse Action Route

We call these explanations violations, these violations are included in the Adverse Action Letter that is emailed to the candidate in question.

How do I know if the violations parameter is required?

In the response of the Show Report Route you will have the key adverse_action_settings which is a object, example:

  adverse_action_settings: {
    "mandatory_selection_of_violations": false
  }

Inside you have the key mandatory_selection_of_violations that you tell you if you should or should not send violations when creating a new Adverse Action.

Which violations can I send?

In the response of the Show Report Route you will have the key report_screenings which is an array and for each one you will have records which is also an array and inside each record you will have violations which is another array.

A record may not have violations. A clear report for example will probably not have any violations.

For each violation you will have at least a description but also it could have disposition and disposition_date.

So you can map all the violations and select the ones you want to send to create an Adverse Action.

Take a look in this example of a full Report response:

{
    "id": "2ee83662-ea17-4233-95b9-288ee3fcb9ff",
    "reference_id": null,
    "candidate_id": "66bdcd96-adf8-4b8a-b599-ea0040a11b79",
    "status": "consider",
    "response_status": null,
    "submitted_at": "2021-04-26T22:33:18.269Z",
    "completed_at": "2021-04-30T15:44:24.333Z",
    "created_at": "2021-04-26T21:51:06.880Z",
    "decision": "",
    "usage_amount": null,
    "process_sequentially": true,
    "created_by": "cool_email@yardstik.com",
    "permissible_purpose": {
        "id": "a2c00755-b57e-40e1-9876-2c5640ce53be",
        "name": "Employment",
        "configurations": { "initial_status": "pre_adverse" }
      }
    },
    "candidate": {
        "id": "66bdcd96-adf8-4b8a-b599-ea0040a11b79",
        "full_name": "John Clean",
        "email": "cool_email@yardstik.com",
        "phone_masked": null,
        "date_of_birth_masked": "#######-12",
        "ssn_masked": null,
        "driver_license_number_masked": null,
        "full_address": {
            "address": "Mineapolis",
            "zip_code": "12345",
            "city": "Mineapolis",
            "state": "MN"
        },
    },
    "account_id": "d210dcdd-c9d4-4ced-a594-8402cb6a2ab4",
    "account_name": "Account Name",
    "report_url": null,
    "adverse_action_id": null,
    "report_screenings": [
        {
            "id": "e11b7d00-9b55-4879-8f6e-c3859f16347d",
            "type": "Criminal",
            "label": "CountyCriminal",
            "name": "CountyCriminal",
            "status": "consider",
            "order": 0,
            "decision": "Consider",
            "response_status": "ready",
            "created_at": "2021-04-26T22:33:18.218Z",
            "report_url": "",
            "elapsed_timing": "1 week",
            "records": [
                {
                    "category": {
                        "key": "County",
                        "value": "NY-NYOCA"
                    },
                    "messages": [],
                    "violations": [],
                    "personal_data": {},
                    "other_information": {
                        "jurisdiction": "NY-NYOCA",
                        "pending_notes": null
                    }
                }
            ],
            "comments": []
        },
        {
            "id": "c6851635-9ce4-47ce-a246-531fbe36aac0",
            "type": "Criminal",
            "label": "StateCriminalCourt",
            "name": "StateCriminalCourt",
            "status": "consider",
            "order": 0,
            "decision": "Consider",
            "response_status": "ready",
            "created_at": "2021-04-26T22:33:18.228Z",
            "report_url": "",
            "elapsed_timing": "1 week",
            "records": [
                {
                    "category": {
                        "key": "State",
                        "value": "NEW YORK"
                    },
                    "messages": [],
                    "violations": [
                        {
                            "comments": null,
                            "sentence": "24 Months Or Pretrial Intervention Next Court Date 01/01/2021",
                            "file_date": "2021-03-20",
                            "case_number": "ABCDEFG",
                            "description": "Felony",
                            "disposition": "Court: Pre Trial Intervention",
                            "jurisdiction": "NEW YORK",
                            "offense_date": null,
                            "count_offense": "1. Possession Of Schedule 4 Substance",
                            "dob_on_record": "XXXX-04-01",
                            "ssn_on_record": null,
                            "name_on_record": "MESS, HANK",
                            "disposition_date": "2021-03-20"
                        },
                        {
                            "description": "This one Has Only the description",
                        }
                    ],
                    "personal_data": {},
                    "other_information": {
                        "jurisdiction": "NEW YORK",
                        "pending_notes": null
                    }
                },
                {
                    "category": {
                        "key": "State",
                        "value": "MINNESOTA"
                    },
                    "messages": [],
                    "violations": [
                        {
                            "comments": null,
                            "sentence": "24 Months Or Pretrial Intervention Next Court Date 10/08/2015",
                            "file_date": "2014-08-20",
                            "case_number": "POIUYTREWQ",
                            "description": "Felony",
                            "disposition": "Court: Pre Trial Intervention",
                            "jurisdiction": "MINNESOTA",
                            "offense_date": null,
                            "count_offense": "1. Possession Of Schedule 4 Substance",
                            "dob_on_record": "XXXX-04-01",
                            "ssn_on_record": null,
                            "name_on_record": "MESS, HANK",
                            "disposition_date": "2015-09-18"
                        },
                        {
                            "comments": null,
                            "sentence": "24 Months Or Pretrial Intervention Next Court Date 10/08/2015",
                            "file_date": "2014-08-20",
                            "case_number": "502008CF012155YXYXMB",
                            "description": "Felony",
                            "disposition": "Court: Pre Trial Intervention",
                            "jurisdiction": "MINNESOTA",
                            "offense_date": null,
                            "count_offense": "2. Possession Of Schedule 2 Substance",
                            "dob_on_record": "XXXX-04-01",
                            "ssn_on_record": null,
                            "name_on_record": "MESS, HANK",
                            "disposition_date": "2014-09-18"
                        },
                        ...
                    ],
                    "personal_data": {},
                    "other_information": {
                        "jurisdiction": "MINNESOTA",
                        "pending_notes": null
                    }
                }
            ],
            "comments": []
        }
    ],
    "report_screenings_total": 2,
    "report_screenings_completed": 2,
    "elapsed_timing": "4 days",
    "package_name": "State Criminal Court",
    "comments": [],
    "course": {
        "has_courses": false,
        "courses_completed": false
    },
    "meta": {
        "entity": "https://app.yardstik.com/reports/1234....",
        "apply": "https://profile.yardstik.com/candidates/1234
    },
    "adverse_action_settings": {
        "mandatory_selection_of_violations": false
    }
}

Errors

Sometimes you will receive an error back from a request. These can be caused by many reasons that we are going to go over. We return a number of standard HTTP errors. Below are some of the most common errors that you may run into while developing.

Status Definition
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
422 Unprocessable Entity
500 Internal Server Error

Below are theses status codes with a bit more information on what could have occurred.

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 or having a malformed API key in the request header.

  • code: 401

  • status: Unauthorized

Unauthorized

Response Schema: application/json
errors
Array of strings
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 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

HTTP/1.1 403 Forbidden
Date: Wed, 21 Oct 2015 07:28:00 GMT

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

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

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

  {
      "title": "Error Title",
      "detail": "Validation failed: Some message stating what may have failed",
      "meta": {},
      "src": {},
      "status": 422
  }

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

Embeddable Views

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

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

Installation

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

  • with npm npm i @yardstik/embeddable-sdk

  • with yarn yarn add @yardstik/embeddable-sdk

Getting Started

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

import { Yardstik } from '@yardstik/embeddable-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 AccountDisclosureIframe 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 (from your backend) make a request to the JWT Route, using your API token for authorization.

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

Subaccounts

The Subaccount is basically an Account with a Parent Account associated with it.

With this association the Parent Account can provide a white label experience for the Subaccounts.

To create a Subaccount you have first to be enabled to do that, please reach out to support@yardstik.com in case you want to create and manage Subaccounts.

There are two important parameters you should provide when create a Subaccount: a Permissible Purpose and one or more Account Package.

To check the request details to create a Subaccount access: Create Subaccount Route

Permissible Purposes

Every account has at least one Permissible Purpose, a Permissible Purpose is a reason why a report is being requested on the Candidate. Here is a list of the possible Permissible Purposes:

  • Employment
  • Tenant
  • Consumer account review to meet requirements

Since an Account can have more than one Permissible Purpose, during the creation of a Subaccount you have to provide a permissible_purpose_id or the Subaccount that is being created.

To know what Permissible Purposes the Parent Account has, check the Get Account Route and in the response body will have permissible_purposes from the array you can determine the id of a given permissible purpose.

When you create a Subaccount, set the permissible_purpose_id with the id of the permissible_purposes you wish to use from the Parent Account.

You can set only one permissible_purpose_id for the Subaccount.

Account Packages

An Account Package contains the Screens that we will run for a Candidate. Any time you create an Invitation or a Report, an account_package_id must be provided.

During the creation of a Subaccount one or more Account Packages can be defined.

The list of AccountPackages that can be provided for the Subaccount can be found in here: Account Packages List.

When you create a Subaccount you will have to provide account package ids for: account_packages as an array with at least the id. So when the Subaccount is created it also creates the AccountPackages with the same configurations of the Parent Account.

Inside the account_packages your objects must follow this format:

  • id: The Parent AccountPackage ID.
  • name: The name for the Subaccount AccountPackage, if not provided will be the same as the Parent AccountPackage
  • paid_by: With the possible options of account or candidate. If not provided will be the same as the Parent AccountPackage.

Note: The paid_by param defines who will pay for the Report, if it's the Account or the Candidate. In case it's the Candidate a Payment form will show to the Candidate provide his credit card information and the report will only start to be processed after the payment is completed.

Example in how to provide the account_packages parameter:

  "account_packages": [
      {
          "id": "The UUID of one of the Parent AccountPackage",
          "name": "The Name for the Subaccount AccountPackage",
          "paid_by": "candidate"
      },
      {
          "id": "The UUID of one of the Parent AccountPackage",
          "name": "If not provided will be the same as the Parent AccountPacakge",
          "paid_by": "account"
      }
  ]

Click in here for more details how to create a Subaccount

Credentialing the Subaccount

After the Subaccount is created, an email will be sent to the Owner of the Subaccount, the Owner is created based on the parameter email_address provided during the Subaccount creation.

In that email, the Owner of the Subaccount will have a link that will take then to our application where it will ask them to sign the legal documents.

After the Owner signs the Legal Documents, our onboard specialists will review all the information provided and may require more information or more documents to be signed.

When everything is finished, the Subaccount will be credentialed and the Owner will be notified and it can start using Yardstik's platform.

Note: Only after the account is credentialed that the API Key generated on the Subaccount create route will be active. Once the API key is active it can be used to manage Yardstik resources via the API. You can also subscribe to the Webhook Type: account.updated so when any of Subaccount is updated you will receive a callback and you can check if that account is with the status credentialed.

If you encounter any error or have questions, please reach out to support@yardstik.com

Accounts

List all Accounts

List all accounts that you have access to.

Request
Security:
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

Unprocessable Entity

get/accounts
Request samples
curl -i -X GET \
  https://api.yardstik.com/accounts \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
[
  • {
    }
]

Create an API Key

Generate a new API key.

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

name of the api package

Responses
201

Created

401

Unauthorized

403

Forbidden

404

Not Found

422

Unprocessable Entity

post/accounts/{accountId}/api_token
Request samples
application/json
{
  • "name": "string"
}
Response samples
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.

Request
Security:
path Parameters
accountId
required
string
Responses
200

OK

401

Unauthorized

422

Unprocessable Entity

get/accounts/{accountId}/settings
Request samples
curl -i -X GET \
  https://api.yardstik.com/accounts/:accountId/settings \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "styles": {
    },
  • "invitations": {
    },
  • "report_notifications": {
    }
}

Get an account Setting

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

Request
Security:
path Parameters
accountId
required
string
settingKey
required
string
Responses
200

OK

401

Unauthorized

422

Unprocessable Entity

get/accounts/{accountId}/settings/{settingKey}
Request samples
curl -i -X GET \
  https://api.yardstik.com/accounts/:accountId/settings/:settingKey \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "primary_color": "FFCD01",
  • "secondary_color": "FFCD01"
}

Update an account Setting

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

Request
Security:
path Parameters
accountId
required
string
settingKey
required
string
Request Body schema: application/json
object
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

Unprocessable Entity

patch/accounts/{accountId}/settings/{settingKey}
Request samples
application/json
{
  • "primary_color": "FFCD01"
}
Response samples
application/json
{ }

Get an Account

Account ID details

Request
Security:
path Parameters
accountId
required
string
Responses
200

OK

201

Created

400

Bad Request

401

Unauthorized

422

Unprocessable Entity

get/accounts/{accountId}
Request samples
curl -i -X GET \
  https://api.yardstik.com/accounts/:accountId \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
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": [
    ]
}

Subaccounts

List Subaccounts

List all subaccounts that your account is parent of.

Request
Security:
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

Unprocessable Entity

get/sub_accounts
Request samples
curl -i -X GET \
  https://api.yardstik.com/sub_accounts \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
[
  • {
    }
]

Create a Subaccount

Create a Subaccount 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.
To create a Subaccount you will need to provide one Permissible Purpose.
You also can provide the account_packages information of your parent Account.

Request
Security:
Request Body schema:
account_name
required
string

name of the subaccount

Array of objects
actions_email_address
string

actions email address of the subaccount

additional_company_info
string

any extra information that you want to provide

required
object
company_phone_number
string

this is for our business verification purposes and will not be included on candidate communication

compliance_email_address
string

compliance email address of the subaccount

email_address
required
string

Email of the primary contact.

For this email address a user will be created and this User will be the Owner of the Subaccount.

This person also will be responsible to sign the legal documents for the Account Accreditation.

Check the documention about the Credentialing the Subaccount.

first_name
required
string

first name of the subaccount primary contact

last_name
required
string

first name of the subaccount primary contact

permissible_purpose_id
required
string <UUID>

the id for the permissable purpose that you want to give the subaccount

support_email_address
string

support email address of the subaccount

support_phone
string

support phone number of the subaccount

tech_email_address
string

tech email address of the subaccount

url
string

Relevant url for subaccount

Responses
201

Created

400

Bad Request

401

Unauthorized

422

Unprocessable Entity

post/sub_accounts
Request samples
{
  • "email_address": "string",
  • "account_name": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "company_phone_number": "string",
  • "additional_company_info": "string",
  • "url": "string",
  • "tech_email_address": "string",
  • "support_email_address": "string",
  • "support_phone": "string",
  • "actions_email_address": "string",
  • "compliance_email_address": "string",
  • "permissible_purpose_id": "string",
  • "address": {
    },
  • "account_packages": [
    ]
}
Response samples
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": [
    ],
  • "api_tokens": [
    ]
}

Get an Subaccount

You can get the details of any Subaccount that your account is parent of.

Request
Security:
path Parameters
sub_account_id
required
string
Responses
200

OK

400

Bad Request

401

Unauthorized

422

Unprocessable Entity

get/sub_accounts/{sub_account_id}
Request samples
curl -i -X GET \
  https://api.yardstik.com/sub_accounts/:sub_account_id \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "id": "string",
  • "account_name": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email_address": "string",
  • "status": "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": { }
}

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.

Request
Security:
query Parameters
page
integer

The page number to retrieve.

per_page
integer

The maximum number of results per page.

Responses
200

List of candidates

401

Unauthorized

get/candidates
Request samples
curl -i -X GET \
  'https://api.yardstik.com/candidates?page=0&per_page=0' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
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)
Request
Security:
Request Body schema: application/json
Array of objects

The addresses of the candidate.

date_of_birth
string or null <date-time>

The date of birth of the candidate.

driver_license_number
string or null

The drivers license number of the candidate.

driver_license_state
string or null

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

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

The middle name of the candidate.

phone
string or null

The primary phone number of the candidate.

previous_driver_license_number
string or null

The previous drivers license number of the candidate.

previous_driver_license_state
string or null

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
201

Candidate was created successfully

401

Unauthorized

post/candidates
Request samples
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
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.

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

The candidate id.

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

Candidate details

get/candidates/{candidate_id}
Request samples
curl -i -X GET \
  https://api.yardstik.com/candidates/:candidate_id \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
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.

Request
Security:
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 or null <date-time>

The date of birth of the candidate.

driver_license_number
string or null

The drivers license number of the candidate.

driver_license_state
string or null

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

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

The middle name of the candidate.

phone
string or null

The primary phone number of the candidate.

previous_driver_license_number
string or null

The previous drivers license number of the candidate.

previous_driver_license_state
string or null

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
200

Candidate details

401

Unauthorized

patch/candidates/{candidate_id}
Request samples
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
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.

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

The candidate id.

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

Deleted Candidate details

401

Unauthorized

delete/candidates/{candidate_id}
Request samples
curl -i -X DELETE \
  https://api.yardstik.com/candidates/:candidate_id \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
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

Request
Security:
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
200

Deleted Address details

401

Unauthorized

delete/candidates/{candidate_id}/addresses/{address_id}
Request samples
curl -i -X DELETE \
  https://api.yardstik.com/candidates/:candidate_id/addresses/:address_id \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
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

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

the unique identifier for the report

Responses
200

OK

401

Unauthorized

patch/candidates/{candidateId}/approve_by_report
Request samples
application/json
{
  • "report_id": "string"
}
Response samples
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.

Request
Security:
query Parameters
page
integer

The page number to retrieve.

per_page
integer

The maximum number of results per page.

Responses
200

List of invitations

401

Unauthorized

get/invitations
Request samples
curl -i -X GET \
  'https://api.yardstik.com/invitations?page=0&per_page=0' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "object": "list",
  • "meta": {
    },
  • "data": [
    ]
}

Create an Invitation

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

Request
Security:
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 or null

that is the code we show after the PII is completed

Responses
201

Invitation was created successfully

401

Unauthorized

post/invitations
Request samples
application/json
{
  • "account_package_id": "263fabf2-df86-40fd-8915-3ea60c091d57",
  • "candidate_id": "2f28f791-f0fd-4155-a356-c24e996beeda",
  • "invitation_code": "string"
}
Response samples
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.

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

The invitation id.

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

Invitation details

get/invitations/{invitation_id}
Request samples
curl -i -X GET \
  https://api.yardstik.com/invitations/:invitation_id \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
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.

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

The invitation id.

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

No Content

401

Unauthorized

delete/invitations/{invitation_id}
Request samples
curl -i -X DELETE \
  https://api.yardstik.com/invitations/:invitation_id \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "errors": [
    ]
}

Cancel an Invitation

Cancel an invitation with the given id..

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

The invitation id

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

Invitation successfully canceled

patch/invitations/{invitation_id}/cancel
Request samples
curl -i -X PATCH \
  https://api.yardstik.com/invitations/:invitation_id/cancel \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
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.

Request
Security:
path Parameters
accountId
required
string
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

Unprocessable Entity

get/accounts/{accountId}/packages
Request samples
curl -i -X GET \
  https://api.yardstik.com/accounts/:accountId/packages \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
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.

Request
Security:
Responses
200

OK

get/reports
Request samples
curl -i -X GET \
  https://api.yardstik.com/reports \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
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.

Request
Security:
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
200

OK

401

Unauthorized

post/reports
Request samples
application/json
{
  • "candidate_id": "string",
  • "account_package_id": "string",
  • "reference_id": "string"
}
Response samples
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": {
    }
}

Get a Report

Get a report with the given id.

Request
Security:
path Parameters
reportId
required
string
Responses
200

OK

401

Unauthorized

get/reports/{reportId}
Request samples
curl -i -X GET \
  https://api.yardstik.com/reports/:reportId \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
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": {
    }
}

Create a Adverse Action

Create a Adverse Action on a report with the given id.

During the creation of the Adverse Action, in the violations parameter the only required information is the description

The parameter violations it's required or not given some conditions.
Check the Adverse Action Violations Section for details when this parameter is required or not.

For more information about Adverse Action.

Request
Security:
path Parameters
reportId
required
string
Request Body schema: application/json
Array of objects
Responses
200

OK

401

Unauthorized

422

Unprocessable Entity

post/reports/{reportId}/adverse_actions
Request samples
application/json
{
  • "violations": [
    ]
}
Response samples
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

Request
Security:
path Parameters
adverse_action_id
required
string
Responses
200

OK

401

Unauthorized

patch/adverse_actions/{adverse_action_id}/cancel
Request samples
curl -i -X PATCH \
  https://api.yardstik.com/adverse_actions/:adverse_action_id/cancel \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
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.

Request
Security:
Responses
200

OK

401

Unauthorized

403

Forbidden

404

Not Found

422

Unprocessable Entity

get/webhooks
Request samples
curl -i -X GET \
  https://api.yardstik.com/webhooks \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
[
  • {
    }
]

Create a Webhook

Create a webhook

Request
Security:
Request Body schema: application/json
url
string
webhook_type_id
string
Responses
201

Created

401

Unauthorized

403

Forbidden

404

Not Found

422

Unprocessable Entity

post/webhooks
Request samples
application/json
{}
Response samples
application/json
{
  • "id": "e8b57b13-0038-4c69-99ee-1dae304afd80",
  • "webhook_type": "candidate.created",
}

Show a Webhook

Show a specific webhook given a webhook_id

Request
Security:
path Parameters
webhook_id
required
string
Responses
200

OK

401

Unauthorized

403

Forbidden

404

Not Found

422

Unprocessable Entity

get/webhooks/{webhook_id}
Request samples
curl -i -X GET \
  https://api.yardstik.com/webhooks/:webhook_id \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
[
  • {
    }
]

Update a webhook

Update a webhook given an ID

Request
Security:
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
201

Created

401

Unauthorized

403

Forbidden

404

Not Found

422

Unprocessable Entity

patch/webhooks/{webhook_id}
Request samples
application/json
{}
Response samples
application/json
{
  • "id": "e8b57b13-0038-4c69-99ee-1dae304afd80",
  • "webhook_type": "candidate.created",
}

Delete a webhook

Delete a webhook given an Id

Request
Security:
path Parameters
webhook_id
required
string
Responses
201

Created

401

Unauthorized

403

Forbidden

404

Not Found

422

Unprocessable Entity

delete/webhooks/{webhook_id}
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.

Request
Security:
Responses
200

OK

401

Unauthorized

403

Forbidden

404

Not Found

422

Unprocessable Entity

get/webhook_types
Request samples
curl -i -X GET \
  https://api.yardstik.com/webhook_types \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
[
  • {
    }
]

JWT

A JWT is required to access the Yardstik embedable views.

Get a JWT

Request
Security:
Request Body schema: application/json
user_email
string
Responses
200

OK

401

Unauthorized

post/web_tokens
Request samples
application/json
{
  • "user_email": "string"
}
Response samples
application/json
[
  • {
    }
]