> 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 child organization POST https://api.letsdeel.com/rest/organizations/children Content-Type: application/json Creates a child organization under the authenticated parent organization. Use it to provision child organizations from your own systems instead of the Partner Portal create form. The `token` field in the response holds the child organization's API token. It is returned only once and cannot be retrieved later, so store it on receipt. **Token scopes**: `organizations:write` Reference: https://developer.deel.com/api/endpoints/organizations/create-organization-child ## 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` (OrganizationsChildrenPostRequestBodyContentApplicationJsonSchemaData, required) — The request payload. ## Response ### 201 Operation successful. The child organization was created successfully. - `data` (OrganizationsChildrenPostResponsesContentApplicationJsonSchemaData, required) ## Errors ### 400 Bad Request Error Bad request. The request body failed validation, admin_email or a parent_admin_emails entry is not an admin of the parent organization, parent_admin_emails or child_admins is sent while multiple admins are not enabled for the parent organization, or the parent organization cannot create child organizations. When the API gateway rejects the request body before it reaches Deel, each error item carries a path field instead of code, and the body also carries a request object that describes the failed call. - `errors` (list of OrganizationsChildrenPostResponsesContentApplicationJsonSchemaErrorsItems, optional) - `request` (OrganizationsChildrenPostResponsesContentApplicationJsonSchemaRequest, optional) ### 401 Unauthorized Error Operation failed. - `request` (ApiErrorRequest, optional) - `errors` (list of ApiError, optional) ### 403 Forbidden Error Operation failed. - `request` (ApiErrorRequest, optional) - `errors` (list of ApiError, optional) ### 404 Not Found Error Operation failed. - `request` (ApiErrorRequest, optional) - `errors` (list of ApiError, optional) ### 409 Conflict Error Conflict - an organization with this name is currently being created. - `errors` (list of OrganizationsChildrenPostResponsesContentApplicationJsonSchemaErrorsItems, required) ### 429 Too Many Requests Error Too Many Requests - retry limit exceeded for creating this organization. - `errors` (list of OrganizationsChildrenPostResponsesContentApplicationJsonSchemaErrorsItems, required) ### 500 Internal Server Error Operation failed. - `errors` (list of OrganizationsChildrenPostResponsesContentApplicationJsonSchemaErrorsItems, optional) ## Types ### OrganizationsChildrenPostRequestBodyContentApplicationJsonSchemaData The request payload. - `child_organization` (OrganizationsChildrenPostRequestBodyContentApplicationJsonSchemaDataChildOrganization, required) — The object that contains all the information related to the child organization that will be created. - `parent_organization` (OrganizationsChildrenPostRequestBodyContentApplicationJsonSchemaDataParentOrganization, required) — The object that contains the information related to the parent_organization. - `child_admins` (list of OrganizationsChildrenPostRequestBodyContentApplicationJsonSchemaDataChildAdminsItems, optional) — People from the child organization to add as its admins. Each person receives an invite to the child organization. - `parent_admin_emails` (list of string, optional) — More admins of the parent organization to add as admins of the child organization, as the Partner Portal create form does. Every email must belong to an existing admin of the parent organization, otherwise creation fails and no child organization is created. Each admin receives an invite to the child organization. ### OrganizationsChildrenPostResponsesContentApplicationJsonSchemaData - `id` (string, required) — The unique identifier of the created child organization. - `token` (string, required) — The API token generated for the created child organization - `created_at` (string, required) — When the created child organization was created (ISO 8601 format) - `updated_at` (string, required) — When the created child organization was updated for the last time (ISO 8601 format) ### OrganizationsChildrenPostResponsesContentApplicationJsonSchemaErrorsItems - `code` (string, optional) — Machine-readable error code - `message` (string, optional) — Human-readable explanation of the error ### OrganizationsChildrenPostResponsesContentApplicationJsonSchemaRequest - `url` (string, optional) — The relative URL of the failed request - `code` (double, optional) — The code of the source handler which produced the returned error - `docs` (string, optional) — A link to the official documentation for the requested endpoint resource - `method` (string, optional) — The HTTP method of the failed request - `source` (string, optional) — The source handler which produced the returned error - `status` (double, optional) — The status code of the response - `api_req_id` (string, optional) — The request ID of the failed request ### 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 ### OrganizationsChildrenPostRequestBodyContentApplicationJsonSchemaDataChildOrganization The object that contains all the information related to the child organization that will be created. - `name` (string, required) — The organization's name. - `department` (string, optional, default: Founder) — The department's name where the manager will be added. Defaults to "Founder" when omitted. - `is_api_enabled` (boolean, optional, default: false) — The flag that enables the public API for the child organization. Defaults to false when omitted. - `workforce_size` (integer, optional) — The workforce size of the child organization. - `headquarters_country` (string, optional) — The organization's headquarters country as an ISO 3166-1 alpha-2 code. Validated against Deel's country whitelist; unknown codes are rejected. ### OrganizationsChildrenPostRequestBodyContentApplicationJsonSchemaDataParentOrganization The object that contains the information related to the parent_organization. - `admin_email` (string, required) — The email of one of the managers of the parent organization. It must belong to an existing admin/manager of the parent organization, otherwise creation fails. This manager is the user that creates the child organization. ### OrganizationsChildrenPostRequestBodyContentApplicationJsonSchemaDataChildAdminsItems A person from the child organization who becomes one of its admins. - `email` (string, required) — The email of the person from the child organization. - `last_name` (string, required) — The last name of the person from the child organization. - `first_name` (string, required) — The first name of the person from the child organization. ## Examples **Request** ```json { "data": { "child_organization": { "name": "ACME INC." }, "parent_organization": { "admin_email": "admin@example.com" } } } ``` **Response** ```json { "data": { "id": "7cdadbfa-3f9e-4e81-95d4-d40d0cab74be", "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30", "created_at": "2025-07-06T19:51:54.000Z", "updated_at": "2025-07-06T19:51:54.000Z" } } ``` **SDK Code** ```python import requests url = "https://api.letsdeel.com/rest/organizations/children" payload = { "data": { "child_organization": { "name": "ACME INC." }, "parent_organization": { "admin_email": "admin@example.com" } } } 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/organizations/children'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"data":{"child_organization":{"name":"ACME INC."},"parent_organization":{"admin_email":"admin@example.com"}}}' }; 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/organizations/children" payload := strings.NewReader("{\n \"data\": {\n \"child_organization\": {\n \"name\": \"ACME INC.\"\n },\n \"parent_organization\": {\n \"admin_email\": \"admin@example.com\"\n }\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/organizations/children") 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 \"child_organization\": {\n \"name\": \"ACME INC.\"\n },\n \"parent_organization\": {\n \"admin_email\": \"admin@example.com\"\n }\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/organizations/children") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"data\": {\n \"child_organization\": {\n \"name\": \"ACME INC.\"\n },\n \"parent_organization\": {\n \"admin_email\": \"admin@example.com\"\n }\n }\n}") .asString(); ``` ```php request('POST', 'https://api.letsdeel.com/rest/organizations/children', [ 'body' => '{ "data": { "child_organization": { "name": "ACME INC." }, "parent_organization": { "admin_email": "admin@example.com" } } }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.letsdeel.com/rest/organizations/children"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"data\": {\n \"child_organization\": {\n \"name\": \"ACME INC.\"\n },\n \"parent_organization\": {\n \"admin_email\": \"admin@example.com\"\n }\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["data": [ "child_organization": ["name": "ACME INC."], "parent_organization": ["admin_email": "admin@example.com"] ]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.letsdeel.com/rest/organizations/children")! 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() ```