v1

latestOpenAPI 3.1.02026-07-243113441.2 MB

Employee Forms

Sign an employee form

Sign an employee form.

The optional preparer attributes are only valid for I-9 form. When a preparer is used, the first name, last name, street address, city, state, and zip for that preparer are all required.

scope: employee_forms:sign

put/v1/employees/{employee_id}/forms/{form_id}/sign

Path parameters

employee_idstring required

The UUID of the employee

form_idstring required

The UUID of the form

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.

x-gusto-client-ipstring

Optional header to supply the IP address. This can be used to supply the IP address for signature endpoints instead of the signed_by_ip_address parameter.

Request body

signature_textstring required

The signature

agreeboolean required

Whether you agree to sign electronically

signed_by_ip_addressstring

The IP address of the signatory who signed the form. Both IPv4 AND IPv6 are supported. You must provide the IP address with either this parameter OR you can leave out this parameter and set the IP address in the request header using the x-gusto-client-ip header instead.

preparerboolean

Whether there is a preparer

preparer_first_namestring

preparer_last_namestring

preparer_street_1string

preparer_street_2string

preparer_citystring

preparer_statestring

preparer_zipstring

preparer_agreestring

Whether preparer agrees to sign electronically

preparer2boolean

Whether there is a 2nd preparer

preparer2_first_namestring

preparer2_last_namestring

preparer2_street_1string

preparer2_street_2string

preparer2_citystring

preparer2_statestring

preparer2_zipstring

preparer2_agreestring

Whether 2nd preparer agrees to sign electronically

preparer3boolean

Whether there is a 3rd preparer

preparer3_first_namestring

preparer3_last_namestring

preparer3_street_1string

preparer3_street_2string

preparer3_citystring

preparer3_statestring

preparer3_zipstring

preparer3_agreestring

Whether 3rd preparer agrees to sign electronically

preparer4boolean

Whether there is a 4th preparer

preparer4_first_namestring

preparer4_last_namestring

preparer4_street_1string

preparer4_street_2string

preparer4_citystring

preparer4_statestring

preparer4_zipstring

preparer4_agreestring

Whether 4th preparer agrees to sign electronically

Response

Success

uuidstring required

The UUID of the form

employee_uuidstring

The UUID of the employee to which the form belongs, if applicable.

namestring

The type identifier of the form

titlestring

The title of the form

descriptionstring

The description of the form

draftboolean

If the form is in a draft state. E.g. End of year tax forms may be provided in a draft state prior to being finalized.

yearinteger nullable

The year of this form. For some forms, e.g. tax forms, this is the year which the form represents. A W2 for January - December 2022 would be delivered in January 2023 and have a year value of 2022. This value is nullable and will not be present on all forms.

quarterinteger nullable

The quarter of this form. For some forms, e.g. tax forms, this is the calendar quarter which this form represents. An Employer's Quarterly Federal Tax Return (Form 941) for April, May, June 2022 would have a quarter value of 2 (and a year value of 2022). This value is nullable and will not be present on all forms.

requires_signingboolean

A boolean flag that indicates whether the form needs signing or not. Note that this value will change after the form is signed.

document_content_typestring nullable

The content type of the associated document. Most forms are PDFs with a content type of application/pdf. Some tax file packages will be zip files (containing PDFs) with a content type of application/zip. This attribute will be null when the document has not been prepared.