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 tax documentation that satisfies Paxos’s acceptance check 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.

​
Failed tax requirements and approval

A TAX_DOCUMENTATION requirement can have status: FAILED while the Identity has status: APPROVED. The requirement reports validation or remediation issues with the current form; its status alone does not determine whether the Identity can transact. Use the Identity’s top-level status and status_details.active_controls to determine access restrictions. For W-forms, TAX_DOCUMENTATION_RESUBMISSION_REQUIRED explicitly requests a replacement form to satisfy Paxos’s tax-documentation acceptance check. Specific reason codes, such as TREATY_COUNTRY_MISMATCH, US_INDICIA, or TIN_MISMATCH, can appear without it. Those reasons can still require remediation when awaiting_action_from is CLIENT, but do not by themselves mean that Paxos requires a replacement form for approval. For example, this Identity is approved, has no active controls, and still has a tax-documentation issue for you to address:
The absence of TAX_DOCUMENTATION_RESUBMISSION_REQUIRED does not mean that no action is needed or that the Identity is approved. TAX_DOCUMENTATION_REQUIRED requests an initial form, and TAX_DOCUMENTATION_EXPIRED requests renewal. Other requirements and active controls can also restrict access.

​
Choose the next action

Read errors[].code together with awaiting_action_from. Use Submit Tax Documentation when you need to submit, replace, correct, or renew a form. There is no separate partial-update endpoint; any form submission must be complete. The following specific reason codes can accompany TAX_DOCUMENTATION_RESUBMISSION_REQUIRED or appear independently. A reason under review can also accompany TAX_DOCUMENTATION_VALIDATION_PENDING with awaiting_action_from: PAXOS. Use the requirement and Identity states to determine the next action:
  • 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