Contractor documents

The contractor W-9 Form is a document, and can be accessed and generated through the Documents API. This API is only used for contractor W-9 documents.

Documents have attributes like pages and fields, unlike forms (for information on forms, consult Contractor forms).

Users can get a contractor’s documents, get an individual document, retrieve the PDF for a document, and sign a document.

1. Retrieve a document

Get all documents for a contractor

Retrieve a contractor’s documents using the GET /v1/contractors/{{contractor_uuid}}/documents endpoint.

Sample response

In this sample response, the document in the returned array is unsigned, as requires_signing is true and the pages and fields attributes are returned:

[  
  {  
    "uuid": "e83b3c20-dc4f-4382-bee3-b478fc42c68b",  
    "title": "Taxpayer Identification (Form W-9)",  
    "name": "taxpayer_identification_form_w_9",  
    "recipient_type": "Contractor",  
    "recipient_uuid": "f079c253-29e2-45e2-b384-2cc615c9c568",  
    "signed_at": "2024-09-03T16:39:22.000-07:00",  
    "description": "Form W-9, Request for Taxpayer Identification Number and Certification",  
    "requires_signing": true,  
    "draft": false,  
    "year": null,  
    "quarter": null,  
    "pages": [  
      {  
        "image_url": "http://app.gusto-dev.com:3000/assets/document_templates/20/unmapped_template/images/0.jpg",  
        "page_number": 0  
      },  
      {  
        "image_url": "http://app.gusto-dev.com:3000/assets/document_templates/20/unmapped_template/images/1.jpg",  
        "page_number": 1  
      }  
    ],  
    "fields": [  
      {  
        "key": "text1596141656513",  
        "value": null,  
        "x": 69,  
        "y": 94,  
        "width": 261,  
        "height": 13,  
        "page_number": 0,  
        "data_type": "text",  
        "required": true  
      },  
      {  
        "key": "optional_text1596141704672",  
        "value": null,  
        "x": 69,  
        "y": 118,  
        "width": 262,  
        "height": 13,  
        "page_number": 0,  
        "data_type": "text",  
        "required": false  
      }  
    ],  
  }  
]

📘
Use "pages" and "fields" for signing preparation
The pages and fields attributes are intended for signing preparation, and aren't returned for signed documented.
Example usage: a document’s pages can be rendered using with the image_urls, and the field values can be used to autofill certain fields on a signing form.

Get a specific document

Retrieve a specific document with the GET /v1/documents/{{document_uuid}} endpoint.

Sample response (signed document)

This sample response shows a signed document, as requires_signing is false and the pages and fields attributes are not returned:

{  
    "uuid": "e83b3c20-dc4f-4382-bee3-b478fc42c68b",  
    "title": "Taxpayer Identification (Form W-9)",  
    "name": "taxpayer_identification_form_w_9",  
    "recipient_type": "Contractor",  
    "recipient_uuid": "f079c253-29e2-45e2-b384-2cc615c9c568",  
    "signed_at": "2024-09-03T16:39:22.000-07:00",  
    "description": "Form W-9, Request for Taxpayer Identification Number and Certification",  
    "requires_signing": false,  
    "draft": false,  
    "year": null,  
    "quarter": null  
  }

2. Sign a document

Sign a contractor W-9 form using the PUT /v1/documents/{{document_uuid}}/sign endpoint, and doing the following:

Passing in values for the "name" and "signature_text" keys.
Agree to sign the form electronically with "agree": true
Pass in the signatory's valid IP address with signed_by_ip_address

Sample request

curl --request PUT \
     --url https://api.gusto-demo.com/v1/documents/document_uuid/sign \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "agree": true,
  "signed_by_ip_address": "1.1.1.1",
  "fields": [
    {
      "key": "name",
      "value": "Bob"
    },
    {
      "key": "signature_text",
      "value": "Bob Signature"
    }
  ]
}
'

const fetch = require('node-fetch');

const url = 'https://api.gusto-demo.com/v1/contractors/{contractor_uuid}/bank_accounts';
const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer <<COMPANY_API_TOKEN>>'
  },
  body: JSON.stringify({
    name: 'BoA Checking Account',
    routing_number: '266905059',
    account_number: '5809431207',
    account_type: 'Checking'
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

Sample response

In the response, signed_at will now include the timestamp of when the document was signed, and the requires_signing attribute will be false. The response will no longer include pages and fields.

{  
    "uuid": "e83b3c20-dc4f-4382-bee3-b478fc42c68b",  
    "title": "Taxpayer Identification (Form W-9)",  
    "name": "taxpayer_identification_form_w_9",  
    "recipient_type": "Contractor",  
    "recipient_uuid": "f079c253-29e2-45e2-b384-2cc615c9c568",  
    "signed_at": "2024-09-03T16:39:22.000-07:00",  
    "description": "Form W-9, Request for Taxpayer Identification Number and Certification",  
    "requires_signing": false,  
    "draft": false,  
    "year": null,  
    "quarter": null  
  }

3. Get the PDF for a document

Retrieve a document’s pdf with the GET /v1/documents/{{document_uuid}}/pdf.

The PDF will be blank for unsigned documents and contain field data for signed documents.

{  
  "uuid": "e83b3c20-dc4f-4382-bee3-b478fc42c68b",  
  "document_url": "<https://app.gusto-demo.com/assets/personal_documents/23/original.pdf?1724367941">  
}

Contractor Documents Flow

1. Create a contractor via API call:

curl --location --request POST https://api.gusto-demo.com/v1/companies/{company_id}/contractors  
--header 'Authorization: Bearer {{access_token}}'  
--header 'Content-Type: application/json'  
--data-raw 
'{  
  "self_onboarding": false,  
  "first_name": "Erlich",  
  "last_name": "Bachman",  
  "start_date": "2024-09-06"  
}'

const fetch = require('node-fetch');

const url = 'https://api.gusto-demo.com/v1/contractors/{contractor_uuid}/bank_accounts';
const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer <<COMPANY_API_TOKEN>>'
  },
  body: JSON.stringify({
    name: 'BoA Checking Account',
    routing_number: '266905059',
    account_number: '5809431207',
    account_type: 'Checking'
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

2. Generate the Contractor Documents Flow

Then, generate a contractor_documents flow with using the POST /v1/companies/{company_uuid}/flows endpoint, setting flow_type to contractor_documents and entity_type to Contractor.

curl --location --request POST <https://api.gusto-demo.com/v1/companies/{company_uuid}/flows>  
--header 'Authorization: Bearer {{access_token}}'  
--header 'Content-Type: application/json'  
--data-raw '{  
  "flow_type": "contractor_documents",  
  "entity_type": "Contractor",  
  "entity_uuid": {{contractor_uuid}}  
}'

const fetch = require('node-fetch');

const url = 'https://api.gusto-demo.com/v1/contractors/{contractor_uuid}/bank_accounts';
const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer <<COMPANY_API_TOKEN>>'
  },
  body: JSON.stringify({
    name: 'BoA Checking Account',
    routing_number: '266905059',
    account_number: '5809431207',
    account_type: 'Checking'
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

Flow behavior (Employer view)

1. Locate the contractor document

Clicking on the title link will take you to a page where you can view/download the document. If you don’t want to sign the document through the flow, you can print out the document here and fill it out physically.

2. Sign document

To sign the page, either hit the Sign button from the view/download page, or hit Sign document from the title page.

Fill out the required fields (e.g. Name and Signature for W-9 Forms), check the I agree to sign electronically checkbox, and hit Sign.

3. View/download signed document

After signing, you can hit the title link to view/download the document.