Skip to main content
The Tax Documentation API allows you to submit a complete substitute W-form collected in your customer experience and retrieve the Identity’s current tax documentation. Each submission belongs to the Identity specified in the POST request body; the GET endpoint specifies the Identity in its path.
Tax documentation collection applies only to person and institution Identities in the Paxos Trust Company (PTC) population. Business-member Identities do not need to submit tax documentation. Beginning January 1, 2027, in-scope Identities without approved tax documentation will be blocked from taxable transactions.
The API supports three form types: The partner selects the form type and retains the executed substitute form. Paxos accepts the structured form values and certification metadata, but not a PDF or other evidence artifact. Use Submit Tax Documentation to submit the initial form or replace the current form with another complete submission. Use Get Tax Documentation to retrieve the latest form accepted for the Identity. For integration guidance and complete examples, see Collect Tax Documentation.

​
Relationship to Identity details

Tax documentation and Identity details have independent lifecycles. Submitting or replacing tax documentation does not update person_details or institution_details. Updating those Identity details does not modify the current tax documentation. When information must change in both resources, update each resource separately. The current tax documentation represents the latest form accepted by Paxos and can therefore differ from the Identity’s current details.

​
Respond to tax-documentation requirements

Paxos exposes an outstanding tax-documentation obligation through status_details.requirements on Get Identity and List Identities. A requirement with type: TAX_DOCUMENTATION identifies the action or processing state for the Identity’s current W-form. For every client-actionable tax-documentation requirement, use Submit Tax Documentation. There is no separate remediation endpoint: submit another complete form to replace or renew the current form. When Paxos requires a complete resubmission, it can include one or more of these reason codes with TAX_DOCUMENTATION_RESUBMISSION_REQUIRED:
  • TIN_MISMATCH
  • TIN_NOT_ISSUED
  • INVALID_TAX_DOCUMENTATION_DATA
  • INVALID_PERMANENT_ADDRESS_CARE_OF
  • INVALID_PERMANENT_ADDRESS_PO_BOX
  • INVALID_PERMANENT_ADDRESS_US
  • TREATY_COUNTRY_MISMATCH
  • US_INDICIA
  • INCOMPLETE_WITHHOLDING_DOCUMENTATION
  • CHANGE_IN_CIRCUMSTANCES
  • INCOMPLETE_DATA
  • INCONSISTENT_DATA
  • INCOMPLETE_ADDRESS
  • INCOMPLETE_TAX_CLASSIFICATION
  • INCOMPLETE_US_TIN
  • INCOMPLETE_TREATY_CLAIM