Manage company attachments

Gusto’s API enables employers to upload documents such as tax notices so that they’re available through API calls and to our support team—enabling us to collaborate with employers to resolve notices. The company attachment endpoints are primarily intended for tax notices and compliance documents, although they can also be extended to other workflows that require document uploads.

Company attachments are different from company forms, which include onboarding forms like Form 8655 or tax forms like Form 944.

The API supports uploading, listing, [viewing](/embedded-payroll/v2025-11-15/reference/get-v1-companies-attachmentget, and downloading company attachments.

Uploading an attachment

To create a company attachment, upload a file using the POST companies/{company_uuid}/attachments endpoint. The endpoint takes the file binary and document category as multipart/form-data, and returns a JSON response with the uploaded file’s information.

Upload PDF files

Although the API supports multiple file formats, we recommend uploading PDF files for optimal compatibility.

The endpoint requires two form-data parameters:

• document: the binary data of the file being uploaded.
  • The following file types are allowed: .qbb, .qbm, .gif, .jpg, .png, .pdf, .xls, .xlsx, .doc, and .docx.
• category: the category of the attached file. Use gep_notice for tax notices and compliance for general compliance documents.

bash

curl --location 'https://api.gusto.com/v1/companies/{company_uuid}/attachments' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {COMPANY_API_TOKEN}' \
--form 'document=@"/path/to/your/file.pdf"' \
--form 'category="gep_notice"'

Retrieving company attachments

Retrieve a list of all company attachments using the GET companies/{company_uuid}/attachments endpoint.

bash

curl --location 'https://api.gusto-staging.com/v1/companies/{company_uuid}/attachments' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {COMPANY_API_TOKEN}'

To retrieve a specific attachment by its UUID, use the GET companies/{company_uuid}/attachments/{attachment_uuid} endpoint.

To download a file, generate a download URL for an attachment using the GET companies/{company_uuid}/attachments/{attachment_uuid}/download_url endpoint. The URL expires after 30 seconds so you must download the file immediately.

---

Company forms

Create a department