> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paxos.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Collect Tax Documentation
> Submit and retrieve partner-collected W-9, W-8BEN, and W-8BEN-E tax documentation for an Identity.
You can collect an IRS substitute W-form in your onboarding or account-management experience and submit the completed form data to Paxos for a specific Identity.
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.
This flow supports:
* `W_9` for a person or institution that is a US person
* `W_8BEN` for a non-US person
* `W_8BEN_E` for a non-US institution
Your organization retains the executed substitute form. Submit the structured form values and certification metadata only. The API does not accept a PDF, image, signing transcript, IP address, or other evidence artifact.
## Before you begin
You need:
* An OAuth client with the `identity:write_identity` scope to submit a form and the `identity:read_identity` scope to retrieve the current form
* The ID of an Identity owned by your organization
* A complete, signed substitute W-9, W-8BEN, or W-8BEN-E
Tax documentation and Identity details have independent lifecycles. Submitting or replacing tax documentation does not update `person_details` or `institution_details`, and updating those Identity details does not modify the current tax documentation. Submit every value the customer certified, even when the same value is already present on the Identity. When information must change in both resources, update each resource separately.
## Submit tax documentation
### ➊ Select the form
Set `form_type` and include exactly one matching object inside `tax_documentation`.
| `form_type` | Required object | Compatible Identity type |
| - | - | - |
| `W_9` | `w_9` | Person or institution |
| `W_8BEN` | `w_8ben` | Person |
| `W_8BEN_E` | `w_8ben_e` | Institution |
Paxos rejects a request when the discriminator, nested object, and Identity type do not agree.
### ➋ Build the complete request
The following examples include optional and conditional fields so you can review the full proposed shape. Only include treaty fields when the customer claims treaty benefits.
Each address follows the shared `IdentityMailingAddress` contract: all six fields allow up to 255 characters without a character-pattern restriction. `country`, `address1`, `city`, and `province` are required; `address2` is optional; and `zip_code` is required for countries that use postal codes.
```json theme={null}
{
"identity_id": "067ecc2e-9b9c-470e-b1c7-b436a0707ef5",
"form_type": "W_9",
"tax_documentation": {
"w_9": {
"name": "Example Holdings LLC",
"doing_business_as": "Example Markets",
"tax_classification": "OTHER",
"other_tax_classification": "Single-member LLC",
"address": {
"country": "USA",
"address1": "123 Example Street",
"address2": "Suite 400",
"city": "New York",
"province": "NY",
"zip_code": "10001"
},
"tin": "12-3456789",
"tin_type": "EIN",
"exempt_payee_code": "5",
"exempt_fatca_code": "A",
"is_not_subject_to_backup_withholding": true,
"has_signed_and_certified": true,
"signature_timestamp": "2026-08-28T14:01:23Z",
"completed_for": "ACCOUNT_HOLDER",
"signature": "Jane Example"
}
}
}
```
```json theme={null}
{
"identity_id": "067ecc2e-9b9c-470e-b1c7-b436a0707ef5",
"form_type": "W_8BEN",
"tax_documentation": {
"w_8ben": {
"name": "Example Person",
"nationality": "CAN",
"permanent_address": {
"country": "CAN",
"address1": "100 Example Road",
"address2": "Unit 8",
"city": "Toronto",
"province": "ON",
"zip_code": "M5V 2T6"
},
"mailing_address": {
"country": "CAN",
"address1": "PO Box 100",
"city": "Toronto",
"province": "ON",
"zip_code": "M5V 2T6"
},
"us_tin": "912-70-1234",
"foreign_tin": "123456789",
"foreign_tin_not_legally_required": false,
"date_of_birth": "1985-04-12",
"reference_numbers": "PARTNER-TAX-10001",
"treaty_claim_country": "CAN",
"certify_resident": true,
"income_type": "INTEREST",
"withholding_rate": "0",
"article_paragraph": "Article XI, paragraph 1",
"has_additional_conditions": false,
"has_signed_and_certified": true,
"signature_timestamp": "2026-08-28T14:01:23Z",
"completed_for": "ACCOUNT_HOLDER",
"signature": "Example Person"
}
}
}
```
```json theme={null}
{
"identity_id": "067ecc2e-9b9c-470e-b1c7-b436a0707ef5",
"form_type": "W_8BEN_E",
"tax_documentation": {
"w_8ben_e": {
"name": "Example Global Ltd.",
"country_of_organization": "GBR",
"tax_classification": "CORPORATION",
"permanent_address": {
"country": "GBR",
"address1": "10 Example Square",
"address2": "Floor 3",
"city": "London",
"province": "London",
"zip_code": "SW1A 1AA"
},
"mailing_address": {
"country": "GBR",
"address1": "20 Correspondence Way",
"city": "London",
"province": "London",
"zip_code": "EC1A 1BB"
},
"us_tin": "98-7654321",
"foreign_tin": "GB123456789",
"foreign_tin_not_legally_required": false,
"reference_numbers": "PARTNER-TAX-20001",
"treaty_claim_country": "GBR",
"certify_resident": true,
"income_type": "DIVIDENDS",
"withholding_rate": "15",
"article_paragraph": "Article 10, paragraph 2",
"has_additional_conditions": true,
"certify_requirements": true,
"limitation_on_benefits": "PUBLICLY_TRADED_CORPORATION",
"limitation_other_article_paragraph": "",
"has_signed_and_certified": true,
"signature_timestamp": "2026-08-28T14:01:23Z",
"completed_for": "ACCOUNT_HOLDER",
"signature": "Jane Example"
}
}
}
```
For the complete field descriptions, enum values, and conditional rules, see [Submit Tax Documentation](/api-reference/endpoints/tax-documentation/submit-tax-documentation).
### ➌ POST the form for the Identity
```bash theme={null}
curl --request POST \
--url https://api.paxos.com/v2/identity/tax-documentation \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"identity_id": "067ecc2e-9b9c-470e-b1c7-b436a0707ef5",
"form_type": "W_8BEN",
"tax_documentation": {
"w_8ben": {
"name": "Example Person",
"nationality": "CAN",
"permanent_address": {
"country": "CAN",
"address1": "100 Example Road",
"city": "Toronto",
"province": "ON",
"zip_code": "M5V 2T6"
},
"foreign_tin": "123456789",
"foreign_tin_not_legally_required": false,
"date_of_birth": "1985-04-12",
"has_signed_and_certified": true,
"signature_timestamp": "2026-08-28T14:01:23Z",
"completed_for": "ACCOUNT_HOLDER",
"signature": "Example Person"
}
}
}'
```
### ➍ Handle acceptance
Paxos returns `200 OK` after authenticating the request, authorizing access to the Identity, validating the complete form, and storing it as the Identity's current tax documentation. The response contains the same representation returned by the GET endpoint:
```json theme={null}
{
"form_type": "W_8BEN",
"tax_documentation": {
"w_8ben": {
"name": "Example Person",
"nationality": "CAN",
"permanent_address": {
"country": "CAN",
"address1": "100 Example Road",
"city": "Toronto",
"province": "ON",
"zip_code": "M5V 2T6"
},
"foreign_tin": "123456789",
"foreign_tin_not_legally_required": false,
"date_of_birth": "1985-04-12",
"has_signed_and_certified": true,
"signature_timestamp": "2026-08-28T14:01:23Z",
"completed_for": "ACCOUNT_HOLDER",
"signature": "Example Person"
}
},
"created_at": "2026-08-28T14:01:24Z"
}
```
This response confirms Paxos storage only. It does not mean that a downstream tax provider has processed or accepted the form.
## Retrieve the current form
Use GET to retrieve the latest tax documentation accepted for the Identity, regardless of form type.
```bash theme={null}
curl --request GET \
--url https://api.paxos.com/v2/identity/tax-documentation/067ecc2e-9b9c-470e-b1c7-b436a0707ef5 \
--header 'Authorization: Bearer '
```
Paxos returns `200 OK` with the same representation returned by POST. If the Identity does not have accepted tax documentation, Paxos returns `404 Not Found`. The response does not expose downstream tax-provider processing status. The returned values reflect the latest accepted form and can differ from the Identity's current `person_details` or `institution_details`.
## Respond to tax-documentation requirements
Use `status_details.requirements` on [Get Identity](/api-reference/endpoints/identity/get-identity) or [List Identities](/api-reference/endpoints/identity/list-identities) to identify an outstanding `TAX_DOCUMENTATION` requirement. When `awaiting_action_from` is `CLIENT`, submit another complete form through the same endpoint; there is no separate remediation endpoint.
For lifecycle states, reason codes, and the corresponding partner action, see [Respond to tax-documentation requirements](/api-reference/endpoints/tax-documentation/overview#respond-to-tax-documentation-requirements).
## Correct or replace a form
POST another complete request to the same endpoint. A later accepted request becomes the current tax document for the Identity:
* The same `form_type` corrects the current form.
* A different `form_type` replaces the current form.
* A rejected request leaves the previously accepted form current.
Partial updates are not supported. The API does not expose PATCH, PUT, or DELETE operations for tax documentation.
Updating the Identity's `person_details` or `institution_details` does not replace its current tax documentation. Submit another complete form through this endpoint when the certified tax documentation must change.
## Supported and unsupported forms
| Form | MVP support |
| - | - |
| W-9 | Supported |
| W-8BEN | Supported |
| W-8BEN-E | Supported |
| W-8IMY | Not supported |
| W-8ECI | Not supported |
| W-8EXP | Not supported |