Yardstik is a modern, RESTful API-driven Trust & Safety platform offering custom background screening and verification packages. Yardstik utilizes resource-oriented URLs that are authenticated via a single API key and leverage JSON in all responses, resulting in a seamless integration.

Since the founding of Yardstik in 2020, many companies across a variety of industries have utilized our Trust & Safety platform.

To learn more, please visit yardstik.com. For a more personalized experience, reach out to our support team at (support@yardstik.com), who can put you in touch with our engineering team for assistance.

To ensure a smooth integration of your application with Yardstik, we have outlined the basic user flow below. When you have a candidate that you want to perform a background check or verification on, these are the steps that one would follow to complete the process:

1. An applicant/candidate is selected to perform a background check and/or screening on.
2. You select an account package and create an invitation for the candidate.
3. The candidate receives an invite email or text message, leading them to the candidate intake form.
4. The candidate provides the required information for the background check(s) requested.
5. Once the candidate signs the legal and consent forms, their information is sent to our verification team who will perform a background check on the candidate and return a status depending on the results.
6. Once the results are ready, you now have a complete background check and/or screening on your candidate, and can decide what the next steps are.

Note: You have the option to place the cost of the background check and/or screening on the candidate. They will complete the payment during the intake process, before their information is sent to our verification team.

The information gathered from the candidate is determined by the account package that is used. The account packages contain information on what is required and will compile the correct collection steps in the candidate intake form, resulting in a smooth user experience for the candidate. Our onboarding team will assist in creating account packages that satisfy your business needs across the many positions your company may be hiring for.

Before you immerse yourself in the amazing world of background check integrations, you must first become registered and credentialed to use our product. Reach out to our support team at support@yardstik.com to get the necessary permissions and setup information.

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

Permissible purpose:

As a company that is 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). This law requires you to supply the candidate with the reason why the background check is being performed, otherwise known as a Permissible Purpose.

Some examples:

Permissible Purpose	Description
Tenant	The candidate is a potential tenant for your rental unit.
Employment	The candidate is a potential employee or contractor for your company. Or, the candidate is a current employee that requires periodic background checks or screenings to maintain their employment with your company.

Legal Business Name: The name of your company, as it appears on any government registration forms.

Owner's Email: The email address of whoever is assigned as the Yardstik Account Owner from your company, and who will be the main contact for communication to and from Yardstik.

First and Last Name: The first and last name of the Yardstik Account Owner.

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

Although we are an API first company, we have a user-friendly interface that allows you to manage your account. Using the interface, you can create API keys, manage candidate invites, view reports of background check and/or screening results (unless you are using the embedded views), track decisions on those results, and more. If you already have a user account set up, access the Dashboard here.

Here at Yardstik, we authenticate your API requests using API keys. The API key is passed in the header of a request under the Authorization: Account [YOUR API KEY]. Along with this it is recommended that you include Accept: application/json (if you do not include this, you may experience some unexpected errors).

Now that you have a credentialed account and are able to log in, you can obtain your first API key and start sending requests!

Getting your first API key is as simple as signing into the Dashboard, clicking on the Developer tab, and selecting the API Keys menu option. On this page, input a name for your API key (this cannot be edited later on, so be sure to choose a unique name) and click the Create button. After this, a window containing your full API key will appear once (and only once).

NOTE: WE DO NOT SAVE API KEYS. MAKE SURE YOU COPY THE API KEY BEFORE CLOSING THE WINDOW.

It is good practice to withhold your API keys from anyone who doesn't need them. If someone gets access to one of your API keys, they have complete access to all API calls on your company's behalf. We recommend not hardcoding API keys anywhere in your application and to not send API keys on any platform that isn't secure.

If you believe that your API key has been compromised, you can delete it from the Dashboard and create a new API key. If you need help, don't hesitate to reach out to Support for assistance.

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.

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

• Get your API key
• Authenticate with Yardstik
• Create an Invitation
• Listen for Webhooks
• Retrieve the Report
• Adverse Action Process

You can manage your API keys from your account dashboard at any time. Once your Yardstik account has been created, login to your dashboard, go to Developer Settings and create your first API key.

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 (must be formatted like "Account {API_KEY}" with the word "Account" preceding your API key).

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 can make requests to the API 🎉

This is an example 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 a Candidate route.

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 '{
    "first_name": "Kirk",
    "last_name": "Boehm",
    "email": "kirk.b@example.com",
    "phone": ""  optional
}'

After you complete this request, you should see a response that looks like the example 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":  "kirk.b@example.com",
"phone":  "+17514747858",
"ssn_masked":  null,
"additional_data":  {},
"guardian":  {},
"person_type": "candidate",
"active": true,
"person_sub_type": null,
"copy_requested": null,
"external_reference": [],
"external_id": null,
"evergreen": false,
"account":  {
    "id":  "15d9fd10-3927-4de6-a504-221971680f0e",
    "account_name":  "Company"
},
...
}

Now that you have created a candidate, you can invite that candidate to complete their intake form using the Create an 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 Account 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": "22269e7d-ea25-4166-b069-e50908c3678e",
    "status": "invite_sent",
    "invitation_code": null,
    "external_id": null,
    "platform_service_id": null,
    "expires_at": "2024-01-01T21:40:56.062Z",
    "canceled_at": null,
    "confirmation_code": "VWJ-14798",
    "created_at": "2023-08-29T15:14:31.430Z",
    "updated_at": "2023-08-29T15:14:31.615Z",
    "account_id": "15d9fd10-3927-4de6-a504-221971680f0e",
    "account_name": "Company",
    "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.com/invitations/ID",
        "apply": "https://profile.yardstik.com/candidates/ID/apply?report_id=ID&account_package_id=ID&auth_type=email"
    },
    "report": {
        "id": "ID",
        "status": "created"
    }
}

The candidate will now receive an email and/or SMS asking them to complete the form. In the meta tag of the response, there is a key named apply. This is the link that they will be sent. If the account has SMS invites enabled and the candidate information contains a valid phone number, they will be sent an SMS invite. Contact our Support team to learn more about how to enable SMS communications for your account.

Status	Definition
invite_sent	The invitation has been sent, no other action has been taken by the candidate yet.
viewed	The invitation has been viewed by the candidate, but not clicked yet.
clicked	The invitation link has been clicked by the candidate, but they have not completed the intake form.
completed	The invitation has been completed by the candidate and the report will begin processing.
canceled	The invitation has been canceled. The candidate will not be able to access the intake form for this invitation.
expired	The invitation has expired. The candidate will not be able to access the intake form for this invitation. For more details about expirations, see Invitations.

See Invitations for more information about the invitation resource.

Yardstik uses webhooks to push events to your application when various events related to your resources occur. 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 Resource for details about available API calls.

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	A candidate has signed disclosures and given consent 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	An invitation has been created.
invitation.updated	An invitation has been updated.
invitation.deleted	An invitation has been deleted.
report.created	A report has been created.
report.updated	A report has been updated.
report.completed	A report has been completed.
report.deleted	A report has been deleted.
monitor.created	A monitor has been created.
monitor.updated	A monitor has been updated.
monitor.deleted	A monitor has been deleted.
monitor_record.created	A monitor record has been created.
monitor_record.updated	A monitor record has been updated.
monitor_record.deleted	A monitor record has been deleted.
account.updated	An account has been updated.
sub_account.active	The Subaccount was activated by Yardstik support.

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 candidate has been created."
    },
    {
        "id": "48a9b600-e7ff-4039-bcb2-04cddab97ba8",
        "system_name": "report.completed",
        "description": "A 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 and system_name when referencing the webhook type when creating new webhooks.

Using Webhook Signing, you can ensure that requests sent to your application are from Yardstik and have not been tampered with. You should use the webhook signature to avoid processing requests that are not from Yardstik and to protect your application from bad actors.

Enabling Webhook Signing

To enable webhook signatures, simply create an API key named WEBHOOK_SIGNATURE (see: Authentication). Yardstik will automatically use your WEBHOOK_SIGNATURE API key to sign the webhook payload using an SHA-256 HMAC hex digest. Make sure you copy the API key to a safe location before leaving the page as it will not be visible after you close. You will use this API Key to generate your own HMAC hash against the payload you recieved to verify that

1. The secret API key you generated was used to sign the request, proving it came from Yardstik.
2. The message payload has not been modified, protecting against man-in-the-middle attacks.

How to validate webhooks

The HMAC hash value that Yardstik signs your webook with will be included in the headers of the request as: x-yardstik-webhook-signature

You will use theWEBHOOK_SIGNATURE API key to generate an HMAC hash of the body of the request and validate the authenticity of that webhook.

If the value ofx-yardstik-webhook-signature is: a1342d29ce3b28c4416482f64a3e8b9f452a22755646d7ca9a553e654676b693
Then your app should also calculate the value as: a1342d29ce3b28c4416482f64a3e8b9f452a22755646d7ca9a553e654676b693

As long as those two values are equal, you should accept the request. If they differ, your application should reject the webhook and stop processing.

A verification function can be used to validate the HMAC-SHA256 value using a crypto library of your choice, such as the Node.js crypto module. The function should calculate a hash using your WEBHOOK_SIGNATURE API key, and ensure that the result matches the hash sent by Yardstik.

Putting it all together

Example Code

The following code sample is a simple Node.js example showcasing how to validate webhook signatures using Crypto libraries behind an Express server.

const crypto = require('crypto');
const express = require('express');
const app = express();
const port = 3000;

app.use(express.json());

app.post('/', (req, res) => {
    const SIGNATURE = req.get('x-yardstik-webhook-signature');
    const BODY = req.body;
    console.log(BODY);

    const HASH = crypto.createHmac('sha256', process.env.WEBHOOK_SIGNATURE).update(JSON.stringify(BODY)).digest('hex');

    console.log(`This is the x-yardstik-webhook-signature: ` + SIGNATURE);
    console.log(`This is your application's calculated hash: ` + HASH);

    // Respond with a 200, if you do not respond with a success code Yardstik will retry the request.
    res.sendStatus(200);
})

app.listen(port, () => {
  console.log(`Example app listening on port ${port}`)
})

Example Output

Example app listening on port 3000
{
  id: '42eff0e4-9bca-45da-a143-2d4e1e271d88',
  event: 'updated',
  resource_id: 'efa32155-f8cb-4331-954c-11db22ae773d',
  account_id: '16fab437-3ab5-4ee1-8a47-16ab41410a5e',
  account_name: 'Example Account',
  resource_type: 'report',
  resource_url: 'https://api.yardstik.com/reports/efa32155-f8cb-4331-954c-11db22ae773d',
  status: 'processing',
  timestamp: '2024-07-10T18:56:44Z'
}
This is the x-yardstik-webhook-signature: a1342d29ce3b28c4416482f64a3e8b9f452a22755646d7ca9a553e654676b693
This is your application's calculated hash: a1342d29ce3b28c4416482f64a3e8b9f452a22755646d7ca9a553e654676b693

The function above uses an environment variable name WEBHOOK_SIGNATURE that contains the API key you created. The app will extract the body from the request sent to the / endpoint and use the Node.js crypto library and your API key to create its own hex digest that should match the header included in the request.

Using a tool like ngrok, you can start this locally and receive calls from our API to your dev workstation to verify that webhook signing is working. NOTE: Ask your security team before running port forwarding applications that expose your app to the internet!

Additional sample webhook responses, POST bodies, and more are available in the Using Webhooks section.

Support

If your webhook signature has been lost or compromised, you can decommission it from the Dashboard and create a new one. You can view best practices for keeping your keys safe here. If your webhook signature isn't working, don't hesitate to reach out to support.

Listening for candidate.created Webhook

For example, you may register a webhook for candidate.created. This webhook will be triggered 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 response body presented above. You can use this to get the candidate ID from the resource_url key.

Listening for report.created Webhook

Let's say you also want to be notified when a background report has been created. To do so, you can register for the 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_created",
    "enabled": true,
    "webhook_type": "report.created",
    "webhook_description": "A report has been 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

If you are an Admin for a platform account and want to manage your subaccount(s), you can do so using the sub_account.active webhook. If you are not sure whether you are managing a platform account or not, 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",
    "enabled": true,
    "webhook_type": "sub_account.active",
    "webhook_description": "A subaccount has been activated by Yardstik support."
}

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.com/accounts/21e2830c-b88e-42e-a5ed-5e316069b21"
}

This webhook can be used to determine when a subaccount under your platform account has been credentialed, so that you can perform whatever operations are needed. A credentialed subaccount has been approved to begin ordering background check 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,
    "external_id": null,
    "active": "true",
    "candidate_id": "018e6289-78e9-45b8-9c8e-9d78f8b4fba4",
    "status": "clear",
    "response_status": null,
    "adjudication": null,
    "submitted_at": "2023-08-25T16:25:21.715Z",
    "completed_at": "2023-08-25T16:26:00.202Z",
    "created_at": "2023-08-25T16:15:11.428Z",
    "updated_at": "2023-08-25T16:26:00.314Z",
    "decision": "",
    ...
    "account_id": "bd17432e-80fb-4519-a82f-64343be8ca76",
    "account_name": "General Dynamics",
    "report_url": "[URL to Report PDF]",
    "adverse_action_id": null,
    "report_screenings": [
        {
            "name": "NationalCriminal"
        },
        ...
    ],
    ...
}

Once a report has been completed, it will be assigned a status. The available statuses can be found below.

There are many different statuses a candidate's report can be in. Here, we've grouped the statuses to illustrate what they mean in relation to the report's progress. You can find the detailed descriptions of each status below.

Not Started	Moving Along	Paused	Action Needed	Done
Created Expired	Queued Processing Pending Pre-Adverse Approved To Process	Info Requested Dispute Pending Approval YS QA Review Exception	Consider	Clear Proceed Final Adverse Canceled Pass Fail

Status	Definition
created	The report was successfully created and is ready to receive candidate information/consent.
expired	The report was created, but didn't receive candidate information/consent before its invitation's expiration date. An expired report can be reopened by refreshing its invitation. For more about expiration and how to customize, see Invitations.
queued	The report is waiting for the next screening to start processing.
processing	Our verifications team is processing the report.
pending	We're waiting on a response from a third party (e.g. a court runner is retrieving records for a County Criminal check).
pre_adverse	In response to the report being in consider status, one of your admins decided to kick off the Adverse Action Process.
approved_to_process	On reports where the candidate is a minor, this indicates that their guardian provided consent for us to process their report.
info_requested	The candidate information we received wasn't sufficient to run the report. We've asked the candidate to provide the information we need and are waiting for their response.
dispute	The candidate has filed a dispute regarding the accuracy or completeness of the results in their reports. Our verifications team is investigating.
pending_approval	On reports where the candidate is a minor, this indicates that we're waiting for their guardian to provide consent for us to process the report.
ys_qa_review	If you've opted for us to manage the Adverse Action Process for you, this indicates that results have been added to the report which may disqualify the candidate. Our verifications team is reviewing and will decide next steps based on your adjudication matrix.
exception	There is an issue with the report data (e.g. SSN is incorrect) that is preventing the report from processing. Our verifications team will contact the candidate for the correct information.
consider	Results have been added to the report which may disqualify the candidate. One of your admins needs to review and decide whether to set the report to proceed or kick off the Adverse Action Process.
clear	The report has finished processing and no disqualifying results were found.
proceed	In response to the report being in consider status, one of your admins decided to set the report to proceed, indicating that the results found do not disqualify the candidate.
final_adverse	The Adverse Action Process is complete and it has been determined that the results found disqualify the candidate.
canceled	The report was canceled and no decision has been made about the candidate. No additional activity will occur on this report.
pass	On reports where there are exclusively pass/fail outcomes (e.g. reports with Identity Verification and no additional screenings), pass indicates a positive "done" state.
fail	On reports where there are exclusively pass/fail outcomes (e.g. reports with Identity Verification and no additional screenings), fail indicates a negative "done" state.

See Reports for more information.

To create a candidate, collect the candidate's information and send the information gathered to our /candidates route via a POST method. This will be processed by our system and return a candidate ID that is used to create a report.

Using the candidate ID, along with your account ID and an account package ID, you will POST this data to the /reports endpoint and generate a new report. This will return the apply url, which will be given to the candidate to fill out the intake form.

Once the candidate fills out the form and submits disclosures, the report will begin processing.

When a report comes back with the a consider status, this indicates that there were some violations that may disqualify the candidate for employment or tenancy.

From here, the candidate is reviewed by either a client user or an API user to make the final decision on whether or not 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. According to the FCRA, the minimum number of days a candidate is allowed to respond to an adverse action is 7 days. This time frame can be extended in the account notifications settings.

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. If the candidate is completing a background screening in order to become a tenant in an apartment complex, there is no need to have this process. They will go directly into the final adverse status. When the tenant is placed directly into final adverse, a reason must be selected. This will be presented to the denied tenant.

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

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

Example Adverse action Error Response

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

During the process of creating an adverse action, you may need to provide a list of violations.

If a report comes back with a status of consider, then there may be an additional step. If the violations don't disqualify the candidate, your account can proceed with the candidate. If they do, then you need to create an Adverse Action Letter.

When an Adverse Action Letter is created in Yardstik, an email is sent to the candidate. The email will contain the details of what could disqualify them from the position, and what their next steps are.

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 the 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 Get a Report Route, you will have the adverse_action_settings key.

Example:

  adverse_action_settings: {
    "mandatory_selection_of_violations": false
  }

In the response, you have the mandatory_selection_of_violations key, which tells you whether you should or should not send violations when creating a new adverse action.

Which violations can I send?

In the response of the Get a Report Route, you will have the report_screenings key, which is an array. For each report screening, you will have records, which is also an array. Finally, inside each record you will have violations, which is another array.

A record may not have violations. For example, a clear report will probably not have any violations.

For each violation, you will have a description, and it also could have a disposition and disposition_date.

You can map all the violations and select the ones you want to send to the candidate.

Here's an 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
    }
}

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.

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'

Paginated 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: 200

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 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 included in each response. The maximum value allowed is 200, with a default value of 50.

• If there are fewer resources available than the per_page value, the response will include all available resources.
• If you pass more than 200, the response will still include only 200.
• If the per_page value is an invalid type, the default value of 50 is used.

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

For all listing endpoints, we support a filtering query param called query that allows you to pass a field name and a matcher to use to filter the results down a specific set. We also support two query params called order_by and order that let you pass the field name you want to order by, and the direction you want the results ordered. When combined with Pagination, this allows you to build a custom UI that lists out resources with ease.

Parameter	Description
query	Field name to filter on. type: string

Get only reports created before Jan 1 2021

curl -g -X GET \
  'https://api.yardstik.com/reports?query[created_at_lt]=2022-01-01' \
  -H 'Authorization: Account [YOUR_API_KEY]' \
  -H 'Accept: application/json'

Get only reports updated after Jan 1 2021

curl -g -X GET \
  'https://api.yardstik.com/reports?query[updated_at_gteq]=2022-01-01T00:00:00.000Z'
  -H 'Authorization: Account [YOUR_API_KEY]' \
  -H 'Accept: application/json'

Get reports created between March 23 2021 and April 1 2021

curl -g -X GET \
  'https://api.yardstik.com/reports?query[created_at_lt]=2021-04-01&query[created_at_gt]=2021-03-23' \
  -H 'Authorization: Account [YOUR_API_KEY]' \
  -H 'Accept: application/json'

Matchers

Predicates	Description	Notes
*_eq	Equal	query[status_eq]=created Individual check, to do multiple see *_in
*_not_eq	Not equal	query[status_not_eq]=created Individual check, to do multiple see *_not_in
*_lt	Less than	query[created_at_lt]=2022-01-01
*_lteq	Less than or equal to	query[created_at_lteq]=2022-01-01
*_gt	Greater than	query[created_at_gt]=2022-01-01
*_gteq	Greater than or equal to	query[created_at_gteq]=2022-01-01
*_null	Is null	query[completed_at_null]=true
*_not_null	Is not null	query[completed_at_not_null]=true
*_in	Match any value in array	query[status_in][]=clear&query[status_in][]=consider
*_not_in	Match none of the values in array	query[status_not_in][]=clear&query[status_not_in][]=consider
*_start	Starts with	query[status_start]=con
*_not_start	Does not start with	query[status_not_start]=con
*_end	Ends with	query[status_end]=sider
*_not_end	Does not end with	query[status_not_end]=sider
*_cont	Contains	query[status_cont]=con
*_not_cont	Does not contain	query[status_not_cont]=con
*_true	Is true	query[active_true]=true
*_false	Is false	query[active_false]=true

Parameter	Description
order_by	Field name to sort on. type: string
order	Specifies the direction to sort. Accepts asc and desc. Defaults to asc when not passed type: string

Order candidates by created_at in default ascending order (oldest first)

curl -g -X GET \
  'https://api.yardstik.com/reports?order_by=created_at
  -H 'Authorization: Account [YOUR_API_KEY]' \
  -H 'Accept: application/json'

Order candidates by updated_at in descending order (newest first)

curl -g -X GET \
  'https://api.yardstik.com/reports?order_by=updated_at&order=desc
  -H 'Authorization: Account [YOUR_API_KEY]' \
  -H 'Accept: application/json'

Combine it all together

You can use pagination, querying and ordering all on the same call to fully control the results. This will get all reports created between March 23 2021 and April 1 2021 and order them by the created_at field with newest first while limiting the results to 20 per page.

curl -g -X GET \
  'https://api.yardstik.com/reports?query[created_at_lt]=2021-04-01&query[created_at_gt]=2021-03-23&order_by=created_at&order=desc&page=1&per_page=20' \
  -H 'Authorization: Account [YOUR_API_KEY]' \
  -H 'Accept: application/json'

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 the status codes with more information on what could have occurred.

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

• code: 400
• status: Bad Request

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

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

• code: 403
• status: Forbidden

The requested resource could not be found but may be available in the future. This error is often encountered when an id that does not exist is passed in a request. If you encounter this error, ensure that you are referencing the correct id and that it exists in your account.

• code: 404
• status: Not Found

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. Refer to the request documentation to ensure you are supplying the required attributes, and that the attribute types are correct.

• code: 422
• status: Unprocessable Entity

An internal server error occurred due to an unexpected condition, and 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

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

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

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

Here is a quick example to get you started:

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

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.

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

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

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

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.

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

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

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

A Subaccount is an account associated with a Parent Account.

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

In order to create and manage Subaccounts, please reach out to support@yardstik.com to have this feature enabled.

There are two important parameters you must provide when creating a Subaccount: a Permissible Purpose and one or more Account Packages.

The request details to create a Subaccount can be found here.

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 for the Subaccount that is being created. You can set only one permissible_purpose_id for the Subaccount.

To know what Permissible Purposes the Parent Account has, check the Get Account Route. The response body will have permissible_purposes. From this array, you can determine the id of a given Permissible Purpose.

An Account Package contains the screenings and verifications 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 Account Packages that can be provided for the Subaccount can be found here: Account Packages List.

When you create a Subaccount, you need to provide an account_packages array, and that array must include an id parameter. This means when the Subaccount is created, it also creates the Account Packages with the same configurations as the Parent Account.

Inside the account_packages array, your objects must follow this format:

• id: The Parent Account Package ID.
• name: The name for the Subaccount Account Package. It will default to the Parent Account Package if this is not provided.
• paid_by: With the possible options of account or candidate. It will default to the Parent Account Package setting if this is not provided.

Note: The paid_by param defines who will pay for the report. This could be the account or the candidate. In the case of the candidate, a payment form will show to the candidate to provide their credit card information, and the report will only start to be processed after the payment is completed.

Example for how to provide the account_packages parameter:

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

Click here for more details how to create a Subaccount

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

In that email, the owner of the Subaccount will have a link that will take them 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 if necessary.

Once the process has been completed, the Subaccount will be credentialed, and the owner will be notified that they can start using Yardstik's platform.

Note: The API Key generated on the Subaccount create route will only be active after the account is credentialed. 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 By doing this, when any Subaccount is updated, you will receive a callback and can check if that account has the status credentialed.

• How to Subscribe to Webhooks
• Get Subaccount Information

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

Accounts are your primary resource for configuring the Yardstik platform.
Use this to manage users, settings, and API keys.

Subaccounts are children of a parent account, and can be used to isolate resources and configuration settings.

Packages are collections of background screens, searches, and verifications used to create a report.

You can add custom fields to resources in an account.
To begin leveraging candidate custom fields please reach out to support@yardstik.com for field setup.