> This page is for API, version 2026-01-01 (Stable) (default). > For other versions, use one of these documentation indexes: > - 2026-01-01 (Stable) (default): https://developer.deel.com/api/stable/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer.deel.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.deel.com/_mcp/server. # Create a tax form for the authenticated worker POST https://api.letsdeel.com/rest/workers/tax-forms Content-Type: application/json Submit a new US tax form for the authenticated worker against a specific client legal entity, typically during onboarding or when a fresh form must be recorded for a worker/legal-entity pair. The worker is resolved from the access token; the target legal entity is set via client_legal_entity_id. Select the form type based on the worker's US tax status: W-9 for US individuals or entities, W-8BEN for non-US individuals, W-8BEN-E for non-US entities. The worker must have an active (non-terminated) contract with the legal entity, and only one tax form may exist per worker/legal-entity pair. **Token scopes**: `worker:write` Reference: https://developer.deel.com/api/reference/endpoints/workers/create-a-tax-form-for-a-worker-v-2026-01-01 ## Authentication - `Authorization` header (bearer token, required) — ## Authentication The Deel API uses bearer tokens to authenticate requests. All API calls must be made over HTTPS — calls over plain HTTP or without authentication will fail. ```curl curl -X GET 'https://api.letsdeel.com/rest/v2/contracts' \ -H 'Authorization: Bearer YOUR-TOKEN-HERE' ``` [Learn more about authentication](/api/authentication) - `Authorization` header (bearer token, required) — Standard OAuth2 security scheme based on https://swagger.io/docs/specification/authentication/ ## Servers - `https://api.letsdeel.com/rest` (Production, default) - `https://api-staging.letsdeel.com/rest` (Demo) ## Request ### Body (application/json) This endpoint expects an object. - `data` (WorkersTaxFormsPostRequestBodyContentApplicationJsonSchemaData, required) ## Response ### 201 Tax form created successfully. - `data` (WorkersTaxFormsPostResponsesContentApplicationJsonSchemaData, required) ## Errors ### 400 Bad Request Error Validation failed — for example a request body field is missing or malformed, the client_legal_entity_id does not exist, or the form_type does not match the contractor's tax residency (e.g. a W-8BEN submitted for a US contractor). - `errors` (list of WorkersTaxFormsPostResponsesContentApplicationJsonSchemaErrorsItems, optional) ### 401 Unauthorized Error Operation failed. - `request` (ApiErrorRequest, optional) - `errors` (list of ApiError, optional) ### 403 Forbidden Error No live contract exists between the contractor and the specified client legal entity. A tax form can only be submitted for a contractor who has a non-terminated contract with that legal entity. - `errors` (list of WorkersTaxFormsPostResponsesContentApplicationJsonSchemaErrorsItems, optional) ### 404 Not Found Error The authenticated worker was not found in the calling organization, or has no contractor profile. - `errors` (list of WorkersTaxFormsPostResponsesContentApplicationJsonSchemaErrorsItems, optional) ### 409 Conflict Error A tax form already exists for this contractor and client legal entity. Only one tax form can exist per contractor/legal-entity pair. - `errors` (list of WorkersTaxFormsPostResponsesContentApplicationJsonSchemaErrorsItems, optional) ### 500 Internal Server Error Internal server error. - `errors` (list of WorkersTaxFormsPostResponsesContentApplicationJsonSchemaErrorsItems, optional) ## Types ### WorkersTaxFormsPostRequestBodyContentApplicationJsonSchemaData - `form_type`: `W9_INDIVIDUAL` (W9_INDIVIDUAL) - `address` (string, required) — Street address. Maximum 40 characters for 1099 reporting compliance. - `city` (string, required) — City name. - `client_legal_entity_id` (string, required) — Public ID of the client's legal entity. - `contractor_signature` (string, required) — Contractor's digital signature. - `country` (string, required) — ISO 3166-1 alpha-2 country code. - `first_name` (string, required) — Legal first name. - `last_name` (string, required) — Legal last name. - `tax_number` (WorkersTaxFormsPostRequestBodyContentApplicationJsonSchemaDataOneOf0TaxNumber, required) — Taxpayer identification number. - `zip_code` (string, required) — ZIP/postal code. Must be a valid US ZIP code for US addresses. - `business_name` (string, optional, nullable) — Business name. Only applicable when is_disregarded_entity is true. - `is_disregarded_entity` (boolean, optional, default: false) — Whether this is a disregarded entity. - `is_subject_backup_withholding` (boolean, optional, default: false) — Whether the contractor is subject to backup withholding. - `middle_name` (string, optional) — Legal middle name. - `state` (string, optional, nullable) — US state code. - `form_type`: `W9_COMPANY` (W9_COMPANY) - `address` (string, required) — Street address. - `business_name` (string, required) — Business name. - `city` (string, required) — City name. - `client_legal_entity_id` (string, required) — Public ID of the client's legal entity. - `contractor_signature` (string, required) — Authorized signer's digital signature. - `country` (string, required) — ISO 3166-1 alpha-2 country code. - `federal_tax_classification` (WorkersTaxFormsPostRequestBodyContentApplicationJsonSchemaDataOneOf1FederalTaxClassification, required) — Federal tax classification. - `tax_number` (WorkersTaxFormsPostRequestBodyContentApplicationJsonSchemaDataOneOf1TaxNumber, required) — Taxpayer identification number. - `zip_code` (string, required) — ZIP/postal code. - `doing_business_as` (string, optional, nullable) — DBA name. - `is_subject_backup_withholding` (boolean, optional, default: false) — Whether the contractor is subject to backup withholding. - `state` (string, optional, nullable) — US state code. - `form_type`: `W8_BEN` (W8_BEN) - `address` (string, required) — Street address. - `client_legal_entity_id` (string, required) — Public ID of the client's legal entity. - `contractor_signature` (string, required) — Contractor's digital signature. - `country` (string, required) — ISO 3166-1 alpha-2 country code of permanent residence. - `country_of_citizenship` (string, required) — ISO 3166-1 alpha-2 country code of citizenship. - `first_name` (string, required) — Legal first name. - `last_name` (string, required) — Legal last name. - `zip_code` (string, required) — ZIP/postal code. - `address_line2` (string, optional, nullable) — Street address line 2. - `city` (string, optional, nullable) — City name. - `date_of_birth` (string, optional, nullable) — Date of birth. Must be at least 18 years ago and no more than 100 years ago. - `is_certified_and_agreed` (boolean, optional, nullable, default: false) — Certification that the signer has read and agrees with the certification information. - `is_disregarded_entity` (boolean, optional, default: false) — Whether this is a disregarded entity. - `is_ftin_not_legally_required` (boolean, optional, default: false) — Check if FTIN is not legally required in your country of residence. - `is_tax_treaty_enabled` (boolean, optional, nullable, default: false) — Whether the contractor claims tax treaty benefits. - `mailing_address` (WorkersTaxFormsPostRequestBodyContentApplicationJsonSchemaDataOneOf2MailingAddress, optional, nullable) — Mailing address if different from permanent residence. - `middle_name` (string, optional, nullable) — Legal middle name. - `print_name_of_signer` (string, optional, nullable) — Printed name of the signer. - `referencing_information` (string, optional, nullable) — Reference number for the form. - `state` (string, optional, nullable) — State or province code. - `tax_number` (WorkersTaxFormsPostRequestBodyContentApplicationJsonSchemaDataOneOf2TaxNumber, optional) — Foreign tax identifying number. At least one of us_tax_number or tax_number is required unless is_ftin_not_legally_required is true. - `tax_treaty_benefits_form` (WorkersTaxFormsPostRequestBodyContentApplicationJsonSchemaDataOneOf2TaxTreatyBenefitsForm, optional, nullable) — Tax treaty benefits details. Applicable when is_tax_treaty_enabled is true. - `us_tax_number` (WorkersTaxFormsPostRequestBodyContentApplicationJsonSchemaDataOneOf2UsTaxNumber, optional) — US Taxpayer Identification Number. - `form_type`: `W8_BEN_E` (W8_BEN_E) - `address` (string, required) — Street address. - `city` (string, required) — City of residence. - `client_legal_entity_id` (string, required) — Public ID of the client's legal entity. - `contractor_signature` (string, required) — Authorized signer's digital signature. - `country` (string, required) — ISO 3166-1 alpha-2 country code of permanent residence. - `country_of_citizenship` (string, required) — ISO 3166-1 alpha-2 country code of incorporation/organization. - `entity_country` (string, required, nullable) — ISO 3166-1 alpha-2 country code of the entity. - `entity_type` (enum, required) — Chapter 3 entity type. - Allowed 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` - `fatca_status` (enum, required) — FATCA (Foreign Account Tax Compliance Act) status. - Allowed values: `ACTIVE_NFFE`, `PASSIVE_NFFE` - `name_of_organization` (string, required) — Name of the organization. - `zip_code` (string, required) — ZIP/postal code. - `address_line2` (string, optional, nullable) — Street address line 2. - `date_of_birth` (string, optional, nullable) — Date of birth of the beneficial owner. - `giin` (string, optional, nullable) — Global Intermediary Identification Number (19 characters). - `has_substantial_us_owner` (boolean, optional, default: false) — Whether the entity has a substantial US owner. Required when fatca_status is 'PASSIVE_NFFE'. - `is_entity_certification_confirmed` (boolean, optional, nullable, default: false) — Certification that the entity is the beneficial owner of all income. - `is_ftin_not_legally_required` (boolean, optional, default: false) — Check if FTIN is not legally required in your country. - `is_tax_treaty_enabled` (boolean, optional, nullable, default: false) — Whether the entity claims tax treaty benefits. - `mailing_address` (WorkersTaxFormsPostRequestBodyContentApplicationJsonSchemaDataOneOf3MailingAddress, optional, nullable) — Mailing address if different from permanent residence. - `name_of_disregarded_entity` (string, optional, nullable) — Name of the disregarded entity, if applicable. - `print_name_of_signer` (string, optional, nullable) — Printed name of the authorized signer. - `referencing_information` (string, optional, nullable) — Reference number for the form. - `state` (string, optional, nullable) — State or province code. - `tax_number` (WorkersTaxFormsPostRequestBodyContentApplicationJsonSchemaDataOneOf3TaxNumber, optional) — 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. - `tax_treaty_benefits_form` (WorkersTaxFormsPostRequestBodyContentApplicationJsonSchemaDataOneOf3TaxTreatyBenefitsForm, optional, nullable) — Tax treaty benefits details. - `us_tax_number` (WorkersTaxFormsPostRequestBodyContentApplicationJsonSchemaDataOneOf3UsTaxNumber, optional) — US Taxpayer Identification Number. ### WorkersTaxFormsPostResponsesContentApplicationJsonSchemaData - `id` (string, required) — The public ID (UUID) of the created tax form. - `created_at` (string, required) — Timestamp of when the tax form was created. ### WorkersTaxFormsPostResponsesContentApplicationJsonSchemaErrorsItems - `code` (string, optional) — Machine-readable error code - `message` (string, optional) — Human-readable explanation of the error ### ApiErrorRequest - `method` (string, optional) — The HTTP method of the failed request - `url` (string, optional) — The relative URL of the failed request - `status` (double, optional) — The status code of the response - `api_req_id` (string, optional) — The request ID of the failed request - `docs` (string, optional) — A link to the official documentation for the requested endpoint resource - `source` (string, optional) — The source handler which produced the returned error - `code` (double, optional) — The code of the source handler which produced the returned error ### ApiError - `message` (string, optional) — A description of the returned error - `path` (string, optional) — The JSON path where input validation failed ### WorkersTaxFormsPostRequestBodyContentApplicationJsonSchemaDataOneOf0TaxNumber Taxpayer identification number. - `type` (enum, required) — Tax ID type. SSN/ITIN for individuals; EIN also allowed for disregarded entities. - Allowed values: `SSN`, `ITIN`, `EIN` - `value` (string, required) — Tax ID value. ### WorkersTaxFormsPostRequestBodyContentApplicationJsonSchemaDataOneOf1FederalTaxClassification Federal tax classification. - `type` (enum, required) — Federal tax classification type. - Allowed values: `C_CORPORATION`, `S_CORPORATION`, `OTHER`, `PARTNERSHIP`, `LLC`, `TRUST_ESTATE` - `llc_classification` (enum, optional) — LLC sub-classification. Required when type is 'LLC'. - Allowed values: `P`, `S`, `C` - `other_additional_information` (string, optional) — Additional information. Required when type is 'OTHER'. ### WorkersTaxFormsPostRequestBodyContentApplicationJsonSchemaDataOneOf1TaxNumber Taxpayer identification number. - `type` (enum, required) — Tax ID type. EIN for most entities; SSN/ITIN/EIN for LLC. - Allowed values: `SSN`, `ITIN`, `EIN` - `value` (string, required) — Tax ID value. ### WorkersTaxFormsPostRequestBodyContentApplicationJsonSchemaDataOneOf2MailingAddress Mailing address if different from permanent residence. - `address` (string, required) — Mailing address. - `country` (string, required) — ISO 3166-1 alpha-2 country code. - `zip_code` (string, required) — Mailing address ZIP/postal code. - `city` (string, optional, nullable) — Mailing address city. - `state` (string, optional, nullable) — Mailing address state. - `address_line2` (string, optional, nullable) — Mailing address line 2. ### WorkersTaxFormsPostRequestBodyContentApplicationJsonSchemaDataOneOf2TaxNumber 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` (enum, required) — Foreign tax ID type. - Allowed values: `FTIN` - `value` (string, required) — Foreign tax identifying number. ### WorkersTaxFormsPostRequestBodyContentApplicationJsonSchemaDataOneOf2TaxTreatyBenefitsForm Tax treaty benefits details. Applicable when is_tax_treaty_enabled is true. - `details` (string, optional) — Additional details about the treaty claim. - `type_of_income` (string, optional) — Type of income covered by the treaty. - `withholding_rate` (double, optional) — Withholding rate under the treaty (percentage). - `article_and_paragraph` (string, optional) — Article and paragraph of the applicable tax treaty. - `owner_resident_country` (string, optional) — Country of residence of the beneficial owner. Must be a US income tax treaty country. ### WorkersTaxFormsPostRequestBodyContentApplicationJsonSchemaDataOneOf2UsTaxNumber US Taxpayer Identification Number. - `type` (enum, required) — US tax ID type. - Allowed values: `SSN`, `ITIN` - `value` (string, required) — US tax ID value. ### WorkersTaxFormsPostRequestBodyContentApplicationJsonSchemaDataOneOf3MailingAddress Mailing address if different from permanent residence. - `address` (string, required) — Mailing address. - `country` (string, required) — ISO 3166-1 alpha-2 country code. - `zip_code` (string, required) — Mailing address ZIP/postal code. - `city` (string, optional, nullable) — Mailing address city. - `state` (string, optional, nullable) — Mailing address state. - `address_line2` (string, optional, nullable) — Mailing address line 2. ### WorkersTaxFormsPostRequestBodyContentApplicationJsonSchemaDataOneOf3TaxNumber 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` (enum, required) — Foreign tax ID type. - Allowed values: `FTIN` - `value` (string, required) — Foreign tax identifying number. ### WorkersTaxFormsPostRequestBodyContentApplicationJsonSchemaDataOneOf3TaxTreatyBenefitsForm Tax treaty benefits details. - `details` (string, optional) — Additional details about the treaty claim. - `type_of_income` (string, optional) — Type of income covered by the treaty. - `limitation_type` (enum, optional, nullable) — Limitation on benefits (LOB) type. - Allowed values: `GOVERNMENT`, `PENSION_TRUST`, `TAX_EXEMPT`, `PUBLICLY_TRADED_CORPORATION`, `SUBSIDIARY`, `OWNERSHIP_TEST`, `DERIVATIVE_TEST`, `ACTIVE_TRADE_TEST`, `FAVORABLE`, `NO_ARTICLE`, `OTHER` - `withholding_rate` (double, optional) — Withholding rate under the treaty (percentage). - `article_and_paragraph` (string, optional) — Article and paragraph of the applicable tax treaty. - `owner_resident_country` (string, optional) — Country of residence of the beneficial owner. - `is_tax_residency_certified` (boolean, optional, nullable, default: false) — Whether tax residency is certified. - `other_article_and_paragraph` (string, optional, nullable) — Other article and paragraph. Required when limitation_type is 'OTHER'. ### WorkersTaxFormsPostRequestBodyContentApplicationJsonSchemaDataOneOf3UsTaxNumber US Taxpayer Identification Number. - `type` (enum, required) — US tax ID type. - Allowed values: `SSN`, `ITIN` - `value` (string, required) — US tax ID value. ## Examples **Request** ```json { "data": { "form_type": "W9_INDIVIDUAL", "address": "123 Main Street", "city": "New York", "client_legal_entity_id": "00000000-0000-0000-0000-000000000000", "contractor_signature": "John Doe", "country": "US", "first_name": "John", "last_name": "Doe", "tax_number": { "type": "SSN", "value": "219-09-9999" }, "zip_code": "10001" } } ``` **Response** ```json { "data": { "id": "00000000-0000-0000-0000-000000000000", "created_at": "2026-01-15T12:00:00.000Z" } } ``` **SDK Code** ```python import requests url = "https://api.letsdeel.com/rest/workers/tax-forms" payload = { "data": { "form_type": "W9_INDIVIDUAL", "address": "123 Main Street", "city": "New York", "client_legal_entity_id": "00000000-0000-0000-0000-000000000000", "contractor_signature": "John Doe", "country": "US", "first_name": "John", "last_name": "Doe", "tax_number": { "type": "SSN", "value": "219-09-9999" }, "zip_code": "10001" } } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.letsdeel.com/rest/workers/tax-forms'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"data":{"form_type":"W9_INDIVIDUAL","address":"123 Main Street","city":"New York","client_legal_entity_id":"00000000-0000-0000-0000-000000000000","contractor_signature":"John Doe","country":"US","first_name":"John","last_name":"Doe","tax_number":{"type":"SSN","value":"219-09-9999"},"zip_code":"10001"}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.letsdeel.com/rest/workers/tax-forms" payload := strings.NewReader("{\n \"data\": {\n \"form_type\": \"W9_INDIVIDUAL\",\n \"address\": \"123 Main Street\",\n \"city\": \"New York\",\n \"client_legal_entity_id\": \"00000000-0000-0000-0000-000000000000\",\n \"contractor_signature\": \"John Doe\",\n \"country\": \"US\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"tax_number\": {\n \"type\": \"SSN\",\n \"value\": \"219-09-9999\"\n },\n \"zip_code\": \"10001\"\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.letsdeel.com/rest/workers/tax-forms") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"data\": {\n \"form_type\": \"W9_INDIVIDUAL\",\n \"address\": \"123 Main Street\",\n \"city\": \"New York\",\n \"client_legal_entity_id\": \"00000000-0000-0000-0000-000000000000\",\n \"contractor_signature\": \"John Doe\",\n \"country\": \"US\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"tax_number\": {\n \"type\": \"SSN\",\n \"value\": \"219-09-9999\"\n },\n \"zip_code\": \"10001\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.letsdeel.com/rest/workers/tax-forms") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"data\": {\n \"form_type\": \"W9_INDIVIDUAL\",\n \"address\": \"123 Main Street\",\n \"city\": \"New York\",\n \"client_legal_entity_id\": \"00000000-0000-0000-0000-000000000000\",\n \"contractor_signature\": \"John Doe\",\n \"country\": \"US\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"tax_number\": {\n \"type\": \"SSN\",\n \"value\": \"219-09-9999\"\n },\n \"zip_code\": \"10001\"\n }\n}") .asString(); ``` ```php request('POST', 'https://api.letsdeel.com/rest/workers/tax-forms', [ 'body' => '{ "data": { "form_type": "W9_INDIVIDUAL", "address": "123 Main Street", "city": "New York", "client_legal_entity_id": "00000000-0000-0000-0000-000000000000", "contractor_signature": "John Doe", "country": "US", "first_name": "John", "last_name": "Doe", "tax_number": { "type": "SSN", "value": "219-09-9999" }, "zip_code": "10001" } }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.letsdeel.com/rest/workers/tax-forms"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"data\": {\n \"form_type\": \"W9_INDIVIDUAL\",\n \"address\": \"123 Main Street\",\n \"city\": \"New York\",\n \"client_legal_entity_id\": \"00000000-0000-0000-0000-000000000000\",\n \"contractor_signature\": \"John Doe\",\n \"country\": \"US\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"tax_number\": {\n \"type\": \"SSN\",\n \"value\": \"219-09-9999\"\n },\n \"zip_code\": \"10001\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["data": [ "form_type": "W9_INDIVIDUAL", "address": "123 Main Street", "city": "New York", "client_legal_entity_id": "00000000-0000-0000-0000-000000000000", "contractor_signature": "John Doe", "country": "US", "first_name": "John", "last_name": "Doe", "tax_number": [ "type": "SSN", "value": "219-09-9999" ], "zip_code": "10001" ]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.letsdeel.com/rest/workers/tax-forms")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```