> 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 Global Payroll worker POST https://api.letsdeel.com/rest/gp/workers Content-Type: application/json Creates a Global Payroll worker and their contract in a single call, so API clients and partner integrations can onboard Global Payroll workers directly instead of using the legacy `POST /rest/contracts/gp` flow. No invitation email is sent to the worker unless the request asks for one. **Token scopes**: `contracts:write` **Beta**: this version requires the `X-Beta: true` request header and its contract may change before it is promoted to stable. It is scheduled to become stable on 2027-01-12. Reference: https://developer.deel.com/api/reference/endpoints/global-payroll/create-gp-worker-v-2026-10-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 ### Headers - `X-Beta` (enum, required, default: true) — Opts in to the beta version of this endpoint. Must be `true`. - Allowed values: `true` ### Body (application/json) This endpoint expects an object. - `data` (GpWorkersPostRequestBodyContentApplicationJsonSchemaData, required) ## Response ### 201 The worker and their contract were created. `data.id` is the contract id; `data.employee.id` is the worker id to use with the other Global Payroll worker endpoints. - `data` (GpWorkersPostResponsesContentApplicationJsonSchemaData, required) ## Errors ### 400 Bad Request Error Bad request. Codes: validation_error (the body is invalid; field names the offending property), invalid_payroll_group (the payroll group is missing, inactive, not a Global Payroll group or in another legal entity), currency_not_allowed (not allowed for the legal entity country), work_location_required (US legal entities), contract_state_required (the country needs contract_state), entity_integration_active (the legal entity has an active HR integration). - `errors` (list of GpWorkersPostResponsesContentApplicationJsonSchemaErrorsItems, required) ### 401 Unauthorized Error The authentication is missing or is invalid. - `errors` (list of GpWorkersPostResponsesContentApplicationJsonSchemaErrorsItems, required) ### 403 Forbidden Error Forbidden. Codes: team_permission_denied (the caller cannot create contracts in the team), forbidden (the caller's organization cannot use this endpoint). - `errors` (list of GpWorkersPostResponsesContentApplicationJsonSchemaErrorsItems, required) ### 404 Not Found Error Not found. Codes: legal_entity_not_found, team_not_found, entity_address_not_found. The referenced resource does not exist or does not belong to your organization. - `errors` (list of GpWorkersPostResponsesContentApplicationJsonSchemaErrorsItems, required) ### 409 Conflict Error Conflict. Codes: worker_already_exists (the external_id or the email already has a worker or active contract in this legal entity; details carry worker_id and contract_id), external_id_mismatch (the email belongs to a worker with a different external_id), employee_number_taken (the employee number is used in this legal entity), creation_in_progress (an identical create is still running, retry shortly). - `errors` (list of GpWorkersPostResponsesContentApplicationJsonSchemaErrorsItems, required) ### 500 Internal Server Error An unexpected error occurred while creating the worker. - `errors` (list of GpWorkersPostResponsesContentApplicationJsonSchemaErrorsItems, required) ## Types ### GpWorkersPostRequestBodyContentApplicationJsonSchemaData - `team_id` (string, required) — Identifier of the team the contract is created in. It must belong to your organization and the caller needs permission to create contracts in it. - `job_title` (string, required) — Job title of the worker. - `start_date` (string, required) — Employment start date, in YYYY-MM-DD format. The payroll start date defaults to it. - `compensation` (GpWorkersPostRequestBodyContentApplicationJsonSchemaDataCompensation, required) — Base compensation of the worker. - `home_address` (GpWorkersPostRequestBodyContentApplicationJsonSchemaDataHomeAddress, required) — Home address of the worker. - `personal_info` (GpWorkersPostRequestBodyContentApplicationJsonSchemaDataPersonalInfo, required) — Personal details of the worker. - `employment_type` (enum, required) — Employment type of the worker. - Allowed values: `FULL_TIME`, `PART_TIME` - `legal_entity_id` (string, required) — Identifier of the Global Payroll legal entity the worker is employed by. It must belong to your organization. - `payroll_group_id` (string, required) — Identifier of the active Global Payroll payroll group of the legal entity the worker is paid in. - `pto` (GpWorkersPostRequestBodyContentApplicationJsonSchemaDataPto, optional) — Paid time off settings for the worker. - `external_id` (string, optional) — Identifier of the worker in your own system. It must be unique within your organization. - `work_location` (GpWorkersPostRequestBodyContentApplicationJsonSchemaDataWorkLocation, optional) — Where the worker works. Required when the legal entity is in the United States. - `contract_state` (string, optional) — State or province code the contract is governed by. Required when the legal entity country has provinces enabled for Global Payroll (for example CA, US, AU, BR, IN) and must be one of its provinces. - `fte_percentage` (integer, optional) — Full-time equivalent percentage, from 1 to 99. Required when employment_type is PART_TIME and not allowed when it is FULL_TIME. - `employee_number` (string, optional) — Employee number in your payroll system. Required when the payroll group is a Payroll Connect (Soft GP) group. It must be unique within the legal entity. - `should_invite_employee_to_app` (boolean, optional, default: false) — Whether to email the worker an invitation to join Deel. Defaults to false. ### GpWorkersPostResponsesContentApplicationJsonSchemaData - `id` (string, optional) — Id of the contract created. - `type` (enum, optional) — Type of a contract. - Allowed values: `ongoing_time_based`, `milestones`, `time_based`, `pay_as_you_go_time_based`, `commission`, `payg_milestones`, `payg_tasks`, `eor`, `unknown`, `employee`, `global_payroll`, `shield_msa`, `hris_direct_employee`, `peo` - `client` (GpWorkersPostResponsesContentApplicationJsonSchemaDataClient, optional) - `status` (enum, optional) — Status of a contract in Deel workflow. - Allowed values: `new`, `under_review`, `waiting_for_employee_contract`, `waiting_for_client_sign`, `processing_payment`, `waiting_for_contractor_sign`, `waiting_for_eor_sign`, `waiting_for_employee_sign`, `awaiting_deposit_payment`, `in_progress`, `completed`, `cancelled`, `user_cancelled`, `rejected`, `waiting_for_client_payment`, `onboarding` - `employee` (GpWorkersPostResponsesContentApplicationJsonSchemaDataEmployee, optional) - `job_title` (string, optional) — Employee's job title. - `created_at` (string, optional, nullable) — Long date-time format following ISO-8601. - `employment` (GpWorkersPostResponsesContentApplicationJsonSchemaDataEmployment, optional) - `compensation_details` (GpWorkersPostResponsesContentApplicationJsonSchemaDataCompensationDetails, optional) ### GpWorkersPostResponsesContentApplicationJsonSchemaErrorsItems - `code` (string, required) — Machine-readable error code. - `message` (string, required) — Human-readable explanation of the error. - `field` (string, optional) — Path of the request field the error refers to, when the error is caused by a single field. - `details` (GpWorkersPostResponsesContentApplicationJsonSchemaErrorsItemsDetails, optional) — Extra machine-readable context. Conflict errors carry the worker_id and contract_id of the existing record; currency_not_allowed carries allowed_currencies. ### GpWorkersPostRequestBodyContentApplicationJsonSchemaDataCompensation Base compensation of the worker. - `scale` (enum, required) — Period the amount is paid for. - Allowed values: `ANNUALLY`, `MONTHLY`, `BI_MONTHLY`, `TWO_WEEKLY`, `WEEKLY`, `DAILY`, `HOURLY` - `amount` (double, required) — Base compensation amount per scale period. - `currency` (string, required) — ISO 4217 currency code. It must be one of the currencies allowed for the legal entity country. - `type` (enum, optional, default: SALARIED) — Whether the worker is salaried or paid hourly. Defaults to SALARIED. - Allowed values: `SALARIED`, `HOURLY` ### GpWorkersPostRequestBodyContentApplicationJsonSchemaDataHomeAddress Home address of the worker. - `zip` (string, required) — Postal code. - `city` (string, required) — City. - `street` (string, required) — Street and number. - `country` (string, required) — Country of the home address as an ISO 3166-1 alpha-2 code. - `state` (string, optional) — State, province or region. ### GpWorkersPostRequestBodyContentApplicationJsonSchemaDataPersonalInfo Personal details of the worker. - `email` (string, required) — Personal email address of the worker. It identifies the worker within your organization. - `last_name` (string, required) — Last name of the worker. - `first_name` (string, required) — First name of the worker. - `work_email` (string, optional) — Work email address of the worker. - `nationality` (string, optional) — Nationality of the worker as an ISO 3166-1 alpha-2 country code. - `date_of_birth` (string, optional) — Date of birth of the worker, in YYYY-MM-DD format. ### GpWorkersPostRequestBodyContentApplicationJsonSchemaDataPto Paid time off settings for the worker. - `start_date` (string, optional) — Date paid time off starts accruing, in YYYY-MM-DD format. - `yearly_allowance` (double, optional) — Number of paid time off days granted per year. ### GpWorkersPostRequestBodyContentApplicationJsonSchemaDataWorkLocation Where the worker works. Required when the legal entity is in the United States. - `is_remote` (boolean, required) — Whether the worker works remotely rather than from an entity office. - `name` (string, optional) — Name of an active address of the legal entity, as shown in the app. Alternative to entity_address_id when is_remote is false. 'Remote' is accepted and means a remote worker. - `effective_date` (string, optional) — Date from which the work location applies. Defaults to start_date. - `entity_address_id` (string, optional) — Identifier of an active address of the legal entity. When is_remote is false, provide either this or name. ### GpWorkersPostResponsesContentApplicationJsonSchemaDataClient - `legal_entity` (GpWorkersPostResponsesContentApplicationJsonSchemaDataClientLegalEntity, optional) ### GpWorkersPostResponsesContentApplicationJsonSchemaDataEmployee - `id` (string, optional) — Worker id. Use it with the other Global Payroll worker endpoints (`/rest/gp/workers/{worker_id}/...`). - `email` (string, optional) — Employee's email address. - `last_name` (string, optional) — Employee's last name. - `first_name` (string, optional) — Employee's first name. - `employee_number` (string, optional, nullable) — Employee's number. ### GpWorkersPostResponsesContentApplicationJsonSchemaDataEmployment - `type` (string, optional) — Is it a full-time contract or a part-time contract? - `state` (string, optional, nullable) — State code of the state/province where this person will be employed. - `country` (string, optional) — Country of employment. - `end_date` (string, optional, nullable) — Long date-time format following ISO-8601. - `holidays` (GpWorkersPostResponsesContentApplicationJsonSchemaDataEmploymentHolidays, optional) - `start_date` (string, optional, nullable) — Long date-time format following ISO-8601. - `is_work_visa_required` (boolean, optional) — Do you require Deel to apply for a work visa for this person? ### GpWorkersPostResponsesContentApplicationJsonSchemaDataCompensationDetails - `scale` (string, optional) — Scale at which the salary is paid. - `salary` (double, optional) — Gross annual/month salary. - `currency` (string, optional) — Currency of gross annual/month salary. ### GpWorkersPostResponsesContentApplicationJsonSchemaErrorsItemsDetails Extra machine-readable context. Conflict errors carry the worker_id and contract_id of the existing record; currency_not_allowed carries allowed_currencies. - `worker_id` (string, optional, nullable) — Id of the existing worker the request conflicts with. - `contract_id` (string, optional, nullable) — Id of the existing contract the request conflicts with. - `allowed_currencies` (list of string, optional) — Currencies the legal entity may pay in, when the requested currency is not allowed. ### GpWorkersPostResponsesContentApplicationJsonSchemaDataClientLegalEntity - `name` (string, optional) — Legal entity name. ### GpWorkersPostResponsesContentApplicationJsonSchemaDataEmploymentHolidays - `allowance` (double, optional) — Number of holidays. - `start_date` (string, optional, nullable) — Long date-time format following ISO-8601. ## Examples **Request** ```json { "data": { "team_id": "0a9e5d74-2c18-4b6f-8d3a-5f1c7b92e406", "job_title": "Software Engineer", "start_date": "2026-11-02", "compensation": { "scale": "ANNUALLY", "amount": 65000, "currency": "EUR" }, "home_address": { "zip": "1100-053", "city": "Lisbon", "street": "Rua Augusta 100", "country": "PT" }, "personal_info": { "email": "ana.silva@example.com", "last_name": "Silva", "first_name": "Ana" }, "employment_type": "FULL_TIME", "legal_entity_id": "b4f1a6c2-5d3e-4f8a-9c21-7e0d6a3b1f55", "payroll_group_id": "pg_2f9c1e7a" } } ``` **Response** ```json { "data": { "id": "c9f8a1b2-1234-5678-9abc-1234567890ab", "type": "global_payroll", "client": { "legal_entity": { "name": "Acme Corporation Ltd." } }, "status": "completed", "employee": { "id": "9b2e1c5a-6f3d-4a8b-9c1e-2d4f6a8b0c3e", "email": "jane.doe@example.com", "last_name": "Doe", "first_name": "Jane", "employee_number": "EMP-1001" }, "job_title": "Designer", "created_at": "2024-06-15T10:30:00.000Z", "employment": { "type": "Full-time", "state": "CA", "country": "US", "end_date": "2025-06-15T00:00:00.000Z", "holidays": { "allowance": 20, "start_date": "2024-01-01T00:00:00.000Z" }, "start_date": "2024-01-01T00:00:00.000Z", "is_work_visa_required": true }, "compensation_details": { "scale": "YEAR", "salary": 85000, "currency": "USD" } } } ``` **SDK Code** ```python import requests url = "https://api.letsdeel.com/rest/gp/workers" payload = { "data": { "team_id": "0a9e5d74-2c18-4b6f-8d3a-5f1c7b92e406", "job_title": "Software Engineer", "start_date": "2026-11-02", "compensation": { "scale": "ANNUALLY", "amount": 65000, "currency": "EUR" }, "home_address": { "zip": "1100-053", "city": "Lisbon", "street": "Rua Augusta 100", "country": "PT" }, "personal_info": { "email": "ana.silva@example.com", "last_name": "Silva", "first_name": "Ana" }, "employment_type": "FULL_TIME", "legal_entity_id": "b4f1a6c2-5d3e-4f8a-9c21-7e0d6a3b1f55", "payroll_group_id": "pg_2f9c1e7a" } } headers = { "X-Beta": "true", "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/gp/workers'; const options = { method: 'POST', headers: { 'X-Beta': 'true', Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: '{"data":{"team_id":"0a9e5d74-2c18-4b6f-8d3a-5f1c7b92e406","job_title":"Software Engineer","start_date":"2026-11-02","compensation":{"scale":"ANNUALLY","amount":65000,"currency":"EUR"},"home_address":{"zip":"1100-053","city":"Lisbon","street":"Rua Augusta 100","country":"PT"},"personal_info":{"email":"ana.silva@example.com","last_name":"Silva","first_name":"Ana"},"employment_type":"FULL_TIME","legal_entity_id":"b4f1a6c2-5d3e-4f8a-9c21-7e0d6a3b1f55","payroll_group_id":"pg_2f9c1e7a"}}' }; 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/gp/workers" payload := strings.NewReader("{\n \"data\": {\n \"team_id\": \"0a9e5d74-2c18-4b6f-8d3a-5f1c7b92e406\",\n \"job_title\": \"Software Engineer\",\n \"start_date\": \"2026-11-02\",\n \"compensation\": {\n \"scale\": \"ANNUALLY\",\n \"amount\": 65000,\n \"currency\": \"EUR\"\n },\n \"home_address\": {\n \"zip\": \"1100-053\",\n \"city\": \"Lisbon\",\n \"street\": \"Rua Augusta 100\",\n \"country\": \"PT\"\n },\n \"personal_info\": {\n \"email\": \"ana.silva@example.com\",\n \"last_name\": \"Silva\",\n \"first_name\": \"Ana\"\n },\n \"employment_type\": \"FULL_TIME\",\n \"legal_entity_id\": \"b4f1a6c2-5d3e-4f8a-9c21-7e0d6a3b1f55\",\n \"payroll_group_id\": \"pg_2f9c1e7a\"\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-Beta", "true") 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/gp/workers") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["X-Beta"] = 'true' request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"data\": {\n \"team_id\": \"0a9e5d74-2c18-4b6f-8d3a-5f1c7b92e406\",\n \"job_title\": \"Software Engineer\",\n \"start_date\": \"2026-11-02\",\n \"compensation\": {\n \"scale\": \"ANNUALLY\",\n \"amount\": 65000,\n \"currency\": \"EUR\"\n },\n \"home_address\": {\n \"zip\": \"1100-053\",\n \"city\": \"Lisbon\",\n \"street\": \"Rua Augusta 100\",\n \"country\": \"PT\"\n },\n \"personal_info\": {\n \"email\": \"ana.silva@example.com\",\n \"last_name\": \"Silva\",\n \"first_name\": \"Ana\"\n },\n \"employment_type\": \"FULL_TIME\",\n \"legal_entity_id\": \"b4f1a6c2-5d3e-4f8a-9c21-7e0d6a3b1f55\",\n \"payroll_group_id\": \"pg_2f9c1e7a\"\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/gp/workers") .header("X-Beta", "true") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"data\": {\n \"team_id\": \"0a9e5d74-2c18-4b6f-8d3a-5f1c7b92e406\",\n \"job_title\": \"Software Engineer\",\n \"start_date\": \"2026-11-02\",\n \"compensation\": {\n \"scale\": \"ANNUALLY\",\n \"amount\": 65000,\n \"currency\": \"EUR\"\n },\n \"home_address\": {\n \"zip\": \"1100-053\",\n \"city\": \"Lisbon\",\n \"street\": \"Rua Augusta 100\",\n \"country\": \"PT\"\n },\n \"personal_info\": {\n \"email\": \"ana.silva@example.com\",\n \"last_name\": \"Silva\",\n \"first_name\": \"Ana\"\n },\n \"employment_type\": \"FULL_TIME\",\n \"legal_entity_id\": \"b4f1a6c2-5d3e-4f8a-9c21-7e0d6a3b1f55\",\n \"payroll_group_id\": \"pg_2f9c1e7a\"\n }\n}") .asString(); ``` ```php request('POST', 'https://api.letsdeel.com/rest/gp/workers', [ 'body' => '{ "data": { "team_id": "0a9e5d74-2c18-4b6f-8d3a-5f1c7b92e406", "job_title": "Software Engineer", "start_date": "2026-11-02", "compensation": { "scale": "ANNUALLY", "amount": 65000, "currency": "EUR" }, "home_address": { "zip": "1100-053", "city": "Lisbon", "street": "Rua Augusta 100", "country": "PT" }, "personal_info": { "email": "ana.silva@example.com", "last_name": "Silva", "first_name": "Ana" }, "employment_type": "FULL_TIME", "legal_entity_id": "b4f1a6c2-5d3e-4f8a-9c21-7e0d6a3b1f55", "payroll_group_id": "pg_2f9c1e7a" } }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', 'X-Beta' => 'true', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.letsdeel.com/rest/gp/workers"); var request = new RestRequest(Method.POST); request.AddHeader("X-Beta", "true"); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"data\": {\n \"team_id\": \"0a9e5d74-2c18-4b6f-8d3a-5f1c7b92e406\",\n \"job_title\": \"Software Engineer\",\n \"start_date\": \"2026-11-02\",\n \"compensation\": {\n \"scale\": \"ANNUALLY\",\n \"amount\": 65000,\n \"currency\": \"EUR\"\n },\n \"home_address\": {\n \"zip\": \"1100-053\",\n \"city\": \"Lisbon\",\n \"street\": \"Rua Augusta 100\",\n \"country\": \"PT\"\n },\n \"personal_info\": {\n \"email\": \"ana.silva@example.com\",\n \"last_name\": \"Silva\",\n \"first_name\": \"Ana\"\n },\n \"employment_type\": \"FULL_TIME\",\n \"legal_entity_id\": \"b4f1a6c2-5d3e-4f8a-9c21-7e0d6a3b1f55\",\n \"payroll_group_id\": \"pg_2f9c1e7a\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "X-Beta": "true", "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["data": [ "team_id": "0a9e5d74-2c18-4b6f-8d3a-5f1c7b92e406", "job_title": "Software Engineer", "start_date": "2026-11-02", "compensation": [ "scale": "ANNUALLY", "amount": 65000, "currency": "EUR" ], "home_address": [ "zip": "1100-053", "city": "Lisbon", "street": "Rua Augusta 100", "country": "PT" ], "personal_info": [ "email": "ana.silva@example.com", "last_name": "Silva", "first_name": "Ana" ], "employment_type": "FULL_TIME", "legal_entity_id": "b4f1a6c2-5d3e-4f8a-9c21-7e0d6a3b1f55", "payroll_group_id": "pg_2f9c1e7a" ]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.letsdeel.com/rest/gp/workers")! 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() ```