Sign in

v1

latestOpenAPI 3.1.02026-07-243113441.2 MB
I-9 Verification

Create or update an employee's I-9 authorization

An employee's I-9 authorization stores information about an employee's authorization status, as well as signatures and other information required to complete the Form I-9 for employment eligibility verification.

If the version is supplied and the employee I-9 authorization exists, this endpoint acts as an update. Otherwise, it will create an employee I-9 authorization.

Validations on this endpoint are conditional:

  • document_type may be required, depending on authorization_status.
  • Valid formats for document_number vary, depending on document_type.
  • country is only allowed with document_type: 'foreign_passport'.
  • expiration_date is only allowed with authorization_status: 'alien'.

ℹ️ Unneeded information is automatically removed during updates.

If an update causes some formerly-required fields to be unneeded, the now-unneeded data will be removed automatically.

Example: Updating authorization_status from alien to citizen will cause any data in document_type, document_number, country, and expiration_date to be removed, since these fields are unused for authorization_status:'citizen'.

Detailed instructions for completing Form I-9 can be found at https://www.uscis.gov/sites/default/files/document/forms/i-9instr.pdf

Related guides

scope: i9_authorizations:write

put/v1/employees/{employee_id}/i9_authorization

Path parameters

employee_idstring required

The UUID of the employee

Headers

X-Gusto-API-Version'2026-06-15'

Determines the date-based API version associated with your API call. If none is provided, your application's minimum API version is used.

Request body

versionstring

The current version of the object. See the versioning guide for information on how to use this field. If supplied, this endpoint will update the existing I-9 authorization if it exists.

authorization_status'citizen' | 'noncitizen' | 'permanent_resident' | 'alien' required

The employee's authorization status.

  • citizen: A citizen is someone who was born in the United States or is a naturalized citizen living in the United States.
  • noncitizen: A noncitizen national is someone born in American Samoa, certain former citizens of the former Trust Territory of the Pacific Islands, and certain children of noncitizen nationals born abroad.
  • permanent_resident: A lawful permanent resident is someone who is not a US citizen and who resides under legally recognized and lawfully recorded permanent residence as an immigrant.
  • alien: Also referred to as a "noncitizen authorized to work". This includes anyone who is authorized to work in the United States but is not a US citizen, US national or lawful permanent resident.
document_type'uscis_alien_registration_number' | 'form_i94' | 'foreign_passport'

The type of document an employee holds, based on their authorization status.

  • This is unused for authorization status citizen or noncitizen.
  • If the authorization status is permanent_resident, this must be uscis_alien_registration_number.
  • If the authorization status is alien, this is required and may be any of the valid values.
document_numberstring

The document number. Formatting depends on the employee's document type.

  • For document_type:'uscis_alien_registration_number', this must be a USCIS Number/A-Number, which is 7 to 9 digits.
  • For document_type:'form_i94', this must be a Form I-94 Admission Number, which is 11 digits.
  • For document_type:'foreign_passport', this must be the passport number.

This is required when the document type is present.

countrystring

The document's country of issuance.

This is required when the document type is foreign_passport.

expiration_datestring

The document's expiration date.

This may only be used when the authorization status is alien.

Response

Success

uuidstring required

The UUID of the I-9 authorization

form_uuidstring nullable

The UUID of the Form associated with this I-9 authorization. Use this with "Employee Forms" API endpoints.

versionstring required

The current version of the object. See the versioning guide for information on how to use this field.

authorization_status'citizen' | 'noncitizen' | 'permanent_resident' | 'alien' required

The employee's authorization status

document_type'uscis_alien_registration_number' | 'form_i94' | 'foreign_passport' nullable

The document's document type

has_document_numberboolean nullable

Whether or not a document_number exists for this document.

expiration_datestring nullable

The document's expiration date

countrystring nullable

The document's country of issuance

employer_signedboolean required

Whether the employer has signed the Form I-9

employee_signedboolean required

Whether the employee has signed the Form I-9

additional_infostring nullable

Any additional notes

alt_procedureboolean nullable

Whether an alternative procedure authorized by DHS to examine documents was used