---
title: "Sign a contractor document"
method: PUT
path: "/v1/documents/{document_uuid}/sign"
tags: ["Contractor Documents"]
---

# Sign a contractor document

`PUT /v1/documents/{document_uuid}/sign`

Sign a contractor document.

scope: `contractor_documents:write`

## Path parameters

- `document_uuid` string, required

## Headers

- `X-Gusto-API-Version` '2026-06-15'
- `x-gusto-client-ip` string

## Request body

- object
  - `fields` object[], required — List of fields and the values they will be set to.
    - `key` string — Unique identifier of the field
    - `value` string — Value for the field
  - `agree` boolean, required — Whether you agree to sign electronically
  - `signed_by_ip_address` string — The IP address of the signatory who signed the form. 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.

## Response `200`

Example response

- DocumentSigned
  - `uuid` string — The UUID of the document
  - `title` string — The title of the document
  - `name` string — The type identifier of the document
  - `recipient_type` 'Company' | 'Employee' | 'Contractor' — The type of recipient associated with the document (will be `Contractor` for Contractor Documents)
  - `recipient_uuid` string — Unique identifier for the recipient associated with the document
  - `pages` object[] — List of the document's pages and associated image URLs.
    - `image_url` string — Image URL for the page
    - `page_number` integer — Page number
  - `fields` object[] — List of the document's fields and associated data. Values reflect the data provided at signing.
    - `key` string, nullable — Unique identifier of the field. May be null for custom fields that do not correspond to a known Gusto-managed key mapping.
    - `value` string, nullable — Value of the field
    - `x` integer, nullable — X-coordinate location of the field on the page. May be null when the field has no positioning information.
    - `y` integer, nullable — Y-coordinate location of the field on the page. May be null when the field has no positioning information.
    - `width` integer, nullable — Width of the field. May be null when the field has no positioning information.
    - `height` integer, nullable — Height of the field. May be null when the field has no positioning information.
    - `page_number` integer, nullable — Page number of the field. May be null when the field has no positioning information.
    - `data_type` string — The field's data type
    - `required` boolean — Whether the field is required
  - `signed_at` string, nullable — When the document was signed (will be `null` if unsigned)
  - `description` string — The description of the document
  - `requires_signing` boolean — A boolean flag that indicates whether the document needs signing or not. Note that this value will change after the document is signed.
  - `draft` boolean — If the document is in a draft state
  - `year` integer, nullable — The year of this document. This value is nullable and will not be present on all documents.
  - `quarter` integer, nullable — The quarter of this document. This value is nullable and will not be present on all documents.

## 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.net/gusto/apis/gusto-api.md) · [All operations](https://skmtc.net/gusto/apis/gusto-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gusto/gusto-api/revisions/826dfa57fb3b/schema)