I-9 employment verification

Employers must handle I-9 Employment Eligibility Verification carefully to ensure compliance with federal regulations.

This process involves both the employee and employer completing specific sections of the Form I-9 and verifying supporting documents, ensuring that every employee hired in the US is authorized to live and work in the US.

While this process can be done manually, outside of a partner’s payroll application, this functionality reduces the manual overhead and helps employers remain compliant.

1. Create an employee and invite them to self-onboard

Employee self-onboarding is required because I-9 verification requires the employee to sign the form. See the Onboard a W2 Employee guide for more details. If an employer onboards an employee, the employer and employee will have to to complete Form I-9 manually.

bash

curl --request POST \
     --url https://api.gusto-demo.com/v1/companies/{{company_uuid}}/employees \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {{access_token}}' \
     --header 'content-type: application/json' \
     --data '
{
  "first_name": "Fitchner",
  "middle_initial": "A",
  "last_name": "Barca",
  "date_of_birth": "1970-01-01",
  "email": "[email protected]",
  "self_onboarding": true
}
'

2. Update an employee’s onboarding documents configuration

You can indicate whether an employee is required to complete an I-9 on a per-employee basis. This is done via a PUT request to the Update an employee's onboarding documents config endpoint.

bash

curl --request PUT \
     --url https://api.gusto-demo.com/v1/employees/{{employee_uuid}}/onboarding_documents_config \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{"i9_document": true}'

There is a new field on the employee object onboarding_documents_config: { i9_document: true/false } to indicate this choice.

bash

{
    "uuid": "32015fb9-7a3b-4e91-abc6-f4007f9154c0",
    "first_name": "Fitchner",
    "middle_initial": "A",
    "last_name": "Barca",
    "email": "[email protected]",
    "company_uuid": "23acf457-d2c9-4136-99f0-c5618569616f",
    "manager_uuid": null,
    "version": "a7fb2921b0dc044c2a769e8e8f8da80f",
    "current_employment_status": null,
    "onboarding_status": "self_onboarding_pending_invite",
    "preferred_first_name": null,
    "department_uuid": null,
    "payment_method": "Check",
    "department": null,
    "terminated": false,
    "two_percent_shareholder": null,
    "onboarded": false,
    "historical": false,
    "has_ssn": true,
    "onboarding_documents_config": {
        "uuid": "9d7f3c7a-1015-45a8-92a2-8872975023e4",
        "i9_document": true
    },

3. Employee fills out I-9 info in the self-onboarding flow

Create an I-9 authorization

A PUT request to the Create or update an employee's I-9 authorization endpoint creates an I-9 authorization for the employee, collecting the I-9 info required in Section 1 of the Form I-9.

When creating an I-9 authorization record, validations are conditional based on the authorization_status you select.

• citizen or noncitizen:

  • No extra data is required or allowed

• permanent_resident:

  • document_type must be uscis_alien_registration_number
  • document_number must be a USCIS number, in the format ‘A000000000’

• alien:

  • document_type may be:

    • uscis_alien_registration_number
      • with document_number following the format described above.

  • form_i94

    • with document_number in the format ‘000000000 A0’

  • foreign_passport

    • document_number is required
    • country is required
    • expiration_date is optional. NOTE: an expiration date in the past is allowed.

bash

curl --request PUT \
     --url https://api.gusto-demo.com/v1/employees/{{employee_uuid}}/i9_authorization \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {{access_toke}}n' \
     --header 'content-type: application/json' \
     --data '
{
  "authorization_status": "alien",
  "document_type": "uscis_alien_registration_number",
  "document_number": "A000000000",
  "country": "Panama",
  "expiration_date": "2026-12-31"
}
'

Submitting unnecessary fields when creating an I-9 authorization record will result in a validation error.

Example: submitting a document_type when using "authorization_status": "citizen"

• Validation errors will report that document_type is not used for this authorization status.

Update an I-9 authorization

A PUT request can be made to the same endpoint to update an I-9 authorization with the addition of the version field. Updates are allowed as long as the employee has not yet signed their Form I-9.

bash

curl --request PUT \
     --url https://api.gusto-demo.com/v1/employees/employee_uuid/i9_authorization \
     --header 'accept: application/json' \
     --header 'authorization: Bearer access_token' \
     --header 'content-type: application/json' \
     --data '
{
  "authorization_status": "alien",
  "document_type": "uscis_alien_registration_number",
  "document_number": "A000000000",
  "country": "Panama",
  "expiration_date": "2026-12-31",
  "version": "52b7c567242cb7452e89ba2bc02cb476"
}
'

Updating an authorization_status that requires extra fields to an authorization_status that does not require those fields will automatically remove the unnecessary data.

This is to avoid generating needless validation errors about unnecessary data.

Example: When updating from permanent_resident (which requires document_type and document_number) to citizen (which does not use either of these fields)

• document_type and document_number are automatically removed from the existing database record.
• document_type and document_number included in any updates are ignored.

Get an I-9 authorization

Make a GET request to the Get an employee’s I-9 authorization endpoint to fetch the employee’s I-9 authorization.

bash

curl --request GET \
     --url https://api.gusto-demo.com/v1/employees/{{employee_uui}}/i9_authorization \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {{access_token}}'

4. Employee signs Form I-9 in the self-onboarding flow

Make a PUT request to the Sign an employee form endpoint to sign the Form I-9 that gets generated, which can be fetched from the Get all employee forms endpoint or the form_uuid field of the I-9 authorization. This fills out the signature information in Section 1 of the form and the optional Preparer and/or Translator Certification information.

bash

curl --request PUT \
     --url https://api.gusto-demo.com/v1/employees/{{employee_uuid}}/forms/form_uuid/sign \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {{access_token}}' \
     --header 'content-type: application/json' \
     --data '
{
  "agree": true,
  "signature_text": "Fitchner Barca",
  "signed_by_ip_address": "192.168.0.1"
}
'

Form I-9s accept additional input fields for up to 4 preparers/translators. These are people who assisted the employee in completing the Form I-9. Translator/preparer information is optional. If a translator is used, all basic information about that translator is required. Only Form I-9s will have these optional preparer/translator fields when signing.

After signing the Form I-9, the Update an I-9 authorization endpoint will reject subsequent updates.

5. Employer completes onboarding for the employee

Complete onboarding for the employee, after reviewing and verifying all the information the employee submitted. See the Onboard a W2 Employee guide for more details. The employee must be fully onboarded in order to proceed to the following steps.

6. Employer verifies I-9 documents

Within three business days of the employee’s start date, the employer must review the employee’s I-9 documents and fill out the document details in Section 2 of the form. This can be done using the following endpoints.

Show I-9 evidence document options

Call the Get an employee's I-9 verification documents endpoint to list the various documents an employee can provide to prove their status. This endpoint can be used to build a UI allowing the employer to indicate which documents the employee is providing.

bash

curl --request GET \
     --url https://api.gusto-demo.com/v1/employees/{{employee_uuid}}/i9_authorization/document_options \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {{access_token}}'

Create/update I-9 evidence documents

A PUT request to the Create an employee's I-9 authorization verification documentsendpoint can be used to bulk create I-9 evidence documents for an employee. Make a GET request to the Get an employee's I-9 verification document options endpoint to get the possible document types and titles, which can vary depending on the employee’s authorization status. API responses do not include document numbers to minimize exposure of private employee data.

An employee must provide EITHER (See USCIS website for more information)

• 1 document from “List A”
• 1 document from “List B” AND 1 document from “List C”.
• 1 document from “List A1” AND 1 document from “List A2” AND 1 document from “List A3”. if the employee has an authorization status of alien (non-citizen authorized to work)

bash

curl --request PUT \
     --url https://api.gusto-demo.com/v1/employees/{{employee_uuid}}/i9_authorization/documents \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {{access_token}}' \
     --header 'content-type: application/json' \
     --data '
{
  "documents": [
    {
      "document_type": "us_passport",
      "document_title": "US Passport",
      "document_number": "F12345678",
      "expiration_date": "2026-01-01",
      "issuing_authority": "USA"
    }
  ]
}
'

Every PUT call to this endpoint completely replaces any previously-created verification document records.

Remove I-9 documents

If needed, a request to Delete an employee's I-9 verification document endpoint can be used to remove an I-9 document using the UUID.

bash

curl --request DELETE \
     --url https://api.gusto-demo.com/v1/employees/{{employee_uuid}}/i9_authorization/documents/{{document_uuid}} \
     --header 'authorization: Bearer {{access_token}}'

7. Employer signs Form I-9

A PUT request to the Employer sign an employee's Form I-9endpoint can be made by the employer to sign the I-9 document. The previous steps must be completed in order to successfully sign the form.

bash

curl --request PUT \
     --url https://api.gusto-demo.com/v1/employees/{{employee_uuid}}/i9_authorization/employer_sign \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {{access_token}}' \
     --header 'content-type: application/json' \
     --data '
{
  "agree": true,
  "signature_text": "Victra Julii",
  "signer_title": "Owner",
  "signed_by_ip_address": "192.168.0.1"
}
'

8. Get the I-9 PDF

Make a GET request to the Get the employee form pdf endpoint to view the completed I-9 form. The PDF should be completed and include both employee and employer signatures.

bash

curl --request GET \
     --url https://api.gusto-demo.com/v1/employees/{{employee_uuid}}/forms/{{form_uuid}}/pdf \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {{access_token}}'

---

W2 employee forms

I-9 Verification Using Flows