Deel: Workers schemas
48 Deel schemas with complete fields and constraints.
← Workers operations · All schemas
Complete individual contractor profile setup — 200 response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
data | Model | Required within parent | Expand Complete individual contractor profile setup — 200 response body — data |
Referenced models: Complete individual contractor profile setup — 200 response body — data
Complete individual contractor profile setup — 200 response body — data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
abn | string | Optional | Australian Business Number (11 digits). |
address_confirmed_by_user | boolean | Optional | Whether the user has confirmed the address is correct. |
address_valid | boolean | Optional | Whether the provided address has been validated. |
citizen | string | Optional | Citizenship country as an ISO 3166-1 alpha-2 code. |
city | string | Optional | City of residence. |
company_type | string | Required within parent | Type of company set up for the contractor. |
country | string | Optional | Country of residence as an ISO 3166-1 alpha-2 code. |
entity_tax_residence | string | Optional | Tax residence country for the entity, if different from the individual. |
id_type | string | Optional | Type of identification document provided. |
legal_status | string | Optional | Legal status of the individual contractor. |
onboarding_step | JSON | Optional | |
onboarding_step (anyOf 1) | string | Alternative | Current onboarding step after setup completes. |
onboarding_step (anyOf 2) | null | Alternative | Current onboarding step after setup completes. |
personal_id | string | Optional | Passport or national ID number. |
phone | string | Optional | Phone number in E.164 format. |
profile_id | JSON | Required within parent | |
profile_id (anyOf 1) | integer | Alternative | Internal profile identifier for the contractor. |
profile_id (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
province | string | Optional | Province or state code within the country. |
ssn | string | Optional | Social Security Number (9 digits). |
street | string | Optional | Street address of the contractor. |
tax_residence | string | Optional | Tax residence country as an ISO 3166-1 alpha-2 code. |
timezone | string | Optional | IANA timezone identifier. |
zip | string | Optional | Postal or ZIP code. |
Complete individual contractor profile setup — request body — body data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
abn | string | Optional | Australian Business Number (11 digits). Required when tax_residence is AU. |
address_confirmed_by_user | boolean | Optional | Whether the user has confirmed the address is correct. |
address_valid | boolean | Optional | Whether the provided address has been validated. |
citizen | string | Required within parent | Citizenship country as an ISO 3166-1 alpha-2 code. |
city | string | Required within parent | City of residence. |
country | string | Required within parent | Country of residence as an ISO 3166-1 alpha-2 code. |
entity_tax_residence | string | Optional | Tax residence country for the entity, if different from the individual. |
id_type | string | Optional | Type of identification document provided. |
legal_status | string | Required within parent | Legal status of the individual contractor. |
personal_id | string | Optional | Passport or national ID number. Required when tax_residence is not US. |
phone | string | Optional | Phone number in E.164 format. |
province | string | Optional | Province or state code within the country. |
ssn | string | Optional | Social Security Number (9 digits, no dashes). Required when tax_residence is US. |
street | string | Required within parent | Street address of the contractor. |
tax_residence | string | Optional | Tax residence country as an ISO 3166-1 alpha-2 code. Defaults to the country field if omitted. |
timezone | string | Optional | IANA timezone identifier. |
zip | string | Required within parent | Postal or ZIP code. |
Create a new worker — 201 response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
data | Model | Required within parent | Expand Create a new worker — 201 response body — data |
Referenced models: Create a new worker — 201 response body — data
Create a new worker — 201 response body — data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
contract_id | string | Required within parent | Associated contract ID Minimum length: 1 |
profile_id | string | Required within parent | Created profile ID Minimum length: 1 |
user_id | string | Required within parent | Created user ID Minimum length: 1 |
Create a new worker — request body — body data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
company | Model | Required within parent | Expand Create a new worker — request body — body data company |
contract_id | string | Required within parent | Associated contract ID Minimum length: 1 |
email | string | Required within parent | Worker's email address Format: email Minimum length: 5 |
first_name | string | Required within parent | Worker's first name Minimum length: 1 |
last_name | string | Required within parent | Worker's last name Minimum length: 1 |
middle_name | string or null | Optional | Worker's middle name |
preferred_firstname | string or null | Optional | Worker's preferred first name |
preferred_lastName | string or null | Optional | Worker's preferred last name |
preferred_name | string or null | Optional | Worker's preferred name |
profile_type | string | Required within parent | Type of worker profile One of: CONTRACTOR, EOR |
timezone | string | Required within parent | Worker's timezone |
Referenced models: Create a new worker — request body — body data company
Create a new worker — request body — body data company
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
personal | Model | Required within parent | Expand Create a new worker — request body — body data company personal |
type | string | Required within parent | Type of company registration One of: COMPANY, INDIVIDUAL |
Referenced models: Create a new worker — request body — body data company personal
Create a new worker — request body — body data company personal
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
citizen | string | Required within parent | Citizenship country code |
city | string | Required within parent | City |
country | string | Optional | Country code |
entity_tax_residence | string | Optional | Entity tax residence (only applicable for company type) |
id_type | string | Optional | Type of identification |
legal_status | string | Optional | Legal status (required only when type is INDIVIDUAL) |
personal_id | number | Required within parent | Personal identification number Format: double |
phone | number | Required within parent | Phone number Format: double |
province | string or null | Optional | Province/State |
street | string | Required within parent | Street address |
tax_residence | string | Optional | Tax residence country code |
timezone | string | Optional | Personal timezone |
zip | number | Required within parent | Zip/Postal code Format: double |
Create a tax form for the authenticated worker — 201 response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
data | Model | Required within parent | Expand Create a tax form for the authenticated worker — 201 response body — data |
Referenced models: Create a tax form for the authenticated worker — 201 response body — data
Create a tax form for the authenticated worker — 201 response body — data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
created_at | string | Required within parent | Timestamp of when the tax form was created. Format: date-time |
id | string | Required within parent | The public ID (UUID) of the created tax form. Format: uuid |
Create a tax form for the authenticated worker — request body — body / data / fatca_status: ACTIVE NFFE, PASSIVE NFFE, form type: W8 BEN E tax number
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Foreign tax identifying number. At least one of us_tax_number, tax_number, or giin is required unless is_ftin_not_legally_required is true. |
type | string | Required within parent | Foreign tax ID type. One of: FTIN |
value | string | Required within parent | Foreign tax identifying number. Maximum length: 20 |
Create a tax form for the authenticated worker — request body — body / data / fatca_status: ACTIVE NFFE, PASSIVE NFFE, form type: W8 BEN E tax treaty benefits form Tax treaty benefits details
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Tax treaty benefits details. |
article_and_paragraph | string | Optional | Article and paragraph of the applicable tax treaty. Maximum length: 100 |
details | string | Optional | Additional details about the treaty claim. Maximum length: 400 |
is_tax_residency_certified | boolean or null | Optional | Whether tax residency is certified. Default: false |
limitation_type | JSON | Optional | Limitation on benefits (LOB) type. |
limitation_type (oneOf 1) | string | Alternative | Limitation on benefits (LOB) type. One of: GOVERNMENT, PENSION_TRUST, TAX_EXEMPT, PUBLICLY_TRADED_CORPORATION, SUBSIDIARY, OWNERSHIP_TEST, DERIVATIVE_TEST, ACTIVE_TRADE_TEST, FAVORABLE, NO_ARTICLE, OTHER |
limitation_type (oneOf 2) | null | Alternative | |
other_article_and_paragraph | string or null | Optional | Other article and paragraph. Required when limitation_type is 'OTHER'. Maximum length: 50 |
owner_resident_country | string | Optional | Country of residence of the beneficial owner. Maximum length: 2 Minimum length: 2 Pattern: ^[A-Z]{2}$ |
type_of_income | string | Optional | Type of income covered by the treaty. Maximum length: 25 |
withholding_rate | number | Optional | Withholding rate under the treaty (percentage). Format: double Maximum: 100 Minimum: 0 |
Create a tax form for the authenticated worker — request body — body / data / form_type: W8 BEN mailing address address, address line2, city, country, state, zip code
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Mailing address if different from permanent residence. |
address | string | Required within parent | Mailing address. Maximum length: 100 |
address_line2 | string or null | Optional | Mailing address line 2. Maximum length: 100 |
city | string or null | Optional | Mailing address city. Maximum length: 50 Minimum length: 1 |
country | string | Required within parent | ISO 3166-1 alpha-2 country code. Maximum length: 2 Minimum length: 2 Pattern: ^[A-Z]{2}$ |
state | string or null | Optional | Mailing address state. Maximum length: 10 |
zip_code | string | Required within parent | Mailing address ZIP/postal code. |
Create a tax form for the authenticated worker — request body — body / data / form_type: W8 BEN tax number
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Foreign tax identifying number. At least one of us_tax_number or tax_number is required unless is_ftin_not_legally_required is true. |
type | string | Required within parent | Foreign tax ID type. One of: FTIN |
value | string | Required within parent | Foreign tax identifying number. Maximum length: 20 |
Create a tax form for the authenticated worker — request body — body / data / form_type: W8 BEN tax treaty benefits form article and paragraph, details, owner resident country, type of income, withholding rate
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Tax treaty benefits details. Applicable when is_tax_treaty_enabled is true. |
article_and_paragraph | string | Optional | Article and paragraph of the applicable tax treaty. Maximum length: 100 |
details | string | Optional | Additional details about the treaty claim. Maximum length: 400 |
owner_resident_country | string | Optional | Country of residence of the beneficial owner. Must be a US income tax treaty country. Maximum length: 2 Minimum length: 2 Pattern: ^[A-Z]{2}$ |
type_of_income | string | Optional | Type of income covered by the treaty. Maximum length: 100 |
withholding_rate | number | Optional | Withholding rate under the treaty (percentage). Format: double Maximum: 100 Minimum: 0 |
Create a tax form for the authenticated worker — request body — body / data / form_type: W8 BEN us tax number
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | US Taxpayer Identification Number. |
type | string | Required within parent | US tax ID type. One of: SSN, ITIN |
value | string | Required within parent | US tax ID value. |
Create a tax form for the authenticated worker — request body — body / data / form_type: W9 COMPANY federal tax classification
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Federal tax classification. |
llc_classification | string | Optional | LLC sub-classification. Required when type is 'LLC'. One of: P, S, C |
other_additional_information | string | Optional | Additional information. Required when type is 'OTHER'. Maximum length: 100 |
type | string | Required within parent | Federal tax classification type. One of: C_CORPORATION, S_CORPORATION, OTHER, PARTNERSHIP, LLC, TRUST_ESTATE |
Create a tax form for the authenticated worker — request body — body / data / form_type: W9 COMPANY tax number
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Taxpayer identification number. |
type | string | Required within parent | Tax ID type. EIN for most entities; SSN/ITIN/EIN for LLC. One of: SSN, ITIN, EIN |
value | string | Required within parent | Tax ID value. |
Create a tax form for the authenticated worker — request body — body / data / form_type: W9 INDIVIDUAL tax number
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Taxpayer identification number. |
type | string | Required within parent | Tax ID type. SSN/ITIN for individuals; EIN also allowed for disregarded entities. One of: SSN, ITIN, EIN |
value | string | Required within parent | Tax ID value. |
Create a tax form for the authenticated worker — request body — body data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | discriminator: {"propertyName": "form_type"} |
$ (oneOf 1) | object | Alternative | W9_INDIVIDUAL variant |
$ (oneOf 1).address | string | Required within parent | Street address. Maximum 40 characters for 1099 reporting compliance. Maximum length: 40 |
$ (oneOf 1).business_name | string or null | Optional | Business name. Only applicable when is_disregarded_entity is true. Maximum length: 40 |
$ (oneOf 1).city | string | Required within parent | City name. Maximum length: 40 Minimum length: 1 |
$ (oneOf 1).client_legal_entity_id | string | Required within parent | Public ID of the client's legal entity. Format: uuid |
$ (oneOf 1).contractor_signature | string | Required within parent | Contractor's digital signature. Maximum length: 100 Minimum length: 1 |
$ (oneOf 1).country | string | Required within parent | ISO 3166-1 alpha-2 country code. Maximum length: 2 Minimum length: 2 Pattern: ^[A-Z]{2}$ |
$ (oneOf 1).first_name | string | Required within parent | Legal first name. Maximum length: 40 |
$ (oneOf 1).form_type | string | Required within parent | Discriminator value: W9_INDIVIDUAL One of: W9_INDIVIDUAL |
$ (oneOf 1).is_disregarded_entity | boolean | Optional | Whether this is a disregarded entity. Default: false |
$ (oneOf 1).is_subject_backup_withholding | boolean | Optional | Whether the contractor is subject to backup withholding. Default: false |
$ (oneOf 1).last_name | string | Required within parent | Legal last name. Maximum length: 40 |
$ (oneOf 1).middle_name | string | Optional | Legal middle name. Maximum length: 100 |
$ (oneOf 1).state | string or null | Optional | US state code. Maximum length: 10 |
$ (oneOf 1).tax_number | Model | Required within parent | Expand Create a tax form for the authenticated worker — request body — body / data / form_type: W9 INDIVIDUAL tax number Taxpayer identification number. |
$ (oneOf 1).zip_code | string | Required within parent | ZIP/postal code. Must be a valid US ZIP code for US addresses. |
$ (oneOf 2) | object | Alternative | W9_COMPANY variant |
$ (oneOf 2).address | string | Required within parent | Street address. Maximum length: 40 |
$ (oneOf 2).business_name | string | Required within parent | Business name. Maximum length: 40 Minimum length: 1 |
$ (oneOf 2).city | string | Required within parent | City name. Maximum length: 40 Minimum length: 1 |
$ (oneOf 2).client_legal_entity_id | string | Required within parent | Public ID of the client's legal entity. Format: uuid |
$ (oneOf 2).contractor_signature | string | Required within parent | Authorized signer's digital signature. Maximum length: 100 Minimum length: 1 |
$ (oneOf 2).country | string | Required within parent | ISO 3166-1 alpha-2 country code. Maximum length: 2 Minimum length: 2 Pattern: ^[A-Z]{2}$ |
$ (oneOf 2).doing_business_as | string or null | Optional | DBA name. Maximum length: 50 |
$ (oneOf 2).federal_tax_classification | Model | Required within parent | Expand Create a tax form for the authenticated worker — request body — body / data / form_type: W9 COMPANY federal tax classification Federal tax classification. |
$ (oneOf 2).form_type | string | Required within parent | Discriminator value: W9_COMPANY One of: W9_COMPANY |
$ (oneOf 2).is_subject_backup_withholding | boolean | Optional | Whether the contractor is subject to backup withholding. Default: false |
$ (oneOf 2).state | string or null | Optional | US state code. Maximum length: 10 |
$ (oneOf 2).tax_number | Model | Required within parent | Expand Create a tax form for the authenticated worker — request body — body / data / form_type: W9 COMPANY tax number Taxpayer identification number. |
$ (oneOf 2).zip_code | string | Required within parent | ZIP/postal code. |
$ (oneOf 3) | object | Alternative | W8_BEN variant |
$ (oneOf 3).address | string | Required within parent | Street address. Maximum length: 100 |
$ (oneOf 3).address_line2 | string or null | Optional | Street address line 2. Maximum length: 100 |
$ (oneOf 3).city | string or null | Optional | City name. Maximum length: 50 Minimum length: 1 |
$ (oneOf 3).client_legal_entity_id | string | Required within parent | Public ID of the client's legal entity. Format: uuid |
$ (oneOf 3).contractor_signature | string | Required within parent | Contractor's digital signature. Maximum length: 100 Minimum length: 1 |
$ (oneOf 3).country | string | Required within parent | ISO 3166-1 alpha-2 country code of permanent residence. Maximum length: 2 Minimum length: 2 Pattern: ^[A-Z]{2}$ |
$ (oneOf 3).country_of_citizenship | string | Required within parent | ISO 3166-1 alpha-2 country code of citizenship. Maximum length: 2 Minimum length: 2 Pattern: ^[A-Z]{2}$ |
$ (oneOf 3).date_of_birth | string or null | Optional | Date of birth. Must be at least 18 years ago and no more than 100 years ago. Format: date-time |
$ (oneOf 3).first_name | string | Required within parent | Legal first name. Maximum length: 100 |
$ (oneOf 3).form_type | string | Required within parent | Discriminator value: W8_BEN One of: W8_BEN |
$ (oneOf 3).is_certified_and_agreed | boolean or null | Optional | Certification that the signer has read and agrees with the certification information. Default: false |
$ (oneOf 3).is_disregarded_entity | boolean | Optional | Whether this is a disregarded entity. Default: false |
$ (oneOf 3).is_ftin_not_legally_required | boolean | Optional | Check if FTIN is not legally required in your country of residence. Default: false |
$ (oneOf 3).is_tax_treaty_enabled | boolean or null | Optional | Whether the contractor claims tax treaty benefits. Default: false |
$ (oneOf 3).last_name | string | Required within parent | Legal last name. Maximum length: 100 |
$ (oneOf 3).mailing_address | JSON | Optional | Mailing address if different from permanent residence. |
$ (oneOf 3).mailing_address (oneOf 1) | Model | Alternative | Expand Create a tax form for the authenticated worker — request body — body / data / form_type: W8 BEN mailing address address, address line2, city, country, state, zip code |
$ (oneOf 3).mailing_address (oneOf 2) | null | Alternative | |
$ (oneOf 3).middle_name | string or null | Optional | Legal middle name. Maximum length: 100 |
$ (oneOf 3).print_name_of_signer | string or null | Optional | Printed name of the signer. Maximum length: 100 |
$ (oneOf 3).referencing_information | string or null | Optional | Reference number for the form. Maximum length: 100 |
$ (oneOf 3).state | string or null | Optional | State or province code. Maximum length: 10 |
$ (oneOf 3).tax_number | Model | Optional | Expand Create a tax form for the authenticated worker — request body — body / data / form_type: W8 BEN tax number Foreign tax identifying number. At least one of us_tax_number or tax_number is required unless is_ftin_not_legally_required is true. |
$ (oneOf 3).tax_treaty_benefits_form | JSON | Optional | Tax treaty benefits details. Applicable when is_tax_treaty_enabled is true. |
$ (oneOf 3).tax_treaty_benefits_form (oneOf 1) | Model | Alternative | Expand Create a tax form for the authenticated worker — request body — body / data / form_type: W8 BEN tax treaty benefits form article and paragraph, details, owner resident country, type of income, withholding rate |
$ (oneOf 3).tax_treaty_benefits_form (oneOf 2) | null | Alternative | |
$ (oneOf 3).us_tax_number | Model | Optional | Expand Create a tax form for the authenticated worker — request body — body / data / form_type: W8 BEN us tax number US Taxpayer Identification Number. |
$ (oneOf 3).zip_code | string | Required within parent | ZIP/postal code. |
$ (oneOf 4) | object | Alternative | W8_BEN_E variant |
$ (oneOf 4).address | string | Required within parent | Street address. Maximum length: 100 |
$ (oneOf 4).address_line2 | string or null | Optional | Street address line 2. Maximum length: 100 |
$ (oneOf 4).city | string | Required within parent | City of residence. Maximum length: 50 Minimum length: 1 |
$ (oneOf 4).client_legal_entity_id | string | Required within parent | Public ID of the client's legal entity. Format: uuid |
$ (oneOf 4).contractor_signature | string | Required within parent | Authorized signer's digital signature. Maximum length: 100 Minimum length: 1 |
$ (oneOf 4).country | string | Required within parent | ISO 3166-1 alpha-2 country code of permanent residence. Maximum length: 2 Minimum length: 2 Pattern: ^[A-Z]{2}$ |
$ (oneOf 4).country_of_citizenship | string | Required within parent | ISO 3166-1 alpha-2 country code of incorporation/organization. Maximum length: 2 Minimum length: 2 Pattern: ^[A-Z]{2}$ |
$ (oneOf 4).date_of_birth | string or null | Optional | Date of birth of the beneficial owner. Format: date-time |
$ (oneOf 4).entity_country | string or null | Required within parent | ISO 3166-1 alpha-2 country code of the entity. Maximum length: 2 Minimum length: 2 Pattern: ^[A-Z]{2}$ |
$ (oneOf 4).entity_type | string | Required within parent | Chapter 3 entity type. One of: CORPORATION, DISREGARDED_ENTITY, PARTNERSHIP, SIMPLE_TRUST, GRANTOR_TRUST, COMPLEX_TRUST, ESTATE, GOVERNMENT, CENTRAL_BANK_OF_ISSUE, TAX_EXEMPT, PRIVATE_FOUNDATION, INTERNATIONAL, FOREIGN_GOVERNMENT_CONTROLLED, FOREIGN_GOVERNMENT_INTEGRAL |
$ (oneOf 4).fatca_status | string | Required within parent | FATCA (Foreign Account Tax Compliance Act) status. One of: ACTIVE_NFFE, PASSIVE_NFFE |
$ (oneOf 4).form_type | string | Required within parent | Discriminator value: W8_BEN_E One of: W8_BEN_E |
$ (oneOf 4).giin | string or null | Optional | Global Intermediary Identification Number (19 characters). Maximum length: 19 Minimum length: 19 |
$ (oneOf 4).has_substantial_us_owner | boolean | Optional | Whether the entity has a substantial US owner. Required when fatca_status is 'PASSIVE_NFFE'. Default: false |
$ (oneOf 4).is_entity_certification_confirmed | boolean or null | Optional | Certification that the entity is the beneficial owner of all income. Default: false |
$ (oneOf 4).is_ftin_not_legally_required | boolean | Optional | Check if FTIN is not legally required in your country. Default: false |
$ (oneOf 4).is_tax_treaty_enabled | boolean or null | Optional | Whether the entity claims tax treaty benefits. Default: false |
$ (oneOf 4).mailing_address | JSON | Optional | Mailing address if different from permanent residence. |
$ (oneOf 4).mailing_address (oneOf 1) | Model | Alternative | Expand Create a tax form for the authenticated worker — request body — body / data / form_type: W8 BEN mailing address address, address line2, city, country, state, zip code |
$ (oneOf 4).mailing_address (oneOf 2) | null | Alternative | |
$ (oneOf 4).name_of_disregarded_entity | string or null | Optional | Name of the disregarded entity, if applicable. Maximum length: 100 |
$ (oneOf 4).name_of_organization | string | Required within parent | Name of the organization. Maximum length: 100 |
$ (oneOf 4).print_name_of_signer | string or null | Optional | Printed name of the authorized signer. Maximum length: 100 |
$ (oneOf 4).referencing_information | string or null | Optional | Reference number for the form. Maximum length: 100 |
$ (oneOf 4).state | string or null | Optional | State or province code. Maximum length: 10 |
$ (oneOf 4).tax_number | Model | Optional | Expand Create a tax form for the authenticated worker — request body — body / data / fatca_status: ACTIVE NFFE, PASSIVE NFFE, form type: W8 BEN E tax number Foreign tax identifying number. At least one of us_tax_number, tax_number, or giin is required unless is_ftin_not_legally_required is true. |
$ (oneOf 4).tax_treaty_benefits_form | JSON | Optional | Tax treaty benefits details. |
$ (oneOf 4).tax_treaty_benefits_form (oneOf 1) | Model | Alternative | Expand Create a tax form for the authenticated worker — request body — body / data / fatca_status: ACTIVE NFFE, PASSIVE NFFE, form type: W8 BEN E tax treaty benefits form Tax treaty benefits details |
$ (oneOf 4).tax_treaty_benefits_form (oneOf 2) | null | Alternative | |
$ (oneOf 4).us_tax_number | Model | Optional | Expand Create a tax form for the authenticated worker — request body — body / data / form_type: W8 BEN us tax number US Taxpayer Identification Number. |
$ (oneOf 4).zip_code | string | Required within parent | ZIP/postal code. |
Referenced models: Create a tax form for the authenticated worker — request body — body / data / form_type: W9 INDIVIDUAL tax number, Create a tax form for the authenticated worker — request body — body / data / form_type: W9 COMPANY federal tax classification, Create a tax form for the authenticated worker — request body — body / data / form_type: W9 COMPANY tax number, Create a tax form for the authenticated worker — request body — body / data / form_type: W8 BEN mailing address address, address line2, city, country, state, zip code, Create a tax form for the authenticated worker — request body — body / data / form_type: W8 BEN tax number, Create a tax form for the authenticated worker — request body — body / data / form_type: W8 BEN tax treaty benefits form article and paragraph, details, owner resident country, type of income, withholding rate, Create a tax form for the authenticated worker — request body — body / data / form_type: W8 BEN us tax number, Create a tax form for the authenticated worker — request body — body / data / fatca_status: ACTIVE NFFE, PASSIVE NFFE, form type: W8 BEN E tax number, Create a tax form for the authenticated worker — request body — body / data / fatca_status: ACTIVE NFFE, PASSIVE NFFE, form type: W8 BEN E tax treaty benefits form Tax treaty benefits details
Get a download URL for one compliance document of a worker contract — 200 response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
data | Model | Required within parent | Expand Get a download URL for one compliance document of a worker contract — 200 response body — data |
Referenced models: Get a download URL for one compliance document of a worker contract — 200 response body — data
Get a download URL for one compliance document of a worker contract — 200 response body — data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
expires_at | JSON | Required within parent | |
expires_at (anyOf 1) | string | Alternative | When the URL stops working. Null when the URL is not time-limited. Format: date-time |
expires_at (anyOf 2) | null | Alternative | When the URL stops working. Null when the URL is not time-limited. Format: date-time |
is_external_url | JSON | Optional | |
is_external_url (anyOf 1) | boolean | Alternative | Reserved. Not populated on this endpoint today. |
is_external_url (anyOf 2) | null | Alternative | Reserved. Not populated on this endpoint today. |
updated_at | JSON | Optional | |
updated_at (anyOf 1) | string | Alternative | Reserved. Not populated on this endpoint today. Format: date-time |
updated_at (anyOf 2) | null | Alternative | Reserved. Not populated on this endpoint today. Format: date-time |
url | string | Required within parent | Time-limited download URL, valid for about 15 minutes. Fetch it rather than storing it. |
Get invoice details by ID — 200 response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
data | Model | Required within parent | Expand Get invoice details by ID — 200 response body — data Invoice summary (snake_case; display card fields, amounts, and payment display). |
Referenced models: Get invoice details by ID — 200 response body — data
Get invoice details by ID — 200 response body — data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Invoice summary (snake_case; display card fields, amounts, and payment display). |
amount | JSON | Optional | |
amount (anyOf 1) | string | Alternative | Amount before fees. |
amount (anyOf 2) | null | Alternative | Amount before fees. |
created_at | string | Required within parent | When the invoice record was created (ISO-8601). Format: date-time |
currency | string | Required within parent | Three-letter currency code. Maximum length: 3 Minimum length: 3 Pattern: ^[A-Z]{3}$ |
id | string | Required within parent | Public invoice id. |
issued_at | JSON | Optional | |
issued_at (anyOf 1) | string | Alternative | When the invoice was issued, if applicable. Format: date-time |
issued_at (anyOf 2) | null | Alternative | When the invoice was issued, if applicable. Format: date-time |
payment_display_status | Model | Optional | Expand Get invoice details by ID — 200 response body — data payment display status Derived payment display state for the invoice. |
status | string | Required within parent | Invoice workflow status. |
title | string | Optional | Display title. |
total | JSON | Optional | |
total (anyOf 1) | string | Alternative | Total including fees. |
total (anyOf 2) | null | Alternative | Total including fees. |
Referenced models: Get invoice details by ID — 200 response body — data payment display status
Get invoice details by ID — 200 response body — data payment display status
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Derived payment display state for the invoice. |
key | string | Required within parent | Stable machine key. |
label | string | Required within parent | Human-readable label. |
List compliance documents of a worker contract — 200 response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
data | array | Required within parent | Documents on this page. |
data[] | Model | Each item | Expand Retrieve one compliance document of a worker contract — 200 response body — data |
has_more | boolean | Required within parent | Whether another page follows this one. |
next_cursor | JSON | Required within parent | |
next_cursor (anyOf 1) | string | Alternative | Opaque token to pass as `cursor` to fetch the next page. Null on the last page. Never construct or parse one. |
next_cursor (anyOf 2) | null | Alternative | Opaque token to pass as `cursor` to fetch the next page. Null on the last page. Never construct or parse one. |
total_count | JSON | Required within parent | |
total_count (anyOf 1) | integer | Alternative | Total number of documents for the contract, across every page. Minimum: 0 |
total_count (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
Referenced models: Retrieve one compliance document of a worker contract — 200 response body — data
List of worker compliance documents — 200 response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
data | Model | Required within parent | Expand List of worker compliance documents — 200 response body — data |
Referenced models: List of worker compliance documents — 200 response body — data
List of worker compliance documents — 200 response body — data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
documents | array | Required within parent | List of compliance documents required for the worker. |
documents[] | Model | Each item | Expand List of worker compliance documents — 200 response body — data documents item |
Referenced models: List of worker compliance documents — 200 response body — data documents item
List of worker compliance documents — 200 response body — data documents item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
country | JSON | Required within parent | |
country (anyOf 1) | string | Alternative | ISO 3166-1 alpha-2 country code where the document is required. |
country (anyOf 2) | null | Alternative | ISO 3166-1 alpha-2 country code where the document is required. |
description | string | Required within parent | Description of the document requirement. Empty string when no description exists. |
filenames | array | Required within parent | List of uploaded file names. Empty array when no files have been uploaded. |
filenames[] | string | Each item | |
fillable | boolean | Required within parent | Whether the document can be filled through the Deel platform. |
has_template | boolean | Required within parent | Whether a template is available for this document. |
id | string | Required within parent | Unique identifier for the compliance document requirement. Format: uuid |
is_acknowledgement_only_document | boolean | Required within parent | Whether this document only requires acknowledgement without file upload. |
is_consent_required | boolean | Optional | Whether consent is required for acknowledgement-only documents. Only present when is_acknowledgement_only_document is true. |
is_optional | boolean | Required within parent | Whether the document is optional for the worker. Also true when the document is required within 30 days. |
name | string | Required within parent | Display name of the compliance document. |
rejection_message | string | Required within parent | Plain text message explaining why the document was rejected. Empty string when no rejection message exists. |
required_in_30_days | boolean | Required within parent | Whether the document is required within 30 days of employment start. |
status | JSON | Required within parent | Review status of the uploaded document, null if no document has been uploaded yet. |
status (anyOf 1) | string | Alternative | Review status of the uploaded document, null if no document has been uploaded yet. Known values: AWAITING_EX_REVIEW, AWAITING_EXTERNAL_REVIEW, REJECTED, APPROVED, ON_HOLD |
status (anyOf 2) | null | Alternative | |
uploaded_at | JSON | Required within parent | |
uploaded_at (anyOf 1) | string | Alternative | ISO 8601 timestamp when the document was uploaded, null if no document has been uploaded. Format: date-time |
uploaded_at (anyOf 2) | null | Alternative | ISO 8601 timestamp when the document was uploaded, null if no document has been uploaded. Format: date-time |
List tax forms for the authenticated worker — 200 response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
data | array | Required within parent | The worker's tax forms, newest first. |
data[] | Model | Each item | Expand List tax forms for the authenticated worker — 200 response body — data item |
has_more | boolean | Required within parent | Whether more tax forms exist beyond this page. |
next_cursor | JSON | Required within parent | |
next_cursor (anyOf 1) | string | Alternative | Cursor to pass as the cursor query parameter to fetch the next page. Null when has_more is false. |
next_cursor (anyOf 2) | null | Alternative | Cursor to pass as the cursor query parameter to fetch the next page. Null when has_more is false. |
total_count | JSON | Required within parent | |
total_count (anyOf 1) | integer | Alternative | Total number of the worker's tax forms across all pages. |
total_count (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
Referenced models: List tax forms for the authenticated worker — 200 response body — data item
List tax forms for the authenticated worker — 200 response body — data / item / fatca_status: ACTIVE NFFE, PASSIVE NFFE, form type: W8 BEN E tax treaty benefits form article and paragraph, details, is tax residency certified, limitation type, other article and paragraph, owner resident country, type of income, withholding rate
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Tax treaty benefits details. Present when treaty benefits are claimed. |
article_and_paragraph | string | Optional | Article and paragraph of the applicable tax treaty. |
details | string | Optional | Additional details about the treaty claim. |
is_tax_residency_certified | JSON | Optional | |
is_tax_residency_certified (anyOf 1) | boolean | Alternative | Whether tax residency is certified. |
is_tax_residency_certified (anyOf 2) | null | Alternative | Whether tax residency is certified. |
limitation_type | JSON | Optional | Limitation on benefits (LOB) type. |
limitation_type (anyOf 1) | string | Alternative | Limitation on benefits (LOB) type. Known values: GOVERNMENT, PENSION_TRUST, TAX_EXEMPT, PUBLICLY_TRADED_CORPORATION, SUBSIDIARY, OWNERSHIP_TEST, DERIVATIVE_TEST, ACTIVE_TRADE_TEST, FAVORABLE, NO_ARTICLE, OTHER |
limitation_type (anyOf 2) | null | Alternative | |
other_article_and_paragraph | JSON | Optional | |
other_article_and_paragraph (anyOf 1) | string | Alternative | Other article and paragraph. Present when limitation_type is 'OTHER'. |
other_article_and_paragraph (anyOf 2) | null | Alternative | Other article and paragraph. Present when limitation_type is 'OTHER'. |
owner_resident_country | string | Optional | Country of residence of the beneficial owner. |
type_of_income | string | Optional | Type of income covered by the treaty. |
withholding_rate | JSON | Optional | |
withholding_rate (anyOf 1) | number | Alternative | Withholding rate under the treaty (percentage). Format: double |
withholding_rate (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
List tax forms for the authenticated worker — 200 response body — data / item / form_type: W8 BEN mailing address address, address line2, city, country, state, zip code
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Mailing address if different from permanent residence. Present on W8_BEN and W8_BEN_E forms. |
address | string | Optional | Mailing address. |
address_line2 | JSON | Optional | |
address_line2 (anyOf 1) | string | Alternative | Mailing address line 2. |
address_line2 (anyOf 2) | null | Alternative | Mailing address line 2. |
city | JSON | Optional | |
city (anyOf 1) | string | Alternative | Mailing address city. |
city (anyOf 2) | null | Alternative | Mailing address city. |
country | string | Optional | ISO 3166-1 alpha-2 country code. |
state | JSON | Optional | |
state (anyOf 1) | string | Alternative | Mailing address state. |
state (anyOf 2) | null | Alternative | Mailing address state. |
zip_code | string | Optional | Mailing address ZIP/postal code. |
List tax forms for the authenticated worker — 200 response body — data / item / form_type: W8 BEN tax number
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Foreign taxpayer identification number. Returned unmasked. |
type | string | Optional | Tax ID type. Known values: FTIN |
value | string | Optional | Tax ID value, unmasked. |
List tax forms for the authenticated worker — 200 response body — data / item / form_type: W8 BEN tax treaty benefits form article and paragraph, details, owner resident country, type of income, withholding rate
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Tax treaty benefits details. Present when treaty benefits are claimed. |
article_and_paragraph | string | Optional | Article and paragraph of the applicable tax treaty. |
details | string | Optional | Additional details about the treaty claim. |
owner_resident_country | string | Optional | Country of residence of the beneficial owner. |
type_of_income | string | Optional | Type of income covered by the treaty. |
withholding_rate | JSON | Optional | |
withholding_rate (anyOf 1) | number | Alternative | Withholding rate under the treaty (percentage). Format: double |
withholding_rate (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
List tax forms for the authenticated worker — 200 response body — data / item / form_type: W8 BEN us tax number
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | US Taxpayer Identification Number. Present on W8_BEN and W8_BEN_E forms. Returned unmasked. |
type | string | Optional | US tax ID type. Known values: SSN, ITIN |
value | string | Optional | US tax ID value, unmasked. |
List tax forms for the authenticated worker — 200 response body — data / item / form_type: W9 COMPANY federal tax classification
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Federal tax classification. Present on W9_COMPANY forms. |
llc_classification | string | Optional | LLC sub-classification. Present when type is 'LLC'. Known values: P, S, C |
other_additional_information | string | Optional | Additional information. Present when type is 'OTHER'. |
type | string | Optional | Federal tax classification type. Known values: C_CORPORATION, S_CORPORATION, OTHER, PARTNERSHIP, LLC, TRUST_ESTATE |
List tax forms for the authenticated worker — 200 response body — data / item / form_type: W9 COMPANY tax number
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Taxpayer identification number. Returned unmasked. |
type | string | Optional | Tax ID type. Known values: SSN, ITIN, EIN |
value | string | Optional | Tax ID value, unmasked. |
List tax forms for the authenticated worker — 200 response body — data item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | discriminator: {"propertyName": "form_type"} |
$ (anyOf 1) | object | Alternative | W9_INDIVIDUAL variant |
$ (anyOf 1).address | string | Optional | Street address of permanent residence. |
$ (anyOf 1).business_name | JSON | Optional | |
$ (anyOf 1).business_name (anyOf 1) | string | Alternative | Business name. Present on W9_COMPANY forms and disregarded-entity W9_INDIVIDUAL forms. |
$ (anyOf 1).business_name (anyOf 2) | null | Alternative | Business name. Present on W9_COMPANY forms and disregarded-entity W9_INDIVIDUAL forms. |
$ (anyOf 1).city | JSON | Optional | |
$ (anyOf 1).city (anyOf 1) | string | Alternative | City name. |
$ (anyOf 1).city (anyOf 2) | null | Alternative | City name. |
$ (anyOf 1).client_legal_entity_id | string | Required within parent | Public ID of the client's legal entity the form was submitted against. Format: uuid |
$ (anyOf 1).contractor_signature | string | Optional | The signer's digital signature. |
$ (anyOf 1).country | string | Optional | ISO 3166-1 alpha-2 country code of permanent residence. |
$ (anyOf 1).created_at | string | Required within parent | Timestamp of when the tax form was created. Format: date-time |
$ (anyOf 1).first_name | string | Optional | Legal first name. Present on W9_INDIVIDUAL and W8_BEN forms. |
$ (anyOf 1).form_type | string | Required within parent | Discriminator value: W9_INDIVIDUAL Known values: W9_INDIVIDUAL |
$ (anyOf 1).id | string | Required within parent | The public ID (UUID) of the tax form. Format: uuid |
$ (anyOf 1).is_disregarded_entity | boolean | Optional | Whether this is a disregarded entity. Present on W9_INDIVIDUAL and W8_BEN forms. |
$ (anyOf 1).is_subject_backup_withholding | boolean | Optional | Whether the contractor is subject to backup withholding. Present on W-9 forms. |
$ (anyOf 1).last_name | string | Optional | Legal last name. Present on W9_INDIVIDUAL and W8_BEN forms. |
$ (anyOf 1).middle_name | string | Optional | Legal middle name. Present on W9_INDIVIDUAL and W8_BEN forms. |
$ (anyOf 1).pdf_url | JSON | Optional | |
$ (anyOf 1).pdf_url (anyOf 1) | string | Alternative | Pre-signed download URL for the generated form PDF. The link expires about 15 minutes after the response is issued — download promptly or request the list again. Null while the PDF has not been generated yet. |
$ (anyOf 1).pdf_url (anyOf 2) | null | Alternative | Pre-signed download URL for the generated form PDF. The link expires about 15 minutes after the response is issued — download promptly or request the list again. Null while the PDF has not been generated yet. |
$ (anyOf 1).state | JSON | Optional | |
$ (anyOf 1).state (anyOf 1) | string | Alternative | State or province code. |
$ (anyOf 1).state (anyOf 2) | null | Alternative | State or province code. |
$ (anyOf 1).tax_number | Model | Optional | Expand List tax forms for the authenticated worker — 200 response body — data / item / form_type: W9 COMPANY tax number Taxpayer identification number. Returned unmasked. |
$ (anyOf 1).updated_at | string | Required within parent | Timestamp of when the tax form was last updated. Format: date-time |
$ (anyOf 1).zip_code | string | Optional | ZIP/postal code. |
$ (anyOf 2) | object | Alternative | W9_COMPANY variant |
$ (anyOf 2).address | string | Optional | Street address of permanent residence. |
$ (anyOf 2).business_name | JSON | Optional | |
$ (anyOf 2).business_name (anyOf 1) | string | Alternative | Business name. Present on W9_COMPANY forms and disregarded-entity W9_INDIVIDUAL forms. |
$ (anyOf 2).business_name (anyOf 2) | null | Alternative | Business name. Present on W9_COMPANY forms and disregarded-entity W9_INDIVIDUAL forms. |
$ (anyOf 2).city | JSON | Optional | |
$ (anyOf 2).city (anyOf 1) | string | Alternative | City name. |
$ (anyOf 2).city (anyOf 2) | null | Alternative | City name. |
$ (anyOf 2).client_legal_entity_id | string | Required within parent | Public ID of the client's legal entity the form was submitted against. Format: uuid |
$ (anyOf 2).contractor_signature | string | Optional | The signer's digital signature. |
$ (anyOf 2).country | string | Optional | ISO 3166-1 alpha-2 country code of permanent residence. |
$ (anyOf 2).created_at | string | Required within parent | Timestamp of when the tax form was created. Format: date-time |
$ (anyOf 2).doing_business_as | JSON | Optional | |
$ (anyOf 2).doing_business_as (anyOf 1) | string | Alternative | DBA name. Present on W9_COMPANY forms. |
$ (anyOf 2).doing_business_as (anyOf 2) | null | Alternative | DBA name. Present on W9_COMPANY forms. |
$ (anyOf 2).federal_tax_classification | Model | Optional | Expand List tax forms for the authenticated worker — 200 response body — data / item / form_type: W9 COMPANY federal tax classification Federal tax classification. Present on W9_COMPANY forms. |
$ (anyOf 2).form_type | string | Required within parent | Discriminator value: W9_COMPANY Known values: W9_COMPANY |
$ (anyOf 2).id | string | Required within parent | The public ID (UUID) of the tax form. Format: uuid |
$ (anyOf 2).is_subject_backup_withholding | boolean | Optional | Whether the contractor is subject to backup withholding. Present on W-9 forms. |
$ (anyOf 2).pdf_url | JSON | Optional | |
$ (anyOf 2).pdf_url (anyOf 1) | string | Alternative | Pre-signed download URL for the generated form PDF. The link expires about 15 minutes after the response is issued — download promptly or request the list again. Null while the PDF has not been generated yet. |
$ (anyOf 2).pdf_url (anyOf 2) | null | Alternative | Pre-signed download URL for the generated form PDF. The link expires about 15 minutes after the response is issued — download promptly or request the list again. Null while the PDF has not been generated yet. |
$ (anyOf 2).state | JSON | Optional | |
$ (anyOf 2).state (anyOf 1) | string | Alternative | State or province code. |
$ (anyOf 2).state (anyOf 2) | null | Alternative | State or province code. |
$ (anyOf 2).tax_number | Model | Optional | Expand List tax forms for the authenticated worker — 200 response body — data / item / form_type: W9 COMPANY tax number Taxpayer identification number. Returned unmasked. |
$ (anyOf 2).updated_at | string | Required within parent | Timestamp of when the tax form was last updated. Format: date-time |
$ (anyOf 2).zip_code | string | Optional | ZIP/postal code. |
$ (anyOf 3) | object | Alternative | W8_BEN variant |
$ (anyOf 3).address | string | Optional | Street address of permanent residence. |
$ (anyOf 3).address_line2 | JSON | Optional | |
$ (anyOf 3).address_line2 (anyOf 1) | string | Alternative | Street address line 2. Present on W8_BEN and W8_BEN_E forms. |
$ (anyOf 3).address_line2 (anyOf 2) | null | Alternative | Street address line 2. Present on W8_BEN and W8_BEN_E forms. |
$ (anyOf 3).city | JSON | Optional | |
$ (anyOf 3).city (anyOf 1) | string | Alternative | City name. |
$ (anyOf 3).city (anyOf 2) | null | Alternative | City name. |
$ (anyOf 3).client_legal_entity_id | string | Required within parent | Public ID of the client's legal entity the form was submitted against. Format: uuid |
$ (anyOf 3).contractor_signature | string | Optional | The signer's digital signature. |
$ (anyOf 3).country | string | Optional | ISO 3166-1 alpha-2 country code of permanent residence. |
$ (anyOf 3).country_of_citizenship | string | Optional | ISO 3166-1 alpha-2 country code of citizenship (W8_BEN) or incorporation (W8_BEN_E). |
$ (anyOf 3).created_at | string | Required within parent | Timestamp of when the tax form was created. Format: date-time |
$ (anyOf 3).date_of_birth | JSON | Optional | |
$ (anyOf 3).date_of_birth (anyOf 1) | string | Alternative | Date of birth. Present on W8_BEN and W8_BEN_E forms. Format: date-time |
$ (anyOf 3).date_of_birth (anyOf 2) | null | Alternative | Date of birth. Present on W8_BEN and W8_BEN_E forms. Format: date-time |
$ (anyOf 3).first_name | string | Optional | Legal first name. Present on W9_INDIVIDUAL and W8_BEN forms. |
$ (anyOf 3).form_type | string | Required within parent | Discriminator value: W8_BEN Known values: W8_BEN |
$ (anyOf 3).id | string | Required within parent | The public ID (UUID) of the tax form. Format: uuid |
$ (anyOf 3).is_certified_and_agreed | JSON | Optional | |
$ (anyOf 3).is_certified_and_agreed (anyOf 1) | boolean | Alternative | Certification that the signer has read and agrees with the certification information. Present on W8_BEN forms. |
$ (anyOf 3).is_certified_and_agreed (anyOf 2) | null | Alternative | Certification that the signer has read and agrees with the certification information. Present on W8_BEN forms. |
$ (anyOf 3).is_disregarded_entity | boolean | Optional | Whether this is a disregarded entity. Present on W9_INDIVIDUAL and W8_BEN forms. |
$ (anyOf 3).is_ftin_not_legally_required | boolean | Optional | Whether an FTIN is not legally required in the country of residence. Present on W-8 forms. |
$ (anyOf 3).is_tax_treaty_enabled | JSON | Optional | |
$ (anyOf 3).is_tax_treaty_enabled (anyOf 1) | boolean | Alternative | Whether tax treaty benefits are claimed. Present on W-8 forms. |
$ (anyOf 3).is_tax_treaty_enabled (anyOf 2) | null | Alternative | Whether tax treaty benefits are claimed. Present on W-8 forms. |
$ (anyOf 3).last_name | string | Optional | Legal last name. Present on W9_INDIVIDUAL and W8_BEN forms. |
$ (anyOf 3).mailing_address | JSON | Optional | Mailing address if different from permanent residence. Present on W8_BEN and W8_BEN_E forms. |
$ (anyOf 3).mailing_address (anyOf 1) | Model | Alternative | Expand List tax forms for the authenticated worker — 200 response body — data / item / form_type: W8 BEN mailing address address, address line2, city, country, state, zip code |
$ (anyOf 3).mailing_address (anyOf 2) | null | Alternative | |
$ (anyOf 3).middle_name | string | Optional | Legal middle name. Present on W9_INDIVIDUAL and W8_BEN forms. |
$ (anyOf 3).pdf_url | JSON | Optional | |
$ (anyOf 3).pdf_url (anyOf 1) | string | Alternative | Pre-signed download URL for the generated form PDF. The link expires about 15 minutes after the response is issued — download promptly or request the list again. Null while the PDF has not been generated yet. |
$ (anyOf 3).pdf_url (anyOf 2) | null | Alternative | Pre-signed download URL for the generated form PDF. The link expires about 15 minutes after the response is issued — download promptly or request the list again. Null while the PDF has not been generated yet. |
$ (anyOf 3).print_name_of_signer | JSON | Optional | |
$ (anyOf 3).print_name_of_signer (anyOf 1) | string | Alternative | Printed name of the signer. Present on W-8 forms. |
$ (anyOf 3).print_name_of_signer (anyOf 2) | null | Alternative | Printed name of the signer. Present on W-8 forms. |
$ (anyOf 3).referencing_information | JSON | Optional | |
$ (anyOf 3).referencing_information (anyOf 1) | string | Alternative | Reference number for the form. Present on W-8 forms. |
$ (anyOf 3).referencing_information (anyOf 2) | null | Alternative | Reference number for the form. Present on W-8 forms. |
$ (anyOf 3).state | JSON | Optional | |
$ (anyOf 3).state (anyOf 1) | string | Alternative | State or province code. |
$ (anyOf 3).state (anyOf 2) | null | Alternative | State or province code. |
$ (anyOf 3).tax_number | Model | Optional | Expand List tax forms for the authenticated worker — 200 response body — data / item / form_type: W8 BEN tax number Foreign taxpayer identification number. Returned unmasked. |
$ (anyOf 3).tax_treaty_benefits_form | JSON | Optional | Tax treaty benefits details. Present when treaty benefits are claimed. |
$ (anyOf 3).tax_treaty_benefits_form (anyOf 1) | Model | Alternative | Expand List tax forms for the authenticated worker — 200 response body — data / item / form_type: W8 BEN tax treaty benefits form article and paragraph, details, owner resident country, type of income, withholding rate |
$ (anyOf 3).tax_treaty_benefits_form (anyOf 2) | null | Alternative | |
$ (anyOf 3).updated_at | string | Required within parent | Timestamp of when the tax form was last updated. Format: date-time |
$ (anyOf 3).us_tax_number | Model | Optional | Expand List tax forms for the authenticated worker — 200 response body — data / item / form_type: W8 BEN us tax number US Taxpayer Identification Number. Present on W8_BEN and W8_BEN_E forms. Returned unmasked. |
$ (anyOf 3).zip_code | string | Optional | ZIP/postal code. |
$ (anyOf 4) | object | Alternative | W8_BEN_E variant |
$ (anyOf 4).address | string | Optional | Street address of permanent residence. |
$ (anyOf 4).address_line2 | JSON | Optional | |
$ (anyOf 4).address_line2 (anyOf 1) | string | Alternative | Street address line 2. Present on W8_BEN and W8_BEN_E forms. |
$ (anyOf 4).address_line2 (anyOf 2) | null | Alternative | Street address line 2. Present on W8_BEN and W8_BEN_E forms. |
$ (anyOf 4).city | JSON | Optional | |
$ (anyOf 4).city (anyOf 1) | string | Alternative | City name. |
$ (anyOf 4).city (anyOf 2) | null | Alternative | City name. |
$ (anyOf 4).client_legal_entity_id | string | Required within parent | Public ID of the client's legal entity the form was submitted against. Format: uuid |
$ (anyOf 4).contractor_signature | string | Optional | The signer's digital signature. |
$ (anyOf 4).country | string | Optional | ISO 3166-1 alpha-2 country code of permanent residence. |
$ (anyOf 4).country_of_citizenship | string | Optional | ISO 3166-1 alpha-2 country code of citizenship (W8_BEN) or incorporation (W8_BEN_E). |
$ (anyOf 4).created_at | string | Required within parent | Timestamp of when the tax form was created. Format: date-time |
$ (anyOf 4).date_of_birth | JSON | Optional | |
$ (anyOf 4).date_of_birth (anyOf 1) | string | Alternative | Date of birth. Present on W8_BEN and W8_BEN_E forms. Format: date-time |
$ (anyOf 4).date_of_birth (anyOf 2) | null | Alternative | Date of birth. Present on W8_BEN and W8_BEN_E forms. Format: date-time |
$ (anyOf 4).entity_country | JSON | Optional | |
$ (anyOf 4).entity_country (anyOf 1) | string | Alternative | ISO 3166-1 alpha-2 country code of the entity. Present on W8_BEN_E forms. |
$ (anyOf 4).entity_country (anyOf 2) | null | Alternative | ISO 3166-1 alpha-2 country code of the entity. Present on W8_BEN_E forms. |
$ (anyOf 4).entity_type | string | Optional | Chapter 3 entity type. Present on W8_BEN_E forms. Known values: CORPORATION, DISREGARDED_ENTITY, PARTNERSHIP, SIMPLE_TRUST, GRANTOR_TRUST, COMPLEX_TRUST, ESTATE, GOVERNMENT, CENTRAL_BANK_OF_ISSUE, TAX_EXEMPT, PRIVATE_FOUNDATION, INTERNATIONAL, FOREIGN_GOVERNMENT_CONTROLLED, FOREIGN_GOVERNMENT_INTEGRAL |
$ (anyOf 4).fatca_status | string | Optional | FATCA (Foreign Account Tax Compliance Act) status. Present on W8_BEN_E forms. Known values: ACTIVE_NFFE, PASSIVE_NFFE |
$ (anyOf 4).form_type | string | Required within parent | Discriminator value: W8_BEN_E Known values: W8_BEN_E |
$ (anyOf 4).giin | JSON | Optional | |
$ (anyOf 4).giin (anyOf 1) | string | Alternative | Global Intermediary Identification Number. Present on W8_BEN_E forms. |
$ (anyOf 4).giin (anyOf 2) | null | Alternative | Global Intermediary Identification Number. Present on W8_BEN_E forms. |
$ (anyOf 4).has_substantial_us_owner | boolean | Optional | Whether the entity has a substantial US owner. Present on W8_BEN_E forms. |
$ (anyOf 4).id | string | Required within parent | The public ID (UUID) of the tax form. Format: uuid |
$ (anyOf 4).is_entity_certification_confirmed | JSON | Optional | |
$ (anyOf 4).is_entity_certification_confirmed (anyOf 1) | boolean | Alternative | Certification that the entity is the beneficial owner of all income. Present on W8_BEN_E forms. |
$ (anyOf 4).is_entity_certification_confirmed (anyOf 2) | null | Alternative | Certification that the entity is the beneficial owner of all income. Present on W8_BEN_E forms. |
$ (anyOf 4).is_ftin_not_legally_required | boolean | Optional | Whether an FTIN is not legally required in the country of residence. Present on W-8 forms. |
$ (anyOf 4).is_tax_treaty_enabled | JSON | Optional | |
$ (anyOf 4).is_tax_treaty_enabled (anyOf 1) | boolean | Alternative | Whether tax treaty benefits are claimed. Present on W-8 forms. |
$ (anyOf 4).is_tax_treaty_enabled (anyOf 2) | null | Alternative | Whether tax treaty benefits are claimed. Present on W-8 forms. |
$ (anyOf 4).mailing_address | JSON | Optional | Mailing address if different from permanent residence. Present on W8_BEN and W8_BEN_E forms. |
$ (anyOf 4).mailing_address (anyOf 1) | Model | Alternative | Expand List tax forms for the authenticated worker — 200 response body — data / item / form_type: W8 BEN mailing address address, address line2, city, country, state, zip code |
$ (anyOf 4).mailing_address (anyOf 2) | null | Alternative | |
$ (anyOf 4).name_of_disregarded_entity | JSON | Optional | |
$ (anyOf 4).name_of_disregarded_entity (anyOf 1) | string | Alternative | Name of the disregarded entity, if applicable. Present on W8_BEN_E forms. |
$ (anyOf 4).name_of_disregarded_entity (anyOf 2) | null | Alternative | Name of the disregarded entity, if applicable. Present on W8_BEN_E forms. |
$ (anyOf 4).name_of_organization | string | Optional | Name of the organization. Present on W8_BEN_E forms. |
$ (anyOf 4).pdf_url | JSON | Optional | |
$ (anyOf 4).pdf_url (anyOf 1) | string | Alternative | Pre-signed download URL for the generated form PDF. The link expires about 15 minutes after the response is issued — download promptly or request the list again. Null while the PDF has not been generated yet. |
$ (anyOf 4).pdf_url (anyOf 2) | null | Alternative | Pre-signed download URL for the generated form PDF. The link expires about 15 minutes after the response is issued — download promptly or request the list again. Null while the PDF has not been generated yet. |
$ (anyOf 4).print_name_of_signer | JSON | Optional | |
$ (anyOf 4).print_name_of_signer (anyOf 1) | string | Alternative | Printed name of the signer. Present on W-8 forms. |
$ (anyOf 4).print_name_of_signer (anyOf 2) | null | Alternative | Printed name of the signer. Present on W-8 forms. |
$ (anyOf 4).referencing_information | JSON | Optional | |
$ (anyOf 4).referencing_information (anyOf 1) | string | Alternative | Reference number for the form. Present on W-8 forms. |
$ (anyOf 4).referencing_information (anyOf 2) | null | Alternative | Reference number for the form. Present on W-8 forms. |
$ (anyOf 4).state | JSON | Optional | |
$ (anyOf 4).state (anyOf 1) | string | Alternative | State or province code. |
$ (anyOf 4).state (anyOf 2) | null | Alternative | State or province code. |
$ (anyOf 4).tax_number | Model | Optional | Expand List tax forms for the authenticated worker — 200 response body — data / item / form_type: W8 BEN tax number Foreign taxpayer identification number. Returned unmasked. |
$ (anyOf 4).tax_treaty_benefits_form | JSON | Optional | Tax treaty benefits details. Present when treaty benefits are claimed. |
$ (anyOf 4).tax_treaty_benefits_form (anyOf 1) | Model | Alternative | Expand List tax forms for the authenticated worker — 200 response body — data / item / fatca_status: ACTIVE NFFE, PASSIVE NFFE, form type: W8 BEN E tax treaty benefits form article and paragraph, details, is tax residency certified, limitation type, other article and paragraph, owner resident country, type of income, withholding rate |
$ (anyOf 4).tax_treaty_benefits_form (anyOf 2) | null | Alternative | |
$ (anyOf 4).updated_at | string | Required within parent | Timestamp of when the tax form was last updated. Format: date-time |
$ (anyOf 4).us_tax_number | Model | Optional | Expand List tax forms for the authenticated worker — 200 response body — data / item / form_type: W8 BEN us tax number US Taxpayer Identification Number. Present on W8_BEN and W8_BEN_E forms. Returned unmasked. |
$ (anyOf 4).zip_code | string | Optional | ZIP/postal code. |
Referenced models: List tax forms for the authenticated worker — 200 response body — data / item / form_type: W9 COMPANY tax number, List tax forms for the authenticated worker — 200 response body — data / item / form_type: W9 COMPANY federal tax classification, List tax forms for the authenticated worker — 200 response body — data / item / form_type: W8 BEN mailing address address, address line2, city, country, state, zip code, List tax forms for the authenticated worker — 200 response body — data / item / form_type: W8 BEN tax number, List tax forms for the authenticated worker — 200 response body — data / item / form_type: W8 BEN tax treaty benefits form article and paragraph, details, owner resident country, type of income, withholding rate, List tax forms for the authenticated worker — 200 response body — data / item / form_type: W8 BEN us tax number, List tax forms for the authenticated worker — 200 response body — data / item / fatca_status: ACTIVE NFFE, PASSIVE NFFE, form type: W8 BEN E tax treaty benefits form article and paragraph, details, is tax residency certified, limitation type, other article and paragraph, owner resident country, type of income, withholding rate
Retrieve IC worker invoice PDF download link — 200 response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Envelope containing a time-limited signed URL to the invoice PDF. |
data | Model | Required within parent | Expand Retrieve IC worker invoice PDF download link — 200 response body — data Payload with the signed download URL. |
Referenced models: Retrieve IC worker invoice PDF download link — 200 response body — data
Retrieve IC worker invoice PDF download link — 200 response body — data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Payload with the signed download URL. |
url | string | Required within parent | HTTPS URL to download the invoice PDF. Format: uri |
Retrieve one compliance document of a worker contract — 200 response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
data | Model | Required within parent | Expand Retrieve one compliance document of a worker contract — 200 response body — data |
Referenced models: Retrieve one compliance document of a worker contract — 200 response body — data
Retrieve one compliance document of a worker contract — 200 response body — data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
country | JSON | Required within parent | |
country (anyOf 1) | string | Alternative | ISO 3166-1 alpha-2 country code the requirement applies to. Null for a requirement that applies everywhere. |
country (anyOf 2) | null | Alternative | ISO 3166-1 alpha-2 country code the requirement applies to. Null for a requirement that applies everywhere. |
created_at | JSON | Required within parent | |
created_at (anyOf 1) | string | Alternative | When the submission was created. Carries the same value as `uploaded_at`. Format: date-time |
created_at (anyOf 2) | null | Alternative | When the submission was created. Carries the same value as `uploaded_at`. Format: date-time |
description | string | Required within parent | What the document asks for, in the worker language. Empty string when the requirement has no description. |
filenames | array | Required within parent | Names of the files submitted against this requirement. Empty array when nothing has been submitted. |
filenames[] | string | Each item | |
has_template | boolean | Required within parent | Whether a template is provided for this document. |
id | string | Required within parent | Public UUID of the compliance document requirement. Use it as `document_id` on the other endpoints. Format: uuid |
is_acknowledgement_only_document | boolean | Required within parent | Whether the document only has to be acknowledged, with no file to submit. |
is_consent_required | boolean | Optional | Whether the worker has to consent. Present only for acknowledgement-only documents that declare the flag. |
is_required | boolean | Required within parent | Whether the worker has to submit this document. A requirement with a 30-day grace period after the employment start reads `true`: it is required, only not immediately. |
name | string | Required within parent | Display name of the document, in the worker language. |
review | JSON | Optional | Outcome of the Deel review of the submission. Present only for worker types whose submissions are reviewed, and only once a review exists. Absent for Global Payroll documents and for contractor documents that are not reviewed. |
review (anyOf 1) | Model | Alternative | Expand Retrieve one compliance document of a worker contract — 200 response body — data review rejection message, status |
review (anyOf 2) | null | Alternative | |
submission_status | JSON | Required within parent | |
submission_status (anyOf 1) | string | Alternative | Reads `REVIEWING` while a submission is not final yet. Null at every other time. |
submission_status (anyOf 2) | null | Alternative | Reads `REVIEWING` while a submission is not final yet. Null at every other time. |
updated_at | JSON | Required within parent | |
updated_at (anyOf 1) | string | Alternative | When the submission was last changed. Null when nothing has been submitted. Format: date-time |
updated_at (anyOf 2) | null | Alternative | When the submission was last changed. Null when nothing has been submitted. Format: date-time |
uploaded_at | JSON | Required within parent | |
uploaded_at (anyOf 1) | string | Alternative | When the submission was created. Null when nothing has been submitted. Format: date-time |
uploaded_at (anyOf 2) | null | Alternative | When the submission was created. Null when nothing has been submitted. Format: date-time |
Referenced models: Retrieve one compliance document of a worker contract — 200 response body — data review rejection message, status
Retrieve one compliance document of a worker contract — 200 response body — data review rejection message, status
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Outcome of the Deel review of the submission. Present only for worker types whose submissions are reviewed, and only once a review exists. Absent for Global Payroll documents and for contractor documents that are not reviewed. |
rejection_message | JSON | Required within parent | |
rejection_message (anyOf 1) | string | Alternative | Why the submission was rejected, in the worker language. Null unless the status is `REJECTED`. |
rejection_message (anyOf 2) | null | Alternative | Why the submission was rejected, in the worker language. Null unless the status is `REJECTED`. |
status | string | Required within parent | Where the submission sits in the review. Known values: AWAITING_EX_REVIEW, AWAITING_EXTERNAL_REVIEW, REJECTED, APPROVED, ON_HOLD |
Submit files for one compliance document of a worker contract — request body — body data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
files | array | Required within parent | Files to submit against the requirement. Allowed types: pdf, png, jpg, jpeg, heic. |
files[] | Model | Each item | Expand Submit files for one compliance document of a worker contract — request body — body data files item |
Referenced models: Submit files for one compliance document of a worker contract — request body — body data files item
Submit files for one compliance document of a worker contract — request body — body data files item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
content_type | string | Required within parent | MIME type of the file. Maximum length: 255 |
file_id | string | Required within parent | File Service file id. Format: uuid |
one_time_secret | string | Required within parent | File Service one-time secret for that file. Maximum length: 1024 Minimum length: 1 |
original_filename | string | Required within parent | Original filename, extension included. Maximum length: 500 Minimum length: 1 |
Update a US tax form for the authenticated worker — 200 response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
data | Model | Required within parent | Expand Update a US tax form for the authenticated worker — 200 response body — data |
Referenced models: Update a US tax form for the authenticated worker — 200 response body — data
Update a US tax form for the authenticated worker — 200 response body — data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
created_at | string | Required within parent | Timestamp of when the tax form was created. Format: date-time |
id | string | Required within parent | The public ID (UUID) of the tax form. Format: uuid |
updated_at | string | Required within parent | Timestamp of when the tax form was last updated. Format: date-time |
Update a US tax form for the authenticated worker — request body — body data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | discriminator: {"propertyName": "form_type"} |
$ (oneOf 1) | object | Alternative | W9_INDIVIDUAL variant |
$ (oneOf 1).address | string | Required within parent | Street address. Maximum 40 characters for 1099 reporting compliance. Maximum length: 40 |
$ (oneOf 1).business_name | string or null | Optional | Business name. Only applicable when is_disregarded_entity is true. Maximum length: 40 |
$ (oneOf 1).city | string | Required within parent | City name. Maximum length: 40 Minimum length: 1 |
$ (oneOf 1).contractor_signature | string | Optional | Contractor's digital signature. Maximum length: 100 Minimum length: 1 |
$ (oneOf 1).country | string | Required within parent | ISO 3166-1 alpha-2 country code. Maximum length: 2 Minimum length: 2 Pattern: ^[A-Z]{2}$ |
$ (oneOf 1).first_name | string | Required within parent | Legal first name. Maximum length: 40 |
$ (oneOf 1).form_type | string | Required within parent | Discriminator value: W9_INDIVIDUAL One of: W9_INDIVIDUAL |
$ (oneOf 1).is_disregarded_entity | boolean | Optional | Whether this is a disregarded entity. Default: false |
$ (oneOf 1).is_subject_backup_withholding | boolean | Optional | Whether the contractor is subject to backup withholding. Default: false |
$ (oneOf 1).last_name | string | Required within parent | Legal last name. Maximum length: 40 |
$ (oneOf 1).middle_name | string | Optional | Legal middle name. Maximum length: 100 |
$ (oneOf 1).state | string or null | Optional | US state code. Maximum length: 10 |
$ (oneOf 1).tax_number | Model | Required within parent | Expand Create a tax form for the authenticated worker — request body — body / data / form_type: W9 INDIVIDUAL tax number Taxpayer identification number. |
$ (oneOf 1).zip_code | string | Required within parent | ZIP/postal code. Must be a valid US ZIP code for US addresses. |
$ (oneOf 2) | object | Alternative | W9_COMPANY variant |
$ (oneOf 2).address | string | Required within parent | Street address. Maximum length: 40 |
$ (oneOf 2).business_name | string | Required within parent | Business name. Maximum length: 40 Minimum length: 1 |
$ (oneOf 2).city | string | Required within parent | City name. Maximum length: 40 Minimum length: 1 |
$ (oneOf 2).contractor_signature | string | Optional | Authorized signer's digital signature. Maximum length: 100 Minimum length: 1 |
$ (oneOf 2).country | string | Required within parent | ISO 3166-1 alpha-2 country code. Maximum length: 2 Minimum length: 2 Pattern: ^[A-Z]{2}$ |
$ (oneOf 2).doing_business_as | string or null | Optional | DBA name. Maximum length: 50 |
$ (oneOf 2).federal_tax_classification | Model | Required within parent | Expand Create a tax form for the authenticated worker — request body — body / data / form_type: W9 COMPANY federal tax classification Federal tax classification. |
$ (oneOf 2).form_type | string | Required within parent | Discriminator value: W9_COMPANY One of: W9_COMPANY |
$ (oneOf 2).is_subject_backup_withholding | boolean | Optional | Whether the contractor is subject to backup withholding. Default: false |
$ (oneOf 2).state | string or null | Optional | US state code. Maximum length: 10 |
$ (oneOf 2).tax_number | Model | Required within parent | Expand Create a tax form for the authenticated worker — request body — body / data / form_type: W9 COMPANY tax number Taxpayer identification number. |
$ (oneOf 2).zip_code | string | Required within parent | ZIP/postal code. |
$ (oneOf 3) | object | Alternative | W8_BEN variant |
$ (oneOf 3).address | string | Required within parent | Street address. Maximum length: 100 |
$ (oneOf 3).address_line2 | string or null | Optional | Street address line 2. Maximum length: 100 |
$ (oneOf 3).city | string or null | Optional | City name. Maximum length: 50 Minimum length: 1 |
$ (oneOf 3).contractor_signature | string | Optional | Contractor's digital signature. Maximum length: 100 Minimum length: 1 |
$ (oneOf 3).country | string | Required within parent | ISO 3166-1 alpha-2 country code of permanent residence. Maximum length: 2 Minimum length: 2 Pattern: ^[A-Z]{2}$ |
$ (oneOf 3).country_of_citizenship | string | Required within parent | ISO 3166-1 alpha-2 country code of citizenship. Maximum length: 2 Minimum length: 2 Pattern: ^[A-Z]{2}$ |
$ (oneOf 3).date_of_birth | string or null | Optional | Date of birth. Must be at least 18 years ago and no more than 100 years ago. Format: date-time |
$ (oneOf 3).first_name | string | Required within parent | Legal first name. Maximum length: 100 |
$ (oneOf 3).form_type | string | Required within parent | Discriminator value: W8_BEN One of: W8_BEN |
$ (oneOf 3).is_certified_and_agreed | boolean or null | Optional | Certification that the signer has read and agrees with the certification information. Default: false |
$ (oneOf 3).is_disregarded_entity | boolean | Optional | Whether this is a disregarded entity. Default: false |
$ (oneOf 3).is_ftin_not_legally_required | boolean | Optional | Check if FTIN is not legally required in your country of residence. Default: false |
$ (oneOf 3).is_tax_treaty_enabled | boolean or null | Optional | Whether the contractor claims tax treaty benefits. Default: false |
$ (oneOf 3).last_name | string | Required within parent | Legal last name. Maximum length: 100 |
$ (oneOf 3).mailing_address | JSON | Optional | Mailing address if different from permanent residence. |
$ (oneOf 3).mailing_address (oneOf 1) | Model | Alternative | Expand Create a tax form for the authenticated worker — request body — body / data / form_type: W8 BEN mailing address address, address line2, city, country, state, zip code |
$ (oneOf 3).mailing_address (oneOf 2) | null | Alternative | |
$ (oneOf 3).middle_name | string or null | Optional | Legal middle name. Maximum length: 100 |
$ (oneOf 3).print_name_of_signer | string or null | Optional | Printed name of the signer. Maximum length: 100 |
$ (oneOf 3).referencing_information | string or null | Optional | Reference number for the form. Maximum length: 100 |
$ (oneOf 3).state | string or null | Optional | State or province code. Maximum length: 10 |
$ (oneOf 3).tax_number | Model | Optional | Expand Create a tax form for the authenticated worker — request body — body / data / form_type: W8 BEN tax number Foreign tax identifying number. At least one of us_tax_number or tax_number is required unless is_ftin_not_legally_required is true. |
$ (oneOf 3).tax_treaty_benefits_form | JSON | Optional | Tax treaty benefits details. Applicable when is_tax_treaty_enabled is true. |
$ (oneOf 3).tax_treaty_benefits_form (oneOf 1) | Model | Alternative | Expand Create a tax form for the authenticated worker — request body — body / data / form_type: W8 BEN tax treaty benefits form article and paragraph, details, owner resident country, type of income, withholding rate |
$ (oneOf 3).tax_treaty_benefits_form (oneOf 2) | null | Alternative | |
$ (oneOf 3).us_tax_number | Model | Optional | Expand Create a tax form for the authenticated worker — request body — body / data / form_type: W8 BEN us tax number US Taxpayer Identification Number. |
$ (oneOf 3).zip_code | string | Required within parent | ZIP/postal code. |
$ (oneOf 4) | object | Alternative | W8_BEN_E variant |
$ (oneOf 4).address | string | Required within parent | Street address. Maximum length: 100 |
$ (oneOf 4).address_line2 | string or null | Optional | Street address line 2. Maximum length: 100 |
$ (oneOf 4).city | string | Required within parent | City of residence. Maximum length: 50 Minimum length: 1 |
$ (oneOf 4).contractor_signature | string | Optional | Authorized signer's digital signature. Maximum length: 100 Minimum length: 1 |
$ (oneOf 4).country | string | Required within parent | ISO 3166-1 alpha-2 country code of permanent residence. Maximum length: 2 Minimum length: 2 Pattern: ^[A-Z]{2}$ |
$ (oneOf 4).country_of_citizenship | string | Required within parent | ISO 3166-1 alpha-2 country code of incorporation/organization. Maximum length: 2 Minimum length: 2 Pattern: ^[A-Z]{2}$ |
$ (oneOf 4).date_of_birth | string or null | Optional | Date of birth of the beneficial owner. Format: date-time |
$ (oneOf 4).entity_country | string or null | Required within parent | ISO 3166-1 alpha-2 country code of the entity. Maximum length: 2 Minimum length: 2 Pattern: ^[A-Z]{2}$ |
$ (oneOf 4).entity_type | string | Required within parent | Chapter 3 entity type. One of: CORPORATION, DISREGARDED_ENTITY, PARTNERSHIP, SIMPLE_TRUST, GRANTOR_TRUST, COMPLEX_TRUST, ESTATE, GOVERNMENT, CENTRAL_BANK_OF_ISSUE, TAX_EXEMPT, PRIVATE_FOUNDATION, INTERNATIONAL, FOREIGN_GOVERNMENT_CONTROLLED, FOREIGN_GOVERNMENT_INTEGRAL |
$ (oneOf 4).fatca_status | string | Required within parent | FATCA (Foreign Account Tax Compliance Act) status. One of: ACTIVE_NFFE, PASSIVE_NFFE |
$ (oneOf 4).form_type | string | Required within parent | Discriminator value: W8_BEN_E One of: W8_BEN_E |
$ (oneOf 4).giin | string or null | Optional | Global Intermediary Identification Number (19 characters). Maximum length: 19 Minimum length: 19 |
$ (oneOf 4).has_substantial_us_owner | boolean | Optional | Whether the entity has a substantial US owner. Required when fatca_status is 'PASSIVE_NFFE'. Default: false |
$ (oneOf 4).is_entity_certification_confirmed | boolean or null | Optional | Certification that the entity is the beneficial owner of all income. Default: false |
$ (oneOf 4).is_ftin_not_legally_required | boolean | Optional | Check if FTIN is not legally required in your country. Default: false |
$ (oneOf 4).is_tax_treaty_enabled | boolean or null | Optional | Whether the entity claims tax treaty benefits. Default: false |
$ (oneOf 4).mailing_address | JSON | Optional | Mailing address if different from permanent residence. |
$ (oneOf 4).mailing_address (oneOf 1) | Model | Alternative | Expand Create a tax form for the authenticated worker — request body — body / data / form_type: W8 BEN mailing address address, address line2, city, country, state, zip code |
$ (oneOf 4).mailing_address (oneOf 2) | null | Alternative | |
$ (oneOf 4).name_of_disregarded_entity | string or null | Optional | Name of the disregarded entity, if applicable. Maximum length: 100 |
$ (oneOf 4).name_of_organization | string | Required within parent | Name of the organization. Maximum length: 100 |
$ (oneOf 4).print_name_of_signer | string or null | Optional | Printed name of the authorized signer. Maximum length: 100 |
$ (oneOf 4).referencing_information | string or null | Optional | Reference number for the form. Maximum length: 100 |
$ (oneOf 4).state | string or null | Optional | State or province code. Maximum length: 10 |
$ (oneOf 4).tax_number | Model | Optional | Expand Create a tax form for the authenticated worker — request body — body / data / fatca_status: ACTIVE NFFE, PASSIVE NFFE, form type: W8 BEN E tax number Foreign tax identifying number. At least one of us_tax_number, tax_number, or giin is required unless is_ftin_not_legally_required is true. |
$ (oneOf 4).tax_treaty_benefits_form | JSON | Optional | Tax treaty benefits details. |
$ (oneOf 4).tax_treaty_benefits_form (oneOf 1) | Model | Alternative | Expand Create a tax form for the authenticated worker — request body — body / data / fatca_status: ACTIVE NFFE, PASSIVE NFFE, form type: W8 BEN E tax treaty benefits form Tax treaty benefits details |
$ (oneOf 4).tax_treaty_benefits_form (oneOf 2) | null | Alternative | |
$ (oneOf 4).us_tax_number | Model | Optional | Expand Create a tax form for the authenticated worker — request body — body / data / form_type: W8 BEN us tax number US Taxpayer Identification Number. |
$ (oneOf 4).zip_code | string | Required within parent | ZIP/postal code. |
Referenced models: Create a tax form for the authenticated worker — request body — body / data / form_type: W9 INDIVIDUAL tax number, Create a tax form for the authenticated worker — request body — body / data / form_type: W9 COMPANY federal tax classification, Create a tax form for the authenticated worker — request body — body / data / form_type: W9 COMPANY tax number, Create a tax form for the authenticated worker — request body — body / data / form_type: W8 BEN mailing address address, address line2, city, country, state, zip code, Create a tax form for the authenticated worker — request body — body / data / form_type: W8 BEN tax number, Create a tax form for the authenticated worker — request body — body / data / form_type: W8 BEN tax treaty benefits form article and paragraph, details, owner resident country, type of income, withholding rate, Create a tax form for the authenticated worker — request body — body / data / form_type: W8 BEN us tax number, Create a tax form for the authenticated worker — request body — body / data / fatca_status: ACTIVE NFFE, PASSIVE NFFE, form type: W8 BEN E tax number, Create a tax form for the authenticated worker — request body — body / data / fatca_status: ACTIVE NFFE, PASSIVE NFFE, form type: W8 BEN E tax treaty benefits form Tax treaty benefits details