# Create child organization

POST https://api.letsdeel.com/rest/v2/organizations/children
Content-Type: application/json

Creates a new organization along with:

- An API token scoped to the new organization. This token can be used to perform API operations on behalf of the new organization.
- A default group for the organization.
- A hierarchy linking the authenticated organization (the Parent Organization) with the new one (the Child Organization).
- A user from the parent organization who will be assigned to the child organization.

This endpoint sets up the bare minimum required for the new organization to be operational immediately after creation.
 **Token scopes**: `organizations:write`

Reference: https://developer.deel.com/api/endpoints/organizations/create-organization-child

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: Deel HRIS SCIM API
  version: 1.0.0
paths:
  /organizations/children:
    post:
      operationId: create-organization-child
      summary: Create child organization
      description: >-
        Creates a new organization along with:


        - An API token scoped to the new organization. This token can be used to
        perform API operations on behalf of the new organization.

        - A default group for the organization.

        - A hierarchy linking the authenticated organization (the Parent
        Organization) with the new one (the Child Organization).

        - A user from the parent organization who will be assigned to the child
        organization.


        This endpoint sets up the bare minimum required for the new organization
        to be operational immediately after creation.
         **Token scopes**: `organizations:write`
      tags:
        - subpackage_organizations
      parameters:
        - name: Authorization
          in: header
          description: >
            ## 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)
          required: true
          schema:
            type: string
      responses:
        '201':
          description: >-
            Operation successful. The child organization was created
            successfully.
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/organizations_createOrganizationChild_Response_201
        '400':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/CreateChildOrganizationRequestBadRequestError
        '401':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '403':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '404':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '500':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: >-
                    #/components/schemas/OrganizationsChildrenPostRequestBodyContentApplicationJsonSchemaData
                  description: The request payload.
              required:
                - data
servers:
  - url: https://api.letsdeel.com/rest/v2
  - url: https://api-staging.letsdeel.com/rest/v2
components:
  schemas:
    OrganizationsChildrenPostRequestBodyContentApplicationJsonSchemaDataChildOrganization:
      type: object
      properties:
        name:
          type: string
          description: The organization's name.
        department:
          type: string
          description: The department's name where the manager will be added
        is_api_enabled:
          type: boolean
          description: The flag that enables the public API for the child organization.
        workforce_size:
          type: integer
          description: The workforce size of the child organization.
        headquarters_country:
          type: string
          description: The 2-letter country code of the organization's headquarters.
      required:
        - name
      description: >-
        The object that contains all the information related to the child
        organization that will be created.
      title: >-
        OrganizationsChildrenPostRequestBodyContentApplicationJsonSchemaDataChildOrganization
    OrganizationsChildrenPostRequestBodyContentApplicationJsonSchemaDataParentOrganization:
      type: object
      properties:
        admin_email:
          type: string
          description: >-
            The email of one of the managers of the parent organization that
            will be used to create an user for the child organization, it should
            exists on the parent organization.
      description: >-
        The object that contains the information related to the
        parent_organization.
      title: >-
        OrganizationsChildrenPostRequestBodyContentApplicationJsonSchemaDataParentOrganization
    OrganizationsChildrenPostRequestBodyContentApplicationJsonSchemaData:
      type: object
      properties:
        child_organization:
          $ref: >-
            #/components/schemas/OrganizationsChildrenPostRequestBodyContentApplicationJsonSchemaDataChildOrganization
          description: >-
            The object that contains all the information related to the child
            organization that will be created.
        parent_organization:
          $ref: >-
            #/components/schemas/OrganizationsChildrenPostRequestBodyContentApplicationJsonSchemaDataParentOrganization
          description: >-
            The object that contains the information related to the
            parent_organization.
      required:
        - child_organization
        - parent_organization
      description: The request payload.
      title: OrganizationsChildrenPostRequestBodyContentApplicationJsonSchemaData
    OrganizationsChildrenPostResponsesContentApplicationJsonSchemaData:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the created child organization.
        token:
          type: string
          description: The API token generated for the created child organization
        created_at:
          type: string
          format: date-time
          description: When the created child organization was created (ISO 8601 format)
        updated_at:
          type: string
          format: date-time
          description: >-
            When the created child organization was updated for the last time
            (ISO 8601 format)
      required:
        - id
        - token
        - created_at
        - updated_at
      title: OrganizationsChildrenPostResponsesContentApplicationJsonSchemaData
    organizations_createOrganizationChild_Response_201:
      type: object
      properties:
        data:
          $ref: >-
            #/components/schemas/OrganizationsChildrenPostResponsesContentApplicationJsonSchemaData
      required:
        - data
      title: organizations_createOrganizationChild_Response_201
    OrganizationsChildrenPostResponsesContentApplicationJsonSchemaErrorsItems:
      type: object
      properties:
        path:
          type: string
          description: The JSON path where input validation failed
        message:
          type: string
          description: A description of the returned error
      title: >-
        OrganizationsChildrenPostResponsesContentApplicationJsonSchemaErrorsItems
    OrganizationsChildrenPostResponsesContentApplicationJsonSchemaRequest:
      type: object
      properties:
        url:
          type: string
          description: The relative URL of the failed request
        code:
          type: number
          format: double
          description: The code of the source handler which produced the returned error
        docs:
          type: string
          description: >-
            A link to the official documentation for the requested endpoint
            resource
        method:
          type: string
          description: The HTTP method of the failed request
        source:
          type: string
          description: The source handler which produced the returned error
        status:
          type: number
          format: double
          description: The status code of the response
        api_req_id:
          type: string
          description: The request ID of the failed request
      title: OrganizationsChildrenPostResponsesContentApplicationJsonSchemaRequest
    CreateChildOrganizationRequestBadRequestError:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: >-
              #/components/schemas/OrganizationsChildrenPostResponsesContentApplicationJsonSchemaErrorsItems
        request:
          $ref: >-
            #/components/schemas/OrganizationsChildrenPostResponsesContentApplicationJsonSchemaRequest
      title: CreateChildOrganizationRequestBadRequestError
    ApiErrorRequest:
      type: object
      properties:
        method:
          type: string
          description: The HTTP method of the failed request
        url:
          type: string
          description: The relative URL of the failed request
        status:
          type: number
          format: double
          description: The status code of the response
        api_req_id:
          type: string
          description: The request ID of the failed request
        docs:
          type: string
          description: >-
            A link to the official documentation for the requested endpoint
            resource
        source:
          type: string
          description: The source handler which produced the returned error
        code:
          type: number
          format: double
          description: The code of the source handler which produced the returned error
      title: ApiErrorRequest
    ApiError:
      type: object
      properties:
        message:
          type: string
          description: A description of the returned error
        path:
          type: string
          description: The JSON path where input validation failed
      title: ApiError
    ApiErrorContainer:
      type: object
      properties:
        request:
          $ref: '#/components/schemas/ApiErrorRequest'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiError'
      title: ApiErrorContainer
  securitySchemes:
    deelToken:
      type: http
      scheme: bearer
      description: >
        ## 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)
    oauth2:
      type: http
      scheme: bearer
      description: >-
        Standard OAuth2 security scheme based on
        https://swagger.io/docs/specification/authentication/

```

## SDK Code Examples

```python
import requests

url = "https://api.letsdeel.com/rest/v2/organizations/children"

payload = { "data": {
        "child_organization": { "name": "ACME INC." },
        "parent_organization": {}
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.letsdeel.com/rest/v2/organizations/children';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"data":{"child_organization":{"name":"ACME INC."},"parent_organization":{}}}'
};

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/v2/organizations/children"

	payload := strings.NewReader("{\n  \"data\": {\n    \"child_organization\": {\n      \"name\": \"ACME INC.\"\n    },\n    \"parent_organization\": {}\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	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/v2/organizations/children")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"data\": {\n    \"child_organization\": {\n      \"name\": \"ACME INC.\"\n    },\n    \"parent_organization\": {}\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.letsdeel.com/rest/v2/organizations/children")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"data\": {\n    \"child_organization\": {\n      \"name\": \"ACME INC.\"\n    },\n    \"parent_organization\": {}\n  }\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.letsdeel.com/rest/v2/organizations/children', [
  'body' => '{
  "data": {
    "child_organization": {
      "name": "ACME INC."
    },
    "parent_organization": {}
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.letsdeel.com/rest/v2/organizations/children");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"data\": {\n    \"child_organization\": {\n      \"name\": \"ACME INC.\"\n    },\n    \"parent_organization\": {}\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["data": [
    "child_organization": ["name": "ACME INC."],
    "parent_organization": []
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.letsdeel.com/rest/v2/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()
```