Create W-9 forms

Endpoint:POST /w9/forms

Use case:

This endpoint is used to create a W-9, W-8, and W-4 form for a recipient (vendor, contractor, or payee). You can use this to store and manage manually collected forms data, or to pre-fill a form before sending it via email for completion.

Each form must be linked to a previously created company using thecompanyId field.

This is the list of forms currently supported by this endpoint:

W-9 - Request for Taxpayer Identification Number and Certification (U.S. residents)
W-4 - Employee's Withholding Certificate
W-8BEN, W-8BEN-E, W-8IMY - Forms used by foreign individuals and entities to certify tax status

All of these forms are submitted through the same endpoint. Thetype field in the payload determines which form schema will be used.

Note

Each form type has its own required and optional fields. Be sure to structure the payload according to the selected form type.

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 payload

{
  "type": "W9",
  "name": "John Doe",
  "businessName": "Doe Enterprises",
  "businessClassification": "Individual",
  "businessOther": null,
  "foreignPartnerOwnerOrBeneficiary": false,
  "exemptPayeeCode": null,
  "exemptFatcaCode": null,
  "foreignCountryIndicator": false,
  "address": "123 Main St.",
  "foreignAddress": null,
  "city": "Anytown",
  "state": "CA",
  "zip": "90210",
  "accountNumber": "ACC-1001",
  "tinType": "SSN",
  "tin": "543456780",
  "backupWithholding": false,
  "is1099able": true,
  "companyId": "205675590",
  "referenceId": "W9-REF-2024-001",
  "email": "john.doe@example.com",
  "eDeliveryConsentedAt": null,
  "signature": ""
}

Key Properties


Field	Description
`type`	Must indicate the form type
`name`	Name of the individual or entity
`businessName`	Optional business name
`businessClassification`	IRS classification (for example,`"Individual"`,`"LLC"`,`"C Corporation"`)
`foreignPartnerOwnerOrBeneficiary`	Whether the person is a foreign beneficiary
`foreignCountryIndicator`	Indicates foreign residency
`address`,`city`,`state`,`zip`	Mailing address
`foreignAddress`	If located outside the US
`tinType`	`"SSN"` or`"EIN"`
`tin`	Taxpayer Identification Number
`backupWithholding`	Whether the individual is subject to withholding
`is1099able`	Whether a 1099 form will be issued to this recipient
`companyId`	ID of the company requesting the form (required)
`referenceId`	Optional tracking ID
`email`	Optional contact email
`eDeliveryConsentedAt`	Timestamp when the recipient consented to e-delivery
`signature`	Optional SVG image string representing the digital signature from the vendor

Sample response

{
    "name": "John Doe",
    "businessName": "Doe Enterprises",
    "businessClassification": "Individual",
    "businessOther": null,
    "foreignPartnerOwnerOrBeneficiary": false,
    "exemptPayeeCode": null,
    "exemptFatcaCode": null,
    "foreignCountryIndicator": false,
    "address": "123 Main St.",
    "foreignAddress": null,
    "city": "Anytown",
    "state": "CA",
    "zip": "90210",
    "accountNumber": "ACC-1001",
    "tinType": "SSN",
    "tin": "543456780",
    "backupWithholding": false,
    "is1099able": true,
    "tinMatchStatus": {
        "time": null,
        "status": "Pending",
        "irsResponse": null
    },
    "id": "65248327",
    "entryStatus": {
        "status": "signed",
        "time": "2025-09-01T17:22:26.155988"
    },
    "referenceId": "W9-REF-2024-001",
    "companyId": "155706455",
    "displayName": "John Doe",
    "email": "john.doe@example.com",
    "archived": false,
    "ancestorId": "0",
    "signature": "",
    "signedDate": "2025-09-01T17:22:26.155988",
    "eDeliveryConsentedAt": null,
    "createdAt": "2025-09-01T17:22:26.155943",
    "updatedAt": "2025-09-01T17:22:26.155944"
}

Sample validation error response

If required fields are missing or the payload is malformed, the API will return a400 Bad Request.

{
    "title": "One or more validation errors occurred.",
    "errors": [
        {
            "type": "CompanyId",
            "detail": "'Company Id' must not be empty."
        },
        {
            "type": "Name",
            "detail": "'Name' must not be empty."
        }
    ]
}