Contractor Documents

There are two types of contractor documentation supported by our APIs: forms and documents. Forms return 1099 forms. Documents have a more complex structure, with attributes like “pages” and “fields” and currently are used for W9 forms. (For information on forms, consult this guide)

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

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

Contractor Documents APIs

1. Get a contractor’s documents

Retrieve a contractor’s documents by specifying their UUID in the route of the GET /v1/contractors/{{contractor_uuid}}/documents endpoint. This endpoint returns a list of documents, along with their attributes:

[  
  {  
    "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  
      }  
    ],  
  }  
]

uuid: uuid of the document
title: title of the document
name: type identifier of the document
recipient_type: type of recipient associated with the document (will be “Contractor” for Contractor Documents)
recipient_uuid: unique identifier for the recipient associated with the document (will be contractor_uuid for Contractor Documents)
signed_at: when the document was signed (will be null if unsigned)
description: description of the document
requires_signing: whether the document requires signing
draft: whether the document is in the draft state
year: the year of this document (this value is nullable and will not be present on all documents)
quarter: the quarter of this document (this value is nullable and will not be present on all documents)
pages: a list of page numbers and their associated image URLs
fields: a list of fields and their associated data (including **key and value)

The pages and fields attributes can be used for signing preparation; for instance, one can render the document’s pages with the image URLs, and use the field values to autofill certain fields on the form.

Once a document has been signed, one can fetch the pdf to access the document’s data. Thus, pages and fields are only necessary for signing preparation, and we will not return these attributes for signed documents:

  {  
    "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. Get a document

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

For an unsigned document:

{  
    "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  
      }  
    ]  
  }

For a signed document:

{  
    "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 a document pdf

Retrieve a document’s pdf with the GET /v1/documents/{{document_uuid}}/pdf endpoint using its uuid. 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">  
}

4. Sign a document

For contractor W-9 forms, a value must be passed in for name and signature_text using the PUT /v1/documents/{{document_uuid}}/sign endpoint. One must also agree to sign the form electronically, and pass in a valid signed_by_ip_address format.

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));

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 not 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  
  }

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));

Then, generate a contractor_documents flow via API call to our Flows endpoint.

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));

2. View Documents

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.

3. Sign Documents

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

4. View/Download Signed Document

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