API v1 → v2 Migration Guide

W-9 Submission

We have replaced the POST /tax-documentation/w-9 endpoint with the more generic POST /tax-documentation endpoint for all submissions. We have also updated the shape of the request body, as outlined below.

Changes

Property	Action
`name_line_2`	Renamed to `dba_name`
`tax_id`	Renamed to `tin`
`tax_id_type`	Renamed to `tin_type`
`is_certified_by_client`	Renamed to `has_certified`
`signature_date`	Renamed to `signature_timestamp`
`is_not_subject_backup_witholding`	Added

Example Request Body

{
  "name": "John Smith",
  "dba_name": "",
  "tax_classification": "INDIVIDUAL",
  "address": {
    "first_line": "123 Main St",
    "city": "Seattle",
    "state_or_province": "WA",
    "postal_code": "98000",
    "country": "US"
  },
  "tin": "123123123",
  "tin_type": "SSN",
  "document_type": "W-9",
  "has_certified": true,
  "is_not_subject_backup_withholding": false,
  "signature": "John Smith",
  "signature_timestamp": "2023-05-08T18:52:12.210Z"
}

W-9 Retrieval

We have replated the GET /tax-documentation/w-9 endpoint with the more generic GET /tax-documentation endpoint. The response shape matches what the user submitted via the POST endpoint, plus an additional id property.

{
  "id": "5f7a2374-aeb4-4386-90df-8c9314258029"
  // rest of submission...
}

This id can be used to retrieve a specific document by making a request to GET /tax-documentation/{id}.

W-9 Documentation Status

We have replaced the GET /tax-documentation/status endpoint with the GET /tax-documentation/summary endpoint. We have also updated the shape of the response as outlined below.

Changed Properties

Property	Action
`id`	Added
`tin_report_status`	Renamed to `tin_verification_status`
`tin_validation_date`	Renamed to `tin_verification_date`
`tin_validation_status`	Removed
`issues`	Removed for W-9s. Our submission process no longer allows W-9s to be submitted with issues.
`expiration_date`	Removed for W-9s. Our submission process no longer return the expiration_date for W-9s
`status`	Replaced values to be `VALID`, `INVALID`, and `UNDOCUMENTED`.

Example Response

{
    "document_type": "W-9",
    "status": "VALID",
    "tin_verification_status": "VALID",
    "tin_verification_date": "2023-05-08T18:52:12.210Z",
    "id": "2c967ae7-e1c1-4d38-b306-b219eea45b1c"
}

PDF Generation

We changed the endpoint for generating a W-9 PDF from POST /tax-documentation/forms to POST /tax-documentation/document. This endpoint no longer takes a request body. Instead, it just generates the PDF of the account owner's latest submission.

Example response:

{
    "id": "c0025213-7871-4f80-bb2e-6016e9460fba",
    "status": "PROCESSING",
    "type": "W-9",
    "created_date": "2023-05-10T19:23:48.501Z"
}

Once you have this response, you can use the id to retrieve the PDF at GET /tax-documentation/document/{id}.