--- title: "Create or update an employee's I-9 authorization" method: PUT path: "/v1/employees/{employee_id}/i9_authorization" tags: ["I-9 Verification"] --- # Create or update an employee's I-9 authorization `PUT /v1/employees/{employee_id}/i9_authorization` ## Request - Base URL: `https://api.gusto-demo.com` - URL: `https://api.gusto-demo.com/v1/employees/{employee_id}/i9_authorization` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) 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](doc:i-9-employment-verification) scope: `i9_authorizations:write` ## Path parameters - `employee_id` string, required ## Headers - `X-Gusto-API-Version` '2026-06-15' ## Request body - I9AuthorizationRequestBody: Request body for creating or updating an employee's I-9 authorization. - `version` string: The current version of the object. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) 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_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`. ## Response `200` Success - I9Authorization: An employee's I-9 authorization - `uuid` string, required: The UUID of the I-9 authorization - `form_uuid` string, nullable: The UUID of the Form associated with this I-9 authorization. Use this with "Employee Forms" API endpoints. - `version` string, required: The current version of the object. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) 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_number` boolean, nullable: Whether or not a `document_number` exists for this document. - `expiration_date` string, nullable: The document's expiration date - `country` string, nullable: The document's country of issuance - `employer_signed` boolean, required: Whether the employer has signed the Form I-9 - `employee_signed` boolean, required: Whether the employee has signed the Form I-9 - `additional_info` string, nullable: Any additional notes - `alt_procedure` boolean, nullable: Whether an alternative procedure authorized by DHS to examine documents was used ## Other responses - `404`: Not Found The requested resource does not exist. Make sure the provided UUID is valid. - `422`: Unprocessable 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](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details. --- [API](https://skmtc.dev/gusto/apis/gusto-api.md) - [All operations](https://skmtc.dev/gusto/apis/gusto-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gusto/apis/gusto-api/revisions/f98575fa2a5e?raw)