I-9 Management

I-9 Creation & Section 1 Worksheet Access

Overview

Initiating a new I-9 request is facilitated through the Create I-9 operation.

This operation creates a new I-9 and returns the associated I-9 Form ID to be used in the subsequent API calls to HireRight. 

It is important to capture and store the I-9 Form ID that is returned, as this I-9 Form ID will be required in any additional implement API operations such as accessing the Section 1 worksheet, Section 2 worksheet, and/or Completed I-9 Form via the API.

Two workflow options are available as part of the I-9 Creation API call to determine how the Candidate will access the Section 1 worksheet:

  • 'InviteEmployee' Workflow: The employee receives an email from HireRight with access to the Section 1 worksheet.

  • 'Employee' Workflow: The employee accesses the Section 1 worksheet directly from the client's system (such as an onboarding portal).

    • No email is sent

    • Client must make an additional API call to retrieve a weblink for the Section 1 worksheet.

The Create I-9 request also includes an additional parameter to specify the type of I-9 Form to be created, either a Traditional I-9 or Remote I-9.

InviteEmployee Workflow

1) A new I-9 request is initiated via the API with the attribute fallbackModel=‘InviteEmployee’ 

{
   "fallbackModel": "InviteEmployee",
   ...
}

2) A successful response will return a unique I-9 Form ID, generated by HireRight, which must be captured by the client

  • This Form ID is subsequently used with any other API operations to reference that specific I-9

{
    "id" : "FRM-031524-334376P",
    "status" : "Sent to Employee",
    "links" : [
    {
       "href" : "https://stage-apis.hireright.com/connect/I-9/FRM-031524-334376P/employee",
       "rel" : "I-9 form link for employee",
       "type" : "GET"
    },
    {
       "href" : "https://stage-apis.hireright.com/connect/I-9/FRM-031524-334376P/employer",
       "rel" : "I-9 form link for employer",
       "type" : "GET"
   },
   {
       "href" : "https://stage-apis.hireright.com/connect/I-9/FRM-031524-334376P/weblink",
       "rel" : "I-9 form link",
       "type" : "GET"
   },
   {
       "href" : "https://stage-apis.hireright.com/connect/I-9/FRM-031524-334376P",
       "rel" : "I-9 form",
       "type" : "GET"
   }.
   {
      "href" : "https://stage-apis.hireright.com/connect/I-9/FRM-031524-334376P/status",
      "rel" : "I-9 form status",
      "type" : "GET"
   }.
   {
      "href" : "https://stage-apis.hireright.com/connect/I-9/FRM-031524-334376P/documents",
      "rel" : "I-9 form supporting documentation",
      "type" : "GET"
   }
}

3) The employee receives an email from HireRight with access to the Section 1 worksheet

The Create I-9 worksheet request also includes an additional parameter to specify the type of I-9 Form to be created, either a Traditional I-9 or Remote I-9.

Invite Email to Section 1 Worksheet

4) The employee completes and e-signs the Section 1 worksheet
(Data provided by the API will be pre-populated in the various fields within the Section 1 worksheet)

Section 1 Worksheet

Employee Workflow

1) A new I-9 request is initiated via the API with the attribute fallbackModel=‘Employee’ 

{
   "fallbackModel": "Employee",
   ...
}

2) A success response will return unique I-9 Form ID, generated by HireRight, which must be captured by the client.

  • This Form ID is subsequently used with any other API operations to reference that specific I-9

3) A second API call is utilized to access the Section 1 worksheet via the Get I-9 Employee Web Link operation

  • A success response returns a one-time use URL that allows for SSO (Single Sign-On) access and is recommended to be opened automatically (webhook)

  • The API request must include the matching employee’s email address as provided in the I-9 creation API request

4) The employee will access the Section 1 worksheet directly from the client's system (such as an onboarding portal) via the one-time use URL

5) The employee completes and e-signs the Section 1 worksheet
(Data provided by the API will be pre-populated in the various fields within the Section 1 worksheet)

Traditional I-9 vs. Remote I-9

The I-9 API request submission should indicate if the I-9 is a Traditional I-9 or a Remote I-9.

Traditional I-9:

  • Section 2 worksheet is completed by the customer’s section 2 signer
    (This is the default option and must be supported)

  • No additional order attribute is required to initiate this I-9 type

  • Required fields:
    (If any of the fields below are missing per I-9 Type, the I-9 Creation request will be rejected by HireRight)

    • Employee First Name

    • Employee Last Name

    • Employee Email

Required fields for Traditional I-9 Sample:

{
    "candidate": {
      "candidateProfile": {
        "personalData": {
          "personName": {
            "givenName": "John",
            "familyName": [
              {
                "primary": "true",
                "value": "Smith"
              }
            ]
          },
          "contactMethod": {
            "email": "jsmith@internet.com",
          }
        }
      }
   }
}

Remote I-9:

  • Section 2 worksheet is completed by a 3rd party vendor
    (It is recommended to support this option as well)

  • remoteOrder=“true” attribute must be included in the I-9 Creation request

    {
       "fallbackModel": "Employee" / "InviteEmployee",
       "remoteOrder": "true",
       ...
    }

  • Required fields:
    (If any of the fields below are missing per I-9 Type, the I-9 Creation request will be rejected by HireRight)

    • Employee First Name

    • Employee Last Name

    • Employee Email

    • Employee Phone Number

    • Employee Start Date
      (Important: Employee Start Date must be at least 5 business days after the current date.)

    • Legal Certification Text
      (Text must be: "We certify that the named individual has been made and accepted a job offer.")

Required fields for Remote I-9 Sample:

{
   "remoteOrder": "true",
   "legalRequirements": {
      "I9OrderCertify": "We certify that the named individual has been made and accepted a job offer."
   },
   "candidate": {
      "candidateProfile": {
        "personalData": {
          "personName": {
            "givenName": "John",
            "familyName": [
              {
                "primary": "true",
                "value": "Smith"
              }
            ]
          },
          "contactMethod": {
            "email": "jsmith@internet.com",
            "telephone": "123-456-7890",
          }
      }
      "i9Details": {
           "dateHired": "2024-04-25"
      }
    }
  }
}

For additional information, and samples, of all the fields supported by the Create I-9 worksheet operation please see the Data Mapping section below. 

Section 2 Worksheet Access

Overview

For Traditional I-9:

  • Section 2 Signer accesses and completes the Section 2 worksheet

  • Multiple options to access Section 2 worksheet:

    • The HireRight recommended approach is directly through the client's system via the Get I-9 Employer Web Link operation once the I-9 Form is in a Pending Employer status

      • API Operation returns a one-time use URL that allows for SSO (Single Sign-On) access and is recommended to be opened automatically (webhook)

      • API call must include the email address of the user attempting to access the Section 2 worksheet for authentication purposes

    • Via an email notification from HireRight (not SSO)

    • By login directly to HireRight (not SSO)

For Remote I-9:

  • Section 2 worksheet is submitted by a 3rd party vendor

  • Client reviews and approves Section 2 worksheet

Section 2 (Traditional I-9)

1) The Section 2 signer completes and e-signs the Section 2 worksheet
    (Data provided via the integration will be pre-populated in the various fields within the Section 2 worksheet)

Section 2 Worksheet

2) Once the forms are submitted, the I-9 form status as well as the E-Verify case status (if applicable) are displayed to the user and provided as a status update via the API

Section 2 Completion Confirmation Screen

Status Updates

Overview

  • Real time status PUSH updates are recommended to be supported:

    • The client's endpoint for status pushes is provided in the I-9 creation API call (in the ‘statusUpdateUrls' attribute)

    • HireRight pushes status updates real time to the client's endpoint as the I-9 form progresses

    • Automatic retries are built in for failed status pushes

  • There are 2 I-9 relevant statuses that should be displayed within the client's system

    • I-9 Status: The status of the I-9 form

    • E-Verify Status: The E-verify status when applicable

      • After the I-9 Form is completed, if applicable, HireRight will automatically trigger the E-Verify case and will return the corresponding E-Verify status

      • I-9 requests can include E-Verify or not, client's platform should account for both scenarios

  • Additional status information recommended to be displayed with the client's platform includes:

    • I-9 Form ID

    • I-9 Form Completion Time

    • I-9 Verification Time (relevant only if E-verify is included)

  • For additional information on the Status Update process please see the following link Status Updates.

I-9 Statuses

  • Sent to Employee: The I-9 request was initiated successfully.

  • Pending Employee: Section 1 is pending the employee to finish submission of the Section 1 worksheet.

  • Pending Employer: Section 2 is pending the employer to submit the Section 2 worksheet.

  • Pending Correction: Section 2 signer returned the I-9 to the candidate to update the Section 1 worksheet.

  • Pending Remote Agent: Section 2 is pending the authorized 3rd party vendor to submit the Section 2 worksheet (relevant only for I-9 Remote Service)

  • Complete: Section 2 worksheet has been signed.

  • Deleted: I-9 (regular or remote) has been deleted.

E-Verify Statuses

E-Verify Final Statuses:

  • Employment Authorized: A final result indicating that the employee is authorized to work in the United States.

  • SSA Employment Authorized: Same as above.

  • DHS Employment Authorized: Same as above.

  • Final Non-Confirmation: A final result indicating that the employee's work eligibility has not been authorized.

  • SSA Final Non-Confirmation: Same as above.

  • DHS Final Non-Confirmation: Same as above.

  • DHS No Show: The employee did not contact DHS within the required eight federal government workdays.

E-Verify Temporary Statuses:

  • In Progress: Temporary status used when an E-Verify integration has been queried but no Verification Status received yet.

  • Tentative Non-Confirmation: Information does not initially match SSA or DHS records.

  • SSA Tentative Non-Confirmation: Same as above.

  • DHS Tentative Non-Confirmation: Same as above.

  • Tentative Non-Confirmation - Other: Tentative non-confirmation closing case statuses

  • Tentative Non-Confirmation - Asked by DHS: Same as above.

  • Tentative Non-Confirmation - Asked by SSA: Same as above.

  • Tentative Non-Confirmation - Invalid Query: Same as above.

  • Tentative Non-Confirmation - Unauthorized/Terminated: Same as above.

  • Info Review Required: Review of the employee's info is required.

  • SSA Info Review Required: Same as above.

  • DHS Info Review Required: Same as above.

  • Case In Continuance: The employee has visited an SSA field office, or contacted DHS, but more time is needed to determine a final case result.

  • SSA Case in Continuance: Same as above.

  • DHS Case in Continuance: Same as above.

  • Scan And Upload: The case failed photo match and requires photos to be uploaded.

  • Photo Matching Required: If the photo displayed on the E-Verify screen does not match the photo on the employee's document.

  • Institute Additional Verification: Allow more time for DHS/SSA to provide the employment eligibility status.

  • Draft: The case has been created and not yet submitted.

  • Duplicate Case: E-Verify has identified duplicate cases that have been created for the company with the same social security number within the last 30 days.

Sample

Below is a partial snapshot from an I-9 Status JSON payload:

{
   "id" : "FRM-031524-334376P,
   ...
   "orderStatus" : {
      "status" : "Completed", 
      "dateInitiated": "2023-06-08T22:58:00", 
      "dateReceived": "2023-06-08T22:58:00",
      "dateCompleted": "2023-06-08T22:59:05",
      "dateModified": "2023-06-08T23:59:05",
      "timestamp": "2023-06-09T01:39:54+03:00",
   },
   "i9Status": {
      "status": "Completed",
      "formCompletionDate": "2023-06-09T22:58:00",      
      "verificationDate": "2023-06-08T22:58:00",
      "verificationStatus": "Employment Authorized",
      "formReverificationDate": "2024-06-08T22:58:00",
      "reverificationDeadline": "2024-07-08T22:58:00"
   },
   ...
}

Mapping recommendations:

  • Ensure to map i9Status.status and i9Status.verificationStatus if available (it will be available only if the I-9 Form is completed and the I-9 includes E-Verify)

  • Highly recommended to also map orderStatus.dateInitiated and all other fields under the i9Status node if available.: formCompletionDate, verificationDate, formReverificationDate, reverificationDeadline

Completed I-9 Form Access & Retrieval

Overview

  • The HireRight Connect API supports multiple options to access the completed I-9 form:

    • The recommended approach is directly through the client's system via the Get I-9 Employer Web Link operation (same operation as the Section 2 worksheet access) 

      • API Operation returns a one-time use URL that allows for SSO (Single Sign-On) access and is recommended to be opened automatically (webhook)

      • API call must include the email address of the user attempting to access the I-9 form for authentication purposes

    • Via an email notification from HireRight (not SSO)

    • By login directly to HireRight (not SSO)

  • Access is the same for both Traditional I-9 and Remote I-9

  • The I-9 form allows the user to perform additional actions, such as:

    • Review the completed I-9 form

    • Access Audit Trail, Change Tracker, Supporting Documents and other info

    • Initiate Section 3 if needed

    • Download the I-9 PDF

    • Update Start/Termination Dates

    • Access the HireRight I-9 Dashboard

I-9 Form Screenshots

Completed I-9 Form:

Access to the HireRight I-9 Dashboard is provided by the user clicking the HireRight I-9 Dashboard button on the I-9 Form screen:

Completed I-9 Form Retrieval

  • The HireRight Connect API offers multiple ways for the completed I-9 form to be retrieved for local I-9 Form storage, if required, including:

    • Completed I-9 Form PDF

      • The I-9 Form PDF can be retrieved via 2 API operations:

        • Option 1: Request a base64 encoded PDF file of the I-9 Form via the Get I-9 Form operation

        • Option 2: Request a one-time use URL that allows for SSO (Single Sign-On) access to the I-9 Form PDF via the Get I-9 Web Link operation

    • I-9 Supporting Documents

  • These options require the client to sign additional paperwork with HireRight, once signed, then the relevant options can be enabled within the integration by HireRight

Data Mapping

Data Mapping Importance

  • Traditional I-9 and Remote I-9 both require specific fields to be provided to successfully initiate a new I-9 worksheet via the API, please see the Traditional I-9 vs Remote I-9 section for these required fields

  • Although the fields called out above are the minimally required fields, HireRight highly recommends mapping many fields as possible to ensure best experience for the end user by eliminating duplicate data entry between platforms
    (Example of such fields are the Employee address fields, SSN, DOB, citizenship status & Section 2 related data)

  • Fields mapped over will be pre-populated on the various I-9 worksheets which will reduce re-entry of data and making the process easier and faster for the Section 1 and the Section 2 signer

  • See additional details for all the fields supported in the Create I-9 Mapping Details section

Flex Fields Mapping

  • An I-9 Form can be associated with client-specific metadata, known as Flex Fields

  • Flex Fields are available to pass information that a client finds beneficial in a downstream process such as showing additional information on the I-9 Form, associated with an invoice, and other scenarios

  • It is recommended to support mapping common Flex Fields by default

    • Examples of such Flex Fields can be:
      I-9 Business Unit, I-9 Completion Location, I-9 Worksite, Employee Number, etc.

    • If possible, it is also recommended to allow configurations of mapping additional Flex Fields per client upon need (known as Custom Flex Fields)

Sample:

"flexFields": [
   {
   "name": "I-9 Business Unit",
   "value": "Finance"
   },
   {
   "name": "Employee Number,",
   "value": "C4433268"
   }
],

Hiring Manager Mapping

  • The Create I-9 operation also supports the ability to specify, map, a specific Section 2 Signer also know as the Hiring Manager

  • For Traditional I-9 requests, if this info is mapped and the relevant email notification is enabled with HireRight, the Section 2 Signer will receive an email from HireRight with Section 2 worksheet access info once the employee submits the Section 1 worksheet

  • The benefit of this approach is the Section 2 Signer does not need to be an actual user on the HireRight Account, which is preferred by customers with high turn over or if recruiters/hiring managers do not need access to HireRight beyond singing the Section 2 worksheet

  • The recommended approach is to support both mapping a Hiring Manager during the Create I-9 Worksheet operation as well as providing access to the Section 2 worksheet through the partner’s system via the API
    (By supporting both options, the Hiring Manager functionality can be enabled or disabled at a HireRight Account by configuring the relevant email notification)

Sample:

{
   ...
   "candidate": {
       ...
       "resume": {
           "hiringManager": {
               "givenName": "David",
               "familyName": "Wallace",
               "email": "David.Wallace@dunderMifflin.com" 
            } 
        } 
   }
}

Create I-9 Mapping Details

General Info

Multiple Account Support

If a client has multiple HireRight Accounts for their I-9 Forms, the following options are available to support routing the I-9 Form to the appropriate account:

  1. Option 1: The recommended approach is to send the specific HireRight Account Code in each Create I-9 API call

    • The end user would select the appropriate HireRight account within the partner platform prior to the Create I-9 API call

    • Once the I-9 Form is to be created, the partner platform will include the customer selected HireRight Account code in the hr-company-login header parameter in the Create I-9 Worksheet operation

  2. Option 2: Only support sending the HireRight Parent Account Code as the hr-company-login header parameter in each Create I-9 API call

    • In this case, additional configuration must be performed within the HireRight platform to route I-9 Forms to the appropriate HireRight account based on unique Flex Field values

    • The I-9 Form is routed according to a Flex Field that is provided in the Create I-9 API call that uniquely distinguishes between the accounts within HireRight
      For example, if there are three accounts within HireRight for business locations within California, Florida, and New York, it is possible to send over a Business Location Flex Field in each request and HireRight will configure the routing accordingly.

      • California = Account 1

      • Florida = Account 2

      • New York = Account 3

Duplicate Detection

If an employee has multiple I-9 forms, a warning will appear on the Section 2 worksheet, displaying any previous I-9s detected as duplicates.

The Section 2 Signer can review the duplicates and then decide if to delete the current I-9 request or to continue with Section 2 submission.

Error Handling

  • When an error occurs, it is recommended to display the error description to the user “as is” for aiding in troubleshooting, including the following related data points as available:

    • User Reference Id

    • Company Login

    • Timestamp of the error

    • HireRight Transaction Id (if available)

  • For additional information please see Error Handling

Go to Endpoint