Contractor Forms

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 documents consult this guide).

The contractor 1099 is a form that can be accessed/generated through the Forms API. Currently, the Forms API is only used for contractor 1099s.

Contractor Forms

1. Generate 1099 forms (Demo)

Contractor 1099 Forms are generated at the end of the calendar year. To test these endpoints in demo at anytime, use the POST sandbox/generate_1099 endpoint.

2. Get a contractor's forms

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

[
  {
    "uuid": "48cdd5ec-a4dd-4840-a424-ad79f38d8408",
    "name": "US_1099",
    "title": "Form 1099: 2020",
    "description": "Form 1099 records your annual income as a contractor.",
    "draft": false,
    "requires_signing": false,
    "year": 2020,
    "quarter": null,
    "contractor_uuid": "123dd616-6dbc-4724-938a-403f6217a933"
  }
]

• uuid: uuid of the form
• title: title of the form
• name: type identifier of the form
• contractor_uuid: unique identifier for the contractor associated with the form
• 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)

3. Get a form

Retrieve a specific document with the GET /v1/contractors/{{contractor_uuid}}/forms/{{form_id}} endpoint using its uuid.

For an unsigned document:

{
  "uuid": "48cdd5ec-a4dd-4840-a424-ad79f38d8408",
  "name": "US_1099",
  "title": "Form 1099: 2020",
  "description": "Form 1099 records your annual income as a contractor.",
  "draft": false,
  "requires_signing": false,
  "year": 2020,
  "quarter": null,
  "contractor_uuid": "123dd616-6dbc-4724-938a-403f6217a933"
}

4. Get a contractor form pdf

Retrieve a document’s pdf with the GET /v1/contractors/{contractor_uuid}/forms/{form_id}/pdf endpoint using its uuid.

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