Create or update an employee's I-9 authorization

put

https://api.gusto-demo.com/v1/employees/{employee_id}/i9_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

I-9 employment verification

scope: i9_authorizations:write

Path Params

employee_id

string

required

The UUID of the employee

Body Params

version

string

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

string

enum

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.

Allowed:

document_type

string

enum

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.

Allowed:

document_number

string

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.

country

string

The document's country of issuance.

This is required when the document type is foreign_passport.

expiration_date

string

The document's expiration date.

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

Headers

X-Gusto-API-Version

string

enum

Defaults to 2026-02-01

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

Allowed:

Responses

200Success

404Not Found The requested resource does not exist. Make sure the provided UUID is valid.

422Unprocessable Entity This may happen when the body of your request contains errors such as invalid_attribute_value, or the request fails due to an invalid_operation. See the Errors Categories guide for more details.