GuidesAPI ReferenceChangelogAPI StatusAPI PolicyGusto Security
API Reference

Create or update an employee's I-9 authorization

put
https://api.gusto-demo.com/v1/employees//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

scope: i9_authorizations:write

Path Params
string
required

The UUID of the employee

Body Params

Request body for creating or updating an employee's I-9 authorization.

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.

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:
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:
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.

string

The document's country of issuance.

This is required when the document type is foreign_passport.

string

The document's expiration date.

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

Headers
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

Updated 26 days ago

Language
Credentials
Bearer
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 26 days ago