Documentation
Portal

W-8 Implementation Guide - API

Guide to providing relevant W-8 details during user onboarding

📘

One W-8BEN certification for individuals

For non-U.S. individuals, one new certification field replaces the W-8BEN field set: is_exempt_foreign_person. zerohash creates the W-8BEN record. It does this for customers who onboard through the zerohash Onboarding SDK, and for API requests that send the field with the tax ID and without the other W-8 fields. zerohash no longer collects treaty benefits for individuals. zerohash still accepts all current fields, so your integration keeps working without changes. W-8BEN-E requirements for entities do not change.

What are the W-8BEN and the W-8BEN-E?

  • W-8BEN. The IRS form that non-U.S. individuals use to certify that they are not U.S. persons. A valid W-8BEN on file exempts the participant from 24% backup withholding on U.S.-source income.
  • W-8BEN-E. The W-8BEN form for non-U.S. entities. The entity also declares its IRS tax classification, for example corporation, partnership or complex trust. If it applies, the entity can also claim treaty benefits under a Limitation on Benefits provision.

zerohash creates certified W-8BEN and W-8BEN-E forms from the data that you send through the API. For most customers, these two forms and the W-9 are enough.

The W-8 has other variants. zerohash accepts them as uploaded documents. See Do you already collect certified W-8 forms?

  • W-8IMY. The participant is a non-U.S. intermediary or flow-through entity that passes U.S.-source income to its beneficial owners. Examples are a foreign partnership, a simple trust, a grantor trust, a qualified intermediary, or a withholding foreign partnership or trust.
  • W-8ECI. The foreign participant claims that its U.S.-source income is effectively connected with a U.S. trade or business. That income is taxed on a net basis, like a U.S. person's, and is not subject to 30% withholding.
  • W-8EXP. The entity is a foreign government, a foreign central bank of issue, an international organization, a foreign tax-exempt organization or a foreign private foundation. It claims the exemption for these entities.
  • W-8CE. The participant is a covered expatriate, which is a former U.S. citizen or long-term green card holder. They make elections about deferred compensation, tax-deferred accounts or interests in non-grantor trusts after expatriation.

If you are not sure which requirements apply to your customers, contact your zerohash account team.

When to send W-8 information

Send W-8 information when you onboard a non-U.S. person through the zerohash U.S. flow. Participants onboarded through zerohash EU or other non-U.S. entities follow local tax rules and do not need a W-form.

  • Individuals. Send W-8BEN information when the participant is not a U.S. citizen, a green card holder or a U.S. tax resident.
  • Entities. Send W-8BEN-E information when the entity is not formed or organized under U.S. law. Examples are foreign corporations, partnerships and trusts.

zerohash treats a participant as a non-U.S. person if citizenship_code is not US and jurisdiction_code is not a U.S. jurisdiction when you create the participant.

What you send for non-U.S. individuals

The products and services that you use at zerohash set what you send. Your account team can confirm which case applies to you.

Case 1: name, address and foreign tax ID

For some integrations, zerohash needs only the data that you already send for KYC:

  • first_name and last_name
  • the address: address_one, city, jurisdiction_code and zip
  • date_of_birth
  • citizenship_code
  • tax_id: the tax ID issued by the customer's country of tax residence (the foreign TIN)

This is the full requirement for Case 1. Do not send is_exempt_foreign_person or other W-8 fields.

Case 2: name, address, foreign tax ID and the foreign status certification

Send everything in Case 1. Also send the foreign status certification:

  • is_exempt_foreign_person: true when the customer certifies that they are not a U.S. person and are the beneficial owner of the income.

Through the API, send this field alone or with the full W-8 field set. See API: send the field alone or the full set.

Do not send is_not_subject_backup_withholding for a non-U.S. person. Send one certification field only.

If you send a mailing_address that is different from the residential address, zerohash puts it on the W-8BEN.

Show the certification to the customer

For Case 2, collect the certification from the customer in your UI. Show the certification statement next to the checkbox. Use the Certification section of IRS Form W-8BEN as your reference. Tell the customer to inform you within 30 days if their circumstances change.

The zerohash Onboarding SDK shows this text, with the checkbox selected by default:

I am not a U.S. person and I am the beneficial owner of this income.

Keep checked if you are an exempt foreign person for broker transactions.

To see how the SDK collects this data, see Tax Data Collection - KYCaaS.

What zerohash creates for you

zerohash fills in the W-8BEN fields when it saves the record. It does this when:

  • a customer certifies in the Onboarding SDK, or
  • your API request sends is_exempt_foreign_person: true and tax_id, without the other W-8 fields.
FieldWhat zerohash sets
w8_ben.ftinThe tax ID that the customer enters
w8_ben.ftin_requiredtrue
w8_ben.treaty_claimNo treaty claim
signatureThe participant's first and last name
signature_timestampThe time that zerohash saves the record. Through the API, you can send your own value
w_form_certificationThe same time as signature_timestamp
is_w_form_certifiedtrue

API: send the field alone or the full set

Through the API, zerohash creates the W-8BEN fields only when your request has is_exempt_foreign_person and none of these fields:

  • w8_ben
  • signature
  • w_form_certification
  • is_w_form_certified
  • b_notice_receipt
  • payee_exemption
  • fatca_reporting_exemption

zerohash builds w8_ben from the participant's tax_id. If the participant has no tax_id, zerohash cannot create the W-8BEN.

If your request has one of these fields, zerohash does not create the others. It checks your request against the full W-8 field set, as before: w8_ben, signature, signature_timestamp, w_form_certification and is_w_form_certified. If you send only some of them, zerohash can reject the request.

If the customer's country does not issue a tax ID, send the full field set, with w8_ben.ftin_required: false.

Use the actual signing time

You can send signature_timestamp with is_exempt_foreign_person. zerohash still creates the other fields and uses your time for w_form_certification. Send the time that the customer certified when it is earlier than your API call, for example in a backfill. Use milliseconds since the Unix epoch.

🚧

The signing year sets the W-8 expiry date

A W-8 is valid until December 31 of the third year after the year it is signed. If the customer signs on December 31 and you send a January 1 time, the W-8 expires one year later than it should. To keep the expiry date correct, send the actual signing time.

Why zerohash no longer collects treaty claims

Treaty benefits reduce U.S. withholding on passive income, such as interest, dividends and royalties. Form 1099-DA reports gross proceeds from digital asset sales, so treaty benefits do not apply to it. A customer who wants a treaty benefit claims it on their own tax return.

The Onboarding SDK does not collect a treaty claim. Through the API, leave out treaty_claim if the customer claims no treaty benefit.

Request examples

Create a non-U.S. individual (Case 2, API)

Example POST /participants/customers/new request:

{
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "[email protected]",
  "address_one": "10 Downing St",
  "city": "London",
  "zip": "SW1A 2AA",
  "jurisdiction_code": "GB",
  "phone_number": "442012345678",
  "date_of_birth": "1985-06-12",
  "id_number_type": "non_us_passport",
  "id_number": "987654321",
  "id_issuing_authority": "GB",
  "citizenship_code": "GB",
  "tax_id": "QQ123456C",
  "signed_timestamp": 1747130096000,
  "kyc": "pass",
  "kyc_timestamp": 1747130096000,
  "sanction_screening": "pass",
  "sanction_screening_timestamp": 1747130096000,
  "signed_agreements": [
    {
      "type": "user_agreement",
      "region": "uk",
      "signed_timestamp": 1747130096000
    }
  ],
  "is_exempt_foreign_person": true
}

For Case 1, send the same request without is_exempt_foreign_person.

Update an existing non-U.S. individual (Case 2, API)

Example PATCH /participants/customers/{participant_code} request:

{
  "is_exempt_foreign_person": true,
  "signature_timestamp": 1667504636159
}

signature_timestamp is optional. Send it when the customer certified before your API call. To add a missing foreign tax ID, include tax_id. zerohash needs a tax_id on file to create the W-8BEN.

Fields you no longer need to send for individuals

zerohash still accepts all of these fields. Existing integrations keep working without changes. There is no migration deadline. If you send a field, zerohash uses your value.

FieldWhat zerohash sets (Onboarding SDK and API)
w8_ben.treaty_claim.*Not set. zerohash no longer collects treaty claims
w8_ben (ftin, ftin_required)ftin from the participant's tax_id, ftin_required: true
signatureThe participant's first and last name
signature_timestampThe time it saves the record, unless you send a time
w_form_certificationThe same time as signature_timestamp
is_w_form_certifiedtrue

Through the API, zerohash sets these values only when your request has no W-8 field other than is_exempt_foreign_person and signature_timestamp. See API: send the field alone or the full set.

Do you already collect certified W-8 forms?

If you collect signed W-8 forms yourself:

  1. Upload each form with POST /participants/documents and the correct document type.
  2. For individuals, send is_exempt_foreign_person.
  3. Send signature_timestamp with the date that the customer signed the form. This date sets the expiry date.

zerohash accepts these document types:

  • form_w8_ben
  • form_w8_ben_e
  • form_w8_imy
  • form_w8_eci
  • form_w8_exp
  • form_w8_ce

Do this for existing customers, and for each new customer.

Deadlines for existing participants

For Case 2:

  • You can send is_exempt_foreign_person now.
  • Send it for each non-U.S. individual onboarded on or after January 1, 2026. The deadline is 7:00 PM UTC on December 31, 2026.
  • If zerohash does not have the field by then, zerohash locks the participant on January 1, 2027. When zerohash gets the field, it changes the status back to approved automatically.
  • Participants onboarded before January 1, 2026 have until December 31, 2027. zerohash does not lock them on January 1, 2027.

For Case 1:

  • You can send a missing tax_id now.
  • From January 1, 2027, send name, address and tax_id for every new participant at onboarding.
  • zerohash does not restrict existing participants who have no tax_id. Missing data makes year-end tax reports incomplete. zerohash shares reconciliation reports that list the participants with missing data.

To check a participant's status, use GET /participant/{participant_code}/basic_info. For status definitions, see Participant and Account Statuses and Locking.

Backfill existing participants

You can send the missing data in these ways:

The API rate limit is 2,000 requests per rolling 10 seconds per IP address. The limit applies across all endpoints and includes your live traffic. Plan your backfill to stay under it. To retry safely, see Request IDs and idempotency.

Entity participants (W-8BEN-E)

W-8BEN-E requirements do not change. For each non-U.S. entity, send the full W-8BEN-E data.

Collect these data points in your UI:

  • Foreign TIN: the tax ID issued by the entity's country of tax residence.
  • FTIN not legally required: set this if the country does not issue or require a foreign TIN.
  • Mailing address, if it is different from the address of the entity.
  • Tax classification.
  • Treaty benefits claim, if the entity claims reduced withholding under an income tax treaty:
    • treaty country
    • treaty article and paragraph
    • withholding rate claimed
    • type of income
    • residence certification: the entity certifies that it is a tax resident of the treaty country
    • treaty requirements certification: the entity certifies that it meets the requirements of the treaty provision
    • Limitation on Benefits (LOB) provision: the LOB article that qualifies the entity for treaty benefits. See the Claim of Tax Treaty Benefits section of IRS Form W-8BEN-E.
    • LOB "Other" article and paragraph: free text, only when LOB is "Other"
    • additional conditions: shows that the entity meets any additional conditions in the treaty article

Show a W-8BEN-E certification checkbox in your UI. For the certification language, see the Certification section of IRS Form W-8BEN-E.

For entities, always send is_w_form_certified with w_form_certification, and signature with signature_timestamp. Every W-8BEN-E must include a tax_classification.

Create an entity

Example POST /participants/entity/new request:

{
  "platform_code": "PLAT01",
  "entity_name": "Acme Family Trust",
  "legal_name": "Acme Family Trust",
  "contact_number": "442012345678",
  "website": "acme.co.uk",
  "date_established": "2005-04-15",
  "entity_type": "trust_estate",
  "address_one": "10 Downing St",
  "address_two": null,
  "city": "London",
  "postal_code": "SW1A 2AA",
  "tax_id": null,
  "id_issuing_authority": null,
  "risk_rating": null,
  "sanction_screening": "pass",
  "sanction_screening_timestamp": 1747130096000,
  "self_certification_timestamp": 1747130096000,
  "signed_timestamp": 1747130096000,
  "signed_agreements": [
    {
      "type": "user_agreement",
      "region": "uk",
      "signed_timestamp": 1747130096000
    }
  ],
  "submitter_email": "[email protected]",
  "submitter_first_name": "Jane",
  "submitter_last_name": "Doe",
  "submitter_title": "Trustee",
  "control_persons": [
    {
      "name": "Jane Doe",
      "email": "[email protected]",
      "address_one": "10 Downing St",
      "address_two": null,
      "city": "London",
      "postal_code": "SW1A 2AA",
      "jurisdiction_code": "GB",
      "date_of_birth": "1980-03-22",
      "phone_number": "442012345678",
      "citizenship_code": "GB",
      "tax_id": null,
      "id_number_type": "passport",
      "id_number": "987654321",
      "id_issuing_authority": null,
      "sanction_screening": "pass",
      "sanction_screening_timestamp": 1747130096000,
      "kyc": "pass",
      "kyc_timestamp": 1747130096000,
      "control_person": 1
    }
  ],
  "beneficial_owners": [
    {
      "name": "Jane Doe",
      "email": "[email protected]",
      "address_one": "10 Downing St",
      "address_two": null,
      "city": "London",
      "postal_code": "SW1A 2AA",
      "jurisdiction_code": "GB",
      "date_of_birth": "1980-03-22",
      "phone_number": "442012345678",
      "citizenship_code": "GB",
      "tax_id": null,
      "id_number_type": "passport",
      "id_number": "987654321",
      "id_issuing_authority": null,
      "sanction_screening": "pass",
      "sanction_screening_timestamp": 1747130096000,
      "kyc": "pass",
      "kyc_timestamp": 1747130096000,
      "beneficial_owner": 1,
      "role": "Trustee"
    }
  ],
  "incorporation_address": {
    "address_one": "10 Downing St",
    "address_two": null,
    "city": "London",
    "jurisdiction_code": "GB",
    "postal_code": "SW1A 2AA"
  },
  "mailing_address": {
    "address_one": "PO Box 99",
    "address_two": null,
    "city": "London",
    "state": null,
    "postal_code": "EC1A 1BB",
    "country": "GB"
  },
  "is_w_form_certified": true, // must be true, required for proper W-8 generation
  "w_form_certification": 1747130096000, // required for proper W-8 generation
  "signature": "signature_data", // required for proper W-8 generation
  "signature_timestamp": 1747130096000, // required for proper W-8 generation
  "jurisdiction_code": "GB",
  "w8_ben_e": { // required for proper W-8 generation
    "tax_classification": "COMPLEX_TRUST", // required for proper W-8 generation
    "ftin": "GB987654321",
    "ftin_required": true, // must be specified
    "reference_numbers": "ACME-TRUST-1", // optional
    "treaty_claim": { // required for proper W-8 generation
      "is_eligible": true, // must be true, required for proper W-8 generation
      "country": "GB", // required for proper W-8 generation
      "residence_certification": true, // must be true, required for proper W-8 generation
      "requirements_certification": true, // must be true, required for proper W-8 generation
      "limitation_on_benefits": "PUBLICLY_TRADED_CORPORATION", // optional
      "limitation_on_benefits_other": null, // optional
      "income_type": null, // optional
      "withholding_rate": null, // optional
      "article_paragraph": null, // optional
      "additional_conditions": false // optional
    }
  }
}

Update an existing entity

Example PATCH /participants/entity/{participant_code} request:

{
  "is_w_form_certified": true, // must be true, required for proper W-8 generation
  "w_form_certification": 1667504636159, // required for proper W-8 generation
  "signature": "signature_data", // required for proper W-8 generation
  "signature_timestamp": 1667504636159, // required for proper W-8 generation
  "mailing_address": {
    "address_one": "PO Box 99",
    "address_two": null,
    "city": "London",
    "state": null,
    "postal_code": "EC1A 1BB",
    "country": "GB"
  },
  "w8_ben_e": { // required for proper W-8 generation
    "tax_classification": "COMPLEX_TRUST", // required for proper W-8 generation
    "ftin": "GB123456789",
    "ftin_required": true, // must be specified
    "reference_numbers": "ACME-ENTITY-7", // optional
    "treaty_claim": { // required for proper W-8 generation
      "is_eligible": true, // required for proper W-8 generation
      "country": "GB", // required for proper W-8 generation
      "residence_certification": true, // required for proper W-8 generation
      "requirements_certification": true, // required for proper W-8 generation
      "limitation_on_benefits": "PUBLICLY_TRADED_CORPORATION", // optional
      "limitation_on_benefits_other": null, // optional
      "income_type": "BUSINESS_PROFITS", // optional
      "withholding_rate": "0", // optional
      "article_paragraph": "Article 7, paragraph 1", // optional
      "additional_conditions": false // optional
    }
  }
}

Send updates as you do today

If a customer's tax information changes, update the participant record. Examples are a name change, an address change, a new country of residence, a new treaty status or a new certification. Use PATCH /participants/customers/{participant_code} for individuals. Use PATCH /participants/entity/{participant_code} for entities. zerohash certifies the record again.

To keep a W-8 valid, collect a new certification before it expires. zerohash treats an expired W-8 as missing and applies 24% backup withholding.

Updated 9 days ago

Did this page help you?