> 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. # Update a tax form for the authenticated worker PUT https://api.letsdeel.com/rest/workers/tax-forms/{tax_form_id} Content-Type: application/json Replace the authenticated worker's existing tax form with a corrected version, for example to fix a mistyped tax identification number, legal name or address. The worker is resolved from the access token and only their own forms are addressable. The body is the complete form rather than a partial update: an optional field left out is cleared, except contractor_signature, which keeps the value already on file when omitted — it must be supplied when the stored form carries no signature. client_legal_entity_id is not accepted — the legal entity is part of the form's uniqueness key and can never be reassigned. The worker must have an active (non-terminated) contract with the form's legal entity. Editing a form whose 1099 has already been filed with the IRS is permitted but does not refile it. **Token scopes**: `worker:write` Reference: https://developer.deel.com/api/reference/endpoints/workers/replace-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 ### Path parameters - `tax_form_id` (string, required) — Public ID (UUID) of the tax form to replace, as returned by the create or list endpoints. ### Body (application/json) This endpoint expects an object. - `data` (WorkersTaxFormsTaxFormIdPutRequestBodyContentApplicationJsonSchemaData, required) ## Response ### 200 Tax form replaced successfully. - `data` (WorkersTaxFormsTaxFormIdPutResponsesContentApplicationJsonSchemaData, required) ## Errors ### 400 Bad Request Error Validation failed — for example a request body field is missing or malformed, client_legal_entity_id was supplied (the legal entity cannot be reassigned), contractor_signature was omitted for a form that has no signature on record, 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 WorkersTaxFormsTaxFormIdPutResponsesContentApplicationJsonSchemaErrorsItems, 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 tax form's client legal entity. A tax form can only be edited while the contractor has a non-terminated contract with that legal entity. - `errors` (list of WorkersTaxFormsTaxFormIdPutResponsesContentApplicationJsonSchemaErrorsItems, optional) ### 404 Not Found Error The tax form does not exist or does not belong to the authenticated worker, or the worker was not found in the calling organization or has no contractor profile. - `errors` (list of WorkersTaxFormsTaxFormIdPutResponsesContentApplicationJsonSchemaErrorsItems, optional) ### 409 Conflict Error The tax form was replaced by another request while this one was in flight. Fetch the current version and retry the edit. - `errors` (list of WorkersTaxFormsTaxFormIdPutResponsesContentApplicationJsonSchemaErrorsItems, optional) ### 500 Internal Server Error Internal server error. - `errors` (list of WorkersTaxFormsTaxFormIdPutResponsesContentApplicationJsonSchemaErrorsItems, optional) ## Types ### WorkersTaxFormsTaxFormIdPutRequestBodyContentApplicationJsonSchemaData - `form_type`: `W9_INDIVIDUAL` (W9_INDIVIDUAL) - `address` (string, required) — Street address. Maximum 40 characters for 1099 reporting compliance. - `city` (string, required) — City name. - `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` (WorkersTaxFormsTaxFormIdPutRequestBodyContentApplicationJsonSchemaDataOneOf0TaxNumber, 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. - `contractor_signature` (string, optional) — Contractor's digital signature. - `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. - `country` (string, required) — ISO 3166-1 alpha-2 country code. - `federal_tax_classification` (WorkersTaxFormsTaxFormIdPutRequestBodyContentApplicationJsonSchemaDataOneOf1FederalTaxClassification, required) — Federal tax classification. - `tax_number` (WorkersTaxFormsTaxFormIdPutRequestBodyContentApplicationJsonSchemaDataOneOf1TaxNumber, required) — Taxpayer identification number. - `zip_code` (string, required) — ZIP/postal code. - `contractor_signature` (string, optional) — Authorized signer's digital signature. - `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. - `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. - `contractor_signature` (string, optional) — Contractor's digital signature. - `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` (WorkersTaxFormsTaxFormIdPutRequestBodyContentApplicationJsonSchemaDataOneOf2MailingAddress, 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` (WorkersTaxFormsTaxFormIdPutRequestBodyContentApplicationJsonSchemaDataOneOf2TaxNumber, 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` (WorkersTaxFormsTaxFormIdPutRequestBodyContentApplicationJsonSchemaDataOneOf2TaxTreatyBenefitsForm, optional, nullable) — Tax treaty benefits details. Applicable when is_tax_treaty_enabled is true. - `us_tax_number` (WorkersTaxFormsTaxFormIdPutRequestBodyContentApplicationJsonSchemaDataOneOf2UsTaxNumber, optional) — US Taxpayer Identification Number. - `form_type`: `W8_BEN_E` (W8_BEN_E) - `address` (string, required) — Street address. - `city` (string, required) — City of residence. - `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. - `contractor_signature` (string, optional) — Authorized signer's digital signature. - `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` (WorkersTaxFormsTaxFormIdPutRequestBodyContentApplicationJsonSchemaDataOneOf3MailingAddress, 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` (WorkersTaxFormsTaxFormIdPutRequestBodyContentApplicationJsonSchemaDataOneOf3TaxNumber, 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` (WorkersTaxFormsTaxFormIdPutRequestBodyContentApplicationJsonSchemaDataOneOf3TaxTreatyBenefitsForm, optional, nullable) — Tax treaty benefits details. - `us_tax_number` (WorkersTaxFormsTaxFormIdPutRequestBodyContentApplicationJsonSchemaDataOneOf3UsTaxNumber, optional) — US Taxpayer Identification Number. ### WorkersTaxFormsTaxFormIdPutResponsesContentApplicationJsonSchemaData - `id` (string, required) — The public ID (UUID) of the tax form. - `created_at` (string, required) — Timestamp of when the tax form was created. - `updated_at` (string, required) — Timestamp of when the tax form was last updated. ### WorkersTaxFormsTaxFormIdPutResponsesContentApplicationJsonSchemaErrorsItems - `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 ### WorkersTaxFormsTaxFormIdPutRequestBodyContentApplicationJsonSchemaDataOneOf0TaxNumber 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. ### WorkersTaxFormsTaxFormIdPutRequestBodyContentApplicationJsonSchemaDataOneOf1FederalTaxClassification 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'. ### WorkersTaxFormsTaxFormIdPutRequestBodyContentApplicationJsonSchemaDataOneOf1TaxNumber 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. ### WorkersTaxFormsTaxFormIdPutRequestBodyContentApplicationJsonSchemaDataOneOf2MailingAddress 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. ### WorkersTaxFormsTaxFormIdPutRequestBodyContentApplicationJsonSchemaDataOneOf2TaxNumber 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. ### WorkersTaxFormsTaxFormIdPutRequestBodyContentApplicationJsonSchemaDataOneOf2TaxTreatyBenefitsForm 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. ### WorkersTaxFormsTaxFormIdPutRequestBodyContentApplicationJsonSchemaDataOneOf2UsTaxNumber US Taxpayer Identification Number. - `type` (enum, required) — US tax ID type. - Allowed values: `SSN`, `ITIN` - `value` (string, required) — US tax ID value. ### WorkersTaxFormsTaxFormIdPutRequestBodyContentApplicationJsonSchemaDataOneOf3MailingAddress 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. ### WorkersTaxFormsTaxFormIdPutRequestBodyContentApplicationJsonSchemaDataOneOf3TaxNumber 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. ### WorkersTaxFormsTaxFormIdPutRequestBodyContentApplicationJsonSchemaDataOneOf3TaxTreatyBenefitsForm 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'. ### WorkersTaxFormsTaxFormIdPutRequestBodyContentApplicationJsonSchemaDataOneOf3UsTaxNumber 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", "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", "updated_at": "2026-01-15T12:00:00.000Z" } } ``` **SDK Code** ```python import requests url = "https://api.letsdeel.com/rest/workers/tax-forms/00000000-0000-0000-0000-000000000000" payload = { "data": { "form_type": "W9_INDIVIDUAL", "address": "123 Main Street", "city": "New York", "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.put(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.letsdeel.com/rest/workers/tax-forms/00000000-0000-0000-0000-000000000000'; const options = { method: 'PUT', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"data":{"form_type":"W9_INDIVIDUAL","address":"123 Main Street","city":"New York","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/00000000-0000-0000-0000-000000000000" payload := strings.NewReader("{\n \"data\": {\n \"form_type\": \"W9_INDIVIDUAL\",\n \"address\": \"123 Main Street\",\n \"city\": \"New York\",\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("PUT", 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/00000000-0000-0000-0000-000000000000") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Put.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 \"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.put("https://api.letsdeel.com/rest/workers/tax-forms/00000000-0000-0000-0000-000000000000") .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 \"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('PUT', 'https://api.letsdeel.com/rest/workers/tax-forms/00000000-0000-0000-0000-000000000000', [ 'body' => '{ "data": { "form_type": "W9_INDIVIDUAL", "address": "123 Main Street", "city": "New York", "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/00000000-0000-0000-0000-000000000000"); var request = new RestRequest(Method.PUT); 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 \"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", "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/00000000-0000-0000-0000-000000000000")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PUT" 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() ```