Replace a PDF file for a W-9 form

Endpoint: POST /w9/forms/{id}/attachment

Use case:

Use this endpoint to replace the PDF file associated with an existing W-9, W-4, or W-8 form. This is commonly used when:

A vendor or employee has provided a completed form offline (for example, via email or physical copy) and you need to upload it into the system.
An updated or corrected version of the form must be stored in place of the old one.
You want to maintain a digital record of a signed form for compliance purposes.

This operation ensures that the system retains the latest valid document while keeping the form record linked to the correct vendor or payee.

Supported form types

This endpoint supports the following forms:

W-9 - U.S. taxpayer information form
W-4 - Employee’s withholding certificate
W-8BEN, W-8BEN-E, W-8IMY - Foreign individual/entity tax documentation

Sample request

POST /w9/forms/87623979/attachment
Content-Type: multipart/form-data
file=@Jane-Smith-W9.pdf

Successful response

{
    "id": "87623979",
    "message": "File uploaded.",
    "fileName": "Jane-Smith-W9.pdf"
}

Prerequisites and validation rules

The form with the given {id} must exist.
PDF files is the only supported option. Uploading any other file type will return an error.
Uploading a new PDF overwrites the previous attachment for that form.
The form record itself, including name, email, and type, remains unchanged. The system updates only the associated PDF file.

Sample error response (invalid file type)

{
  "title": "One or more validation errors occurred.",
  "errors": [
    {
      "type": "file.ContentType",
      "detail": "Only .pdf files are allowed."
    }
  ]
}