> ## 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. # Submit Tax Documentation > Submit a complete partner-collected W-9, W-8BEN, or W-8BEN-E for an Identity. ```bash OAuth Scope theme={null} identity:write_identity ``` Your organization must retain the executed substitute form. This endpoint accepts structured form values and certification metadata; it does not accept an evidence file. A successful request returns the stored representation that can subsequently be retrieved with [Get Tax Documentation](/api-reference/endpoints/tax-documentation/get-tax-documentation). This operation creates or replaces the Identity's tax documentation only. It does not update the Identity's `person_details` or `institution_details`. See [Collect Tax Documentation](/guides/identity/tax-documentation) for form-selection, replacement, and Identity-detail behavior. ## OpenAPI ````yaml preview/paxos-v2-preview-tax-documentation.openapi.json post /identity/tax-documentation openapi: 3.0.3 info: title: Paxos Partner-Collected Tax Documentation API description: >- Design preview for submitting and retrieving partner-collected tax documentation through the Identity API. version: v2-preview servers: - url: https://api.paxos.com/v2 security: [] paths: /identity/tax-documentation: post: tags: - Tax Documentation summary: Submit Tax Documentation description: >- Submit a complete partner-collected W-9, W-8BEN, or W-8BEN-E for an Identity. A later accepted request becomes the current tax document, including when the form type changes. The partner retains the executed substitute form; this operation accepts structured values and certification metadata only. Submitting tax documentation does not update the Identity's person_details or institution_details. operationId: CreateTaxDocumentation requestBody: required: true description: >- A complete form submission. The populated tax_documentation object must match form_type. content: application/json: schema: $ref: '#/components/schemas/CreateTaxDocumentationRequest' examples: w_9: summary: W-9 value: 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 w_8ben: summary: W-8BEN value: 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 w_8ben_e: summary: W-8BEN-E value: 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 responses: '200': description: >- Paxos validated and stored the submission as the Identity's current tax documentation. The response does not indicate downstream processing or acceptance. content: application/json: schema: $ref: '#/components/schemas/TaxDocumentation' '400': description: >- The request failed form, field, format, or conditional validation. A previously accepted form remains current. '401': description: The request is not authenticated. '403': description: The caller is not authorized for the Identity. '404': description: The Identity does not exist. '429': description: The caller exceeded its rate limit. security: - OAuth2: - identity:write_identity components: schemas: CreateTaxDocumentationRequest: type: object additionalProperties: false required: - identity_id - form_type - tax_documentation properties: identity_id: type: string description: >- Identifier of the Identity whose tax documentation is being submitted. minLength: 6 maxLength: 64 pattern: ^[a-zA-Z0-9][a-zA-Z0-9-.]{4,62}[a-zA-Z0-9]$ form_type: type: string enum: - W_9 - W_8BEN - W_8BEN_E description: IRS form selected by the partner. Paxos does not infer this value. tax_documentation: $ref: '#/components/schemas/TaxDocumentationPayload' TaxDocumentation: type: object additionalProperties: false required: - form_type - tax_documentation - created_at properties: form_type: type: string enum: - W_9 - W_8BEN - W_8BEN_E description: IRS form represented by tax_documentation. tax_documentation: $ref: '#/components/schemas/TaxDocumentationPayload' created_at: type: string format: date-time description: Time Paxos accepted this form. TaxDocumentationPayload: type: object additionalProperties: false minProperties: 1 maxProperties: 1 description: Exactly one form object is required, and it must match form_type. properties: w_9: $ref: '#/components/schemas/W9TaxDocumentation' w_8ben: $ref: '#/components/schemas/W8BenTaxDocumentation' w_8ben_e: $ref: '#/components/schemas/W8BenETaxDocumentation' W9TaxDocumentation: allOf: - $ref: '#/components/schemas/Certification' - type: object required: - name - tax_classification - address - tin - tin_type - is_not_subject_to_backup_withholding properties: name: type: string maxLength: 200 pattern: ^[0-9A-Za-z /?:().,&'+-]+$ description: Legal name of the account owner. doing_business_as: type: string description: Doing-business-as or disregarded-entity name. tax_classification: type: string description: Federal tax classification. enum: - INDIVIDUAL - C_CORPORATION - S_CORPORATION - PARTNERSHIP - TRUST_ESTATE - LLC_C - LLC_P - LLC_S - SOLE_PROPRIETOR - OTHER other_tax_classification: type: string description: Required when tax_classification is OTHER. address: $ref: '#/components/schemas/IdentityMailingAddress' tin: type: string maxLength: 35 pattern: ^[0-9A-Za-z /?:().,&'+-]+$ description: US taxpayer identification number. tin_type: type: string enum: - SSN - EIN - ITIN - ATIN exempt_payee_code: type: string description: >- Payee code for exemption from backup withholding, when applicable. enum: - '1' - '2' - '3' - '4' - '5' - '6' - '7' - '8' - '9' - '10' - '11' - '12' - '13' exempt_fatca_code: type: string description: FATCA reporting exemption code, when applicable. enum: - A - B - C - D - E - F - G - H - I - J - K - L - M is_not_subject_to_backup_withholding: type: boolean description: >- Whether the account owner did not cross out the backup-withholding certification. W8BenTaxDocumentation: allOf: - $ref: '#/components/schemas/Certification' - $ref: '#/components/schemas/W8CommonTaxDocumentation' - type: object required: - name - nationality - permanent_address - date_of_birth properties: name: type: string maxLength: 200 pattern: ^[0-9A-Za-z /?:().,&'+-]+$ description: Legal name of the individual. nationality: type: string pattern: ^[A-Z]{3}$ description: ISO 3166-1 alpha-3 country code. permanent_address: $ref: '#/components/schemas/IdentityMailingAddress' mailing_address: $ref: '#/components/schemas/IdentityMailingAddress' date_of_birth: type: string pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ description: Date of birth in YYYY-MM-DD format. W8BenETaxDocumentation: allOf: - $ref: '#/components/schemas/Certification' - $ref: '#/components/schemas/W8CommonTaxDocumentation' - type: object required: - name - country_of_organization - tax_classification - permanent_address properties: name: type: string maxLength: 200 pattern: ^[0-9A-Za-z /?:().,&'+-]+$ description: Legal name of the institution. country_of_organization: type: string pattern: ^[A-Z]{3}$ description: ISO 3166-1 alpha-3 country code. tax_classification: type: string description: Federal tax classification for W-8BEN-E. enum: - CORPORATION - PARTNERSHIP - SIMPLE_TRUST - COMPLEX_TRUST - GRANTOR_TRUST - ESTATE - CENTRAL_BANK_OF_ISSUE - FOREIGN_GOVERNMENT_CONTROLLED_ENTITY - FOREIGN_GOVERNMENT_INTEGRAL_PART - TAX_EXEMPT_ORGANIZATION - PRIVATE_FOUNDATION - INTERNATIONAL_ORGANIZATION permanent_address: $ref: '#/components/schemas/IdentityMailingAddress' mailing_address: $ref: '#/components/schemas/IdentityMailingAddress' certify_requirements: type: boolean description: >- Certifies that the institution derives the income and meets the treaty's limitation-on-benefits requirements. Required when claiming treaty benefits. limitation_on_benefits: type: string description: >- Applicable limitation-on-benefits provision. Required when claiming treaty benefits. enum: - GOVERNMENT - TAX_EXEMPT_PENSION - OTHER_TAX_EXEMPT_ORGANIZATION - PUBLICLY_TRADED_CORPORATION - SUBSIDIARY - COMPANY_MEETS_EROSION_TEST - COMPANY_MEETS_DERIVATIVE_TEST - COMPANY_MEETS_BUSINESS_TEST - FAVORABLE_DETERMINATION - NO_LOB_ARTICLE - OTHER_ARTICLE_PARAGRAPH limitation_other_article_paragraph: type: string description: >- Applicable treaty article and paragraph. Required when limitation_on_benefits is OTHER_ARTICLE_PARAGRAPH. Certification: type: object required: - has_signed_and_certified - signature_timestamp - completed_for - signature properties: has_signed_and_certified: type: boolean enum: - true description: >- Confirms that the account owner signed and certified the substitute form. Must be true. signature_timestamp: type: string format: date-time description: Timestamp when the form was signed. completed_for: type: string enum: - ACCOUNT_HOLDER - REGARDED_OWNER description: Person or entity for whom the form was completed. signature: type: string maxLength: 200 pattern: ^[0-9A-Za-z /?:().,&'+-]+$ description: Name signed on the substitute form. IdentityMailingAddress: type: object description: >- Address certified on the form. This uses the same field contract as Identity person and institution details but is stored independently and is not synchronized with them. additionalProperties: false required: - country - address1 - city - province properties: country: type: string maxLength: 255 description: ISO 3166-1 alpha-3 country code. example: CAN address1: type: string maxLength: 255 description: First line of the address. address2: type: string maxLength: 255 description: Optional second line of the address. city: type: string maxLength: 255 province: type: string maxLength: 255 description: State, province, or region. zip_code: type: string maxLength: 255 description: Postal or ZIP code. Required for countries that use postal codes. W8CommonTaxDocumentation: type: object required: - foreign_tin_not_legally_required properties: us_tin: type: string maxLength: 35 pattern: ^[0-9A-Za-z /?:().,&'+-]+$ description: US taxpayer identification number, when applicable. foreign_tin: type: string maxLength: 35 pattern: ^[0-9A-Za-z /?:().,&'+-]+$ description: >- Foreign taxpayer identification number. Required unless it is not legally required. foreign_tin_not_legally_required: type: boolean description: >- Whether a foreign TIN is not legally required. When true, omit foreign_tin. reference_numbers: type: string description: >- Reference number entered on the form. This is tax-form data, not a Paxos request identifier or idempotency key. treaty_claim_country: type: string pattern: ^[A-Z]{3}$ description: >- ISO 3166-1 alpha-3 country code for a claimed treaty benefit. Its presence indicates a treaty claim. certify_resident: type: boolean description: >- Certifies residence in treaty_claim_country. Required when claiming treaty benefits. income_type: type: string description: >- Type of income covered by the treaty claim. Required when claiming treaty benefits. enum: - BUSINESS_PROFITS - DIVIDENDS - INTEREST - OTHER_INCOME - ROYALTIES_MOTION_PICTURE_AND_TV - ROYALTIES_OTHER withholding_rate: type: string format: decimal description: >- Treaty withholding rate as a percentage without the percent sign. Required when claiming treaty benefits. article_paragraph: type: string description: >- Treaty article and paragraph. Required when claiming treaty benefits. has_additional_conditions: type: boolean description: >- Whether the treaty claim has additional conditions. Required when claiming treaty benefits. securitySchemes: OAuth2: type: oauth2 flows: clientCredentials: tokenUrl: https://oauth.paxos.com/oauth2/token scopes: identity:read_identity: Read identities identity:write_identity: Create and manage identities ````