Order Creation

Introduction

Background check and Drug screening

An order can be placed for a background check, drug screen, or a combination of both, facilitated through the Create Order operation.

Orders can specify various workflows. The workflow used is based on the following request properties:

  • fallbackModel: Defines the fallback behavior in case some required data is not available. Allowable values are InviteApplicant, GenerateWebLink, InviteRequestor, ManualSubmit, and None.

  • forceFallback: Skips data validation and initiates the fallback. Allowable values are true and false.

  • throwbackModel: When fallbackModel is InviteApplicant, specifies how to handle cases where the invite can’t be sent. Allowable values are ManualSubmit, GenerateWebLink, and InviteRequestor.

  • duplicateCheckModel: Disables account-specific duplicate order checks when placing the order, in case a similar order already exists in HireRight's system. The only allowed value is None.

The operation response returns the list of products being ordered, or if a fallback was triggered, the relevant fallback information.

The response also returns a unique order id generated by HireRight, which must be captured by the client. This id is subsequently used with other API operations to reference that specific order.

HireRight I-9 Products

For ordering the HireRight I-9 products please see the following page: I-9 Management.

Workflows

2-Step Recruiter Workflow

fallbackModel = GenerateWebLink
forceFallback = true

  1. The requester (user) initiates a new order on the client system.

  2. The client system sends background data to HireRight.

  3. HireRight generates a URL that is returned to the client system.

    1. Please note the link returned is a one-time use link that will expire approximately after 2 hours.

  4. The client system redirects the user’s browser to the generated URL.

  5. The requester completes the submitted order on the HireRight side (this is “Step 2”).

    1. On the HireRight interface, the requester can choose either “Invite Applicant to complete the background forms” or “Complete background forms myself”.

    2. If more than one company account is available, the requester also confirms the specific account for the order.

Notes:

  • The steps mentioned above describe the GenerateWebLink fallback model which is the most commonly used 2-Steps workflow.

  • If the GenerateWebLink fallback model is used, the steps mentioned above must be followed in order to access HireRight and complete the request submission; any other steps used can cause issues in specific situations and HireRight will not support those.

  • The API supports also other variations of the 2-Steps workflow using the InviteRequestor and ManualSubmit fallback models, which provide different ways to access HireRight in order to complete the request submission.

  • Please note, if upon order submission more than one HireRight company account is available for ordering and those company accounts are located across multiple global locations, additional configuration may be required to support this ordering workflow. Please contact the assigned HireRight technical resource for assistance.

1-Step Applicant Invite Workflow

fallbackModel = InviteApplicant
forceFallback = true

  1. The requester (user) initiates a new order on the client system.

  2. The client system sends background data to HireRight.

  3. HireRight sends an email invitation to the applicant.

  4. The applicant logs in to the HireRight Applicant Center and complete the background check forms.

Note: The API also supports returning the unique login URL from the email invite in the API response, enabling clients to provide their applicants access to HireRight Applicant Center directly from their platform. If you are interested in this feature, your HireRight technical contact can enable this for you.

Faceless Workflow

fallbackModel = (any)
forceFallback = false

  1. The requester (user) initiates a new order on the client system.

  2. The client system sends background data to HireRight.

  3. HireRight creates the order immediately, without any requester or applicant input.

    1. Any missing or invalid information will either return an error or trigger one of the other workflows based on the specified fallbackModel.

    2. Note that consent forms are also required, and can be passed through the API.

Integrations Workflows: Pros and Cons

The following table summarizes the advantages and disadvantages of the three basic workflows:

Packages and Products

When placing an order, the client must specify a package id and/or specific products for the order.

"packageId": "502653",
"products": [
        { "name": "SSN Trace" },
        { "name": "Criminal Felony & Misdemeanor" }
]

  • packageId: A group of products, pre-configured for the client by HireRight.

  • products: An array of individual products that are ordered a la carte.

For the 2-Step Recruiter workflow, packages or products are not required to be provided by the API, but are required for the other workflows.

Available packages and products can be queried with the Get Packages and Get Products operations.

Best practice:

  • If the 2-step Recruiter workflow is used, do not provide packages/products through the API and allow the user to select those on the HireRight side. 

  • If another workflow is used, get the packages using Get Packages each time the user is initiating a new order, allowing them to select a package on the client-side. 

Flex Fields

An order can be associated with client-specific metadata, known as FlexFields, which is a simple array of name and value pairs. FlexFields can be used to pass information that should be shown on the order report, associated with an invoice, and other scenarios.

Here is a request fragment showing two FlexFields for RequisitionNumber and CostCenter. Note that FlexField values have a 256-character maximum.

"flexFields": [
    {
        "name": "RequisitionNumber",
        "value": "Req225112"
    },
    {
        "name": "CostCenter",
        "value": "C003253"
    }
]

Consent Forms

The employer is required by law to obtain the applicant’s written consent before procuring a background report from HireRight. An electronic copy of the applicant’s consent can be provided to HireRight as a Base64-encoded PDF document inside the supportingDocuments array of the order request body.

Alternatively, there is an option to mark the consent forms as not required on the HireRight side in case the client signs on paperwork, confirming that the consent forms are collected on the client-side.

Here is a request fragment showing how to embed consent forms into the supportingDocuments array:

"supportingDocuments": [
    {
        "type": "release",
        "resultType": "x:Signed",
        "manifestName": "Consent Form",
        "mediaType": "pdf",
        "text": "<base64-encoded-form>"
    }
]

Multiple Account Support

Clients may have multiple accounts (different company logins) set up on the HireRight side. For example, client ABC can have 3 accounts for ABC: USA, ABC: Germany, and ABC: Canada.

The way that multiple accounts are handled through the API depends on the workflow:

  • 2-Step Recruiter Workflow

    • If the requester appears on multiple accounts on the HireRight side, an account selection is displayed to the user, which includes all accounts the user appears on. The user can select the ordering account and the request will be routed to this account accordingly. If the user appears just on one account, the request will route to this account automatically.

    • Please note, if upon order submission more than one HireRight company account is available for ordering and those company accounts are located across multiple global locations, additional configuration may be required to support this ordering workflow. Please contact the assigned HireRight technical resource for assistance.

  • 1-Step Applicant Invite or Faceless Workflow

    • Options:

      1. Send the specific hr-company-login header parameter in each request (note that a non-parent account may need to be set in this case).

      2. Send the parent account in the hr-company-login header parameter in each request. In this case, there must be some configuration on the HireRight side to determine how to route the order to the right account.

        • Options:

          1. Route the order according to the packageId provided in the request. In this case, packages must be unique between the different accounts.

          2. Route the order according to a FlexField that is provided in the request that uniquely distinguishes between the accounts on the HireRight side. For example, if there are three accounts on the HireRight side for the USA, Germany, and Canada, it is possible to send over a country FlexField in each request and HireRight can set the routing accordingly. This must be configured on the HireRight side as well for it to be supported.

        • Note: If the requester appears just on one account, the request will be routed directly to this account. In this case, all other routing rules are ignored.

Duplicate Detection Support

Duplicate detection can be handle in a number of different ways depending on the workflow utilized, typical solutions can be found below:

  • 2-Step Recruiter Workflow

    • Duplicate detection is supported as part of the workflow within the HireRight interface

    • If a duplicate is detected, the user will be warned after they transition to HireRight to complete the request submission
      (At this step the user can decide to move forward with the order or cancel it)

  • 1-Step Applicant Invite or Faceless Workflow

    • Options:

      1. Workflow is automatically changed to 2-Steps workflow

        • HireRight applies the configuration to change the workflow to a 2-Step workflow when duplicates are detected

        • The client's system is required to handle the 2-steps workflow (such as open the URL returned by HireRight)

      2. Duplicates are displayed within the client's system

        • Order creation response from HireRight will contain a duplicate error when duplicates are detected along with a list of detected duplicate(s)

        • The list of duplicate(s) should be displayed to the user with the client's system along with 2 actions: 

          1. Action 1 – Continue Order Submission

            • If selected, client's system submits an additional POST /order operation via the API and includes duplicateCheckModel = None

              • This flag instructs the HireRight API to ignore any detected duplicates, allowing the new order to be submitted

          2. Action 2 – Cancel Order

            • If selected, client's system closes the UI displaying the duplicated error message and no further action is needed via the API

Data Mapping

Data Mapping Importance

For a Faceless workflow, all data required for the order should be provided through the API.

For other workflows, only the candidate's first name, last name, and email are required. Even so, it is still highly recommended to map as many fields as possible in order to ensure the best experience. Fields passed over will be pre-populated on the forms, reducing re-entry of data and making the process easier and faster for the candidate.

Job Location Mapping

The Job Location field has been required since 2017. The collection of this data supports the new Pay Equity measures and is a necessary step in ensuring that HireRight and our clients remain in compliance with current and future legislation.

Posting a new order can also work without passing job locations. It is highly recommended to pass this data through the API to improve the end user's experience.

The required job locations by country are:

  • US: Country, City, State, and Zip Code

  • UK: Country and Region (where the region is England, Wales, Scotland, or North England)

  • All other Countries: Country only

The default behavior when job location is not passed through the integration is:

  • 1-Step Applicant Invite Workflow: Job location is collected from the applicant during online form completion via HireRight’s Applicant Center. After the order is submitted, an email notification is sent to the requester notifying him/her of the job location attached to the order. If the job location is not accurate, the requester must cancel the order and submit a new one, advising the applicant of the correct job location to provide.

  • 2-Step Recruiter Workflow: The job location is collected from the requester on HireRight, at the time of request initiation.

  • Faceless Workflow: The default pre-configured job location on the ordering account is attached to the order. After the order is submitted, an email notification is sent to the requester notifying him/her of the job location attached to the order. If the job location is not accurate, the requester must cancel the order and submit a new one after modifying the default location on the ordering account.

Legal Requirements Mapping

When an order is submitted through HireRight directly, the requester must check the following checkbox: I have read and complied with the Legal Requirements for requesting a background check. 

Providing this certification is an FCRA compliance requirement that is needed of both orders submitted through HireRight directly as well as orders submitted by the API/Integration.

If the integration is using 2-Steps workflow (Fallbacks: GenerateWebLink, ManualSubmit, or InviteRequstor), this is not required as the consent will be collected in HireRight, while completing the request submission.

However, if the integration is using 1-Step of Faceless workflows (Fallbacks: InviteApplicant or None), passing the following certification is required for each and every background check request submitted, otherwise, the request submission will fail:

"legalRequirements": {
    "backgorundCheckCertification": "We make the certifications described in https://ows01.hireright.com/legal_requirements.html."
}

Create Order Mapping Details

Go to Endpoint