API Migration Guide

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.


name_line_2Renamed to dba_name
tax_idRenamed to tin
tax_id_typeRenamed to tin_type
is_certified_by_clientRenamed to has_certified
signature_dateRenamed to signature_timestamp

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

tin_report_statusRenamed to tin_verification_status
tin_validation_dateRenamed to tin_verification_date
issuesRemoved for W-9s.
Our submission process no longer allows W-9s to be submitted with issues.
expiration_dateRemoved for W-9s.
Our submission process no longer return the expiration_date for W-9s
statusReplaced 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}.