> 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
> - Beta: https://developer.deel.com/api/beta/llms.txt
> - Deprecated: https://developer.deel.com/api/deprecated/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 Child Account onboarding intent

POST https://api.letsdeel.com/rest/intents/child-account-onboardings
Content-Type: application/json

Opens the intent that sets up the payment method of a Child Account. Name the Child Account and the person who signs for it. The answer lists the steps that are due. A Child Account has one open intent at a time. A repeat with the same Idempotency-Key and body returns the first intent.

 **Token scopes**: `organizations: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-02-16.

Reference: https://developer.deel.com/api/reference/endpoints/intents/open-child-account-onboarding-intent-v-2026-11-16

## 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

- `Idempotency-Key` (string, required) — A UUID that identifies this open. A repeat with the same key and body returns the first intent.
- `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` (IntentsChildAccountOnboardingsPostRequestBodyContentApplicationJsonSchemaData, required) — The intent to open.

## Response

### 201

The intent that was opened.

- `data` (IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaData, required) — The intent.

## Errors

### 400 Bad Request Error

The body or the Idempotency-Key header is not valid.

- `fix` (IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaFix, required) — How to fix the error.
- `code` (string, required) — Stable code of the error.
- `type` (string, required) — Class of the error.
- `message` (string, required) — What went wrong.

### 401 Unauthorized Error

Operation failed.

- `request` (ApiErrorRequest, optional)
- `errors` (list of ApiError, optional)

### 403 Forbidden Error

The organization is not a Child Account of the caller. A caller without child\_organizations.manage gets 403 with the permission framework body \{code: backend.permission\_runtime.PERMISSION\_DENIED}.

- `fix` (IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaFix, required) — How to fix the error.
- `code` (string, required) — Stable code of the error.
- `type` (string, required) — Class of the error.
- `message` (string, required) — What went wrong.

### 404 Not Found Error

The feature is not open to your organization.

- `fix` (IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaFix, required) — How to fix the error.
- `code` (string, required) — Stable code of the error.
- `type` (string, required) — Class of the error.
- `message` (string, required) — What went wrong.

### 409 Conflict Error

The key was used with another body, or the Child Account has an open intent.

- `fix` (IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaFix, required) — How to fix the error.
- `code` (string, required) — Stable code of the error.
- `type` (string, required) — Class of the error.
- `message` (string, required) — What went wrong.

### 500 Internal Server Error

Operation failed.

- `errors` (list of IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaErrorsItems, optional)

## Types

### IntentsChildAccountOnboardingsPostRequestBodyContentApplicationJsonSchemaData

The intent to open.

- `signer` (IntentsChildAccountOnboardingsPostRequestBodyContentApplicationJsonSchemaDataSigner, required) — The person who signs for the Child Account.
- `payment_method` (IntentsChildAccountOnboardingsPostRequestBodyContentApplicationJsonSchemaDataPaymentMethod, required) — The payment method to set up.
- `organization_id` (string, required) — Id of the Child Account to onboard, as returned by POST /rest/organizations/children.

### IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaData

The intent.

- `id` (string, required) — Id of the intent.
- `type` (string, required) — Type of the intent.
- `wait` (map from string to any, required, nullable) — What the intent waits for, or null.
- `object` (string, required) — Always `intent`.
- `result` (map from string to any, required, nullable) — The result of a finished intent, or null.
- `status` (enum, required) — Status of the intent.
  - Allowed values: `CANCELED`, `REQUIRES_ACTION`, `SUCCEEDED`
- `details` (IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaDataDetails, required) — What the intent sets up.
- `subject` (IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaDataSubject, required) — The Child Account and its signer.
- `summary` (string, required) — One sentence on where the intent stands.
- `created_at` (string, required) — When the intent was opened.
- `expires_at` (string, required, nullable) — When the intent expires, or null for no expiry.
- `last_error` (map from string to any, required, nullable) — The last error of the intent, or null.
- `updated_at` (string, required) — When the intent last changed.
- `cancellation` (IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaDataCancellation, required, nullable) — The cancellation of a canceled intent, or null.
- `next_actions` (list of IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaDataNextActionsItems, required) — The actions for the steps that are due, in step order.
- `requirements` (IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaDataRequirements, required) — The steps by status.
- `type_version` (string, required) — Version of the type the intent was opened with, as a date.
- `steps` (list of IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaDataStepsItems, optional) — Every step of the intent in definition order. Only with `include=steps`.

### IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaFix

How to fix the error.

- `hint` (string, required) — What to change.
- `action` (string, optional) — Key of the step to do next.
- `conflicting_intent` (string, optional) — Id of the open intent that blocks the call. Only on CONFLICTING_INTENT.

### 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

### IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaErrorsItems

- `code` (string, optional) — Machine-readable error code
- `message` (string, optional) — Human-readable explanation of the error

### IntentsChildAccountOnboardingsPostRequestBodyContentApplicationJsonSchemaDataSigner

The person who signs for the Child Account.

- `name` (string, required) — Full name of the person who signs for the Child Account.
- `email` (string, required) — Email of the signer.

### IntentsChildAccountOnboardingsPostRequestBodyContentApplicationJsonSchemaDataPaymentMethod

The payment method to set up.

- `rail` (enum, required) — Payment rail.
  - Allowed values: `US_ACH`

### IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaDataDetails

What the intent sets up.

- `payment_method` (IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaDataDetailsPaymentMethod, required) — The payment method the intent sets up.
- `micro_deposits_sent_at` (string, required, nullable) — When Deel sent the two micro-deposits (ISO 8601). They usually arrive 1–2 business days later. Null until the signer adds the bank account, and again when the account must be added again.

### IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaDataSubject

The Child Account and its signer.

- `signer_user_id` (string, required) — Id of the signer user.
- `organization_id` (string, required) — Id of the Child Account.

### IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaDataCancellation

The cancellation of a canceled intent, or null.

- `code` (enum, required) — Why the intent was canceled.
  - Allowed values: `REQUESTED`
- `reason` (string, required, nullable) — The free text the partner sent when canceling, or null.
- `canceled_at` (string, required) — When the intent was canceled (ISO 8601).

### IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaDataNextActionsItems

- `key` (string, required) — Key of the step the action does.
- `why` (string, required) — Why the action is needed.
- `call` (IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaDataNextActionsItemsCall, required) — The call that does the action.
- `type` (enum, required) — How the action is done.
  - Allowed values: `CALL`, `REDIRECT`
- `actor` (enum, required) — Who does the action.
  - Allowed values: `CLIENT`
- `title` (string, required) — Short name of the action for a person.
- `confirm` (enum, required, nullable) — Who must confirm the action. `HUMAN` means a person must do it. Null means no confirmation.
  - Allowed values: `HUMAN`
- `redirect` (IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaDataNextActionsItemsRedirect, optional) — Only on a `REDIRECT` action: who the returned link is for, and what the call returns.

### IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaDataRequirements

The steps by status.

- `errors` (list of IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaDataRequirementsErrorsItems, required) — Errors of the steps.
- `currently_due` (list of string, required) — Keys of the steps that are due now.
- `eventually_due` (list of string, required) — Keys of the steps that wait for another step.
- `current_deadline` (string, required, nullable) — When the due steps must be done, or null for no deadline.
- `pending_verification` (list of string, required) — Keys of the steps under review.

### IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaDataStepsItems

- `key` (string, required) — Key of the step.
- `actor` (enum, required) — Who does the step.
  - Allowed values: `CLIENT`
- `group` (string, required) — Group of steps that share one mechanism.
- `title` (string, required) — Short name of the step for a person.
- `status` (enum, required) — Status of the step.
  - Allowed values: `DONE`, `DUE`, `IN_REVIEW`, `REJECTED`, `SKIPPED`, `UPCOMING`
- `completed_at` (string, required, nullable) — When the step was done, or null.

### IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaDataDetailsPaymentMethod

The payment method the intent sets up.

- `rail` (enum, required) — Payment rail.
  - Allowed values: `US_ACH`

### IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaDataNextActionsItemsCall

The call that does the action.

- `auth` (string, required) — Token kind that makes the call.
- `path` (string, required) — Path of the call.
- `method` (enum, required) — HTTP method.
  - Allowed values: `POST`
- `body_schema` (map from string to any, required) — JSON Schema (draft 2020-12) of the request body of the call.

### IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaDataNextActionsItemsRedirect

Only on a `REDIRECT` action: who the returned link is for, and what the call returns.

- `note` (string, required) — What the call returns.
- `opens_for` (enum, required) — Who the link the call returns is for.
  - Allowed values: `CLIENT`

### IntentsChildAccountOnboardingsPostResponsesContentApplicationJsonSchemaDataRequirementsErrorsItems

- `code` (string, required) — Stable code of the error.
- `reason` (string, required) — What went wrong.
- `requirement` (string, required) — Key of the step the error applies to.

## Examples

**Request**

```json
{
  "data": {
    "signer": {
      "name": "Ada Lovelace",
      "email": "ada@example.com"
    },
    "payment_method": {
      "rail": "US_ACH"
    },
    "organization_id": "12345"
  }
}
```

**Response**

```json
{
  "data": {
    "id": "int_5b1f0f3e-0000-4000-8000-000000000000",
    "type": "CHILD_ACCOUNT_ONBOARDING",
    "wait": {},
    "object": "intent",
    "result": {},
    "status": "REQUIRES_ACTION",
    "details": {
      "payment_method": {
        "rail": "US_ACH"
      },
      "micro_deposits_sent_at": "2024-01-15T09:30:00Z"
    },
    "subject": {
      "signer_user_id": "67890",
      "organization_id": "12345"
    },
    "summary": "The customer has steps to finish.",
    "created_at": "2026-11-18T10:00:00Z",
    "expires_at": "string",
    "last_error": {},
    "updated_at": "2026-11-18T10:00:00Z",
    "cancellation": {
      "code": "REQUESTED",
      "reason": "The customer opened the onboarding by mistake.",
      "canceled_at": "2026-11-18T10:05:00.000Z"
    },
    "next_actions": [
      {
        "key": "accept_terms",
        "why": "The customer must do this before Deel can bill the Child Account.",
        "call": {
          "auth": "ORGANIZATION",
          "path": "/rest/intents/child-account-onboardings/int_example/actions/example_step",
          "method": "POST",
          "body_schema": {
            "type": "object"
          }
        },
        "type": "REDIRECT",
        "actor": "CLIENT",
        "title": "Accept Deel's terms",
        "confirm": "HUMAN",
        "redirect": {
          "note": "Returns a one-time link for the signer covering every signer step still due.",
          "opens_for": "CLIENT"
        }
      }
    ],
    "requirements": {
      "errors": [
        {
          "code": "EXAMPLE_CODE",
          "reason": "The step failed.",
          "requirement": "accept_terms"
        }
      ],
      "currently_due": [
        "accept_terms"
      ],
      "eventually_due": [
        "verify_bank_account"
      ],
      "current_deadline": "string",
      "pending_verification": []
    },
    "type_version": "2026-11-18",
    "steps": [
      {
        "key": "accept_terms",
        "actor": "CLIENT",
        "group": "signer_session",
        "title": "Accept Deel's terms",
        "status": "DUE",
        "completed_at": "2026-11-12T10:15:00.000Z"
      }
    ]
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.letsdeel.com/rest/intents/child-account-onboardings"

payload = { "data": {
        "signer": {
            "name": "Ada Lovelace",
            "email": "ada@example.com"
        },
        "payment_method": { "rail": "US_ACH" },
        "organization_id": "12345"
    } }
headers = {
    "Idempotency-Key": "3f2b8c1e-6d4a-4e9b-9a1f-2c7d5e8b0a41",
    "X-Beta": "true",
    "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/intents/child-account-onboardings';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '3f2b8c1e-6d4a-4e9b-9a1f-2c7d5e8b0a41',
    'X-Beta': 'true',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"data":{"signer":{"name":"Ada Lovelace","email":"ada@example.com"},"payment_method":{"rail":"US_ACH"},"organization_id":"12345"}}'
};

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/intents/child-account-onboardings"

	payload := strings.NewReader("{\n  \"data\": {\n    \"signer\": {\n      \"name\": \"Ada Lovelace\",\n      \"email\": \"ada@example.com\"\n    },\n    \"payment_method\": {\n      \"rail\": \"US_ACH\"\n    },\n    \"organization_id\": \"12345\"\n  }\n}")

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

	req.Header.Add("Idempotency-Key", "3f2b8c1e-6d4a-4e9b-9a1f-2c7d5e8b0a41")
	req.Header.Add("X-Beta", "true")
	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/intents/child-account-onboardings")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '3f2b8c1e-6d4a-4e9b-9a1f-2c7d5e8b0a41'
request["X-Beta"] = 'true'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"data\": {\n    \"signer\": {\n      \"name\": \"Ada Lovelace\",\n      \"email\": \"ada@example.com\"\n    },\n    \"payment_method\": {\n      \"rail\": \"US_ACH\"\n    },\n    \"organization_id\": \"12345\"\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/intents/child-account-onboardings")
  .header("Idempotency-Key", "3f2b8c1e-6d4a-4e9b-9a1f-2c7d5e8b0a41")
  .header("X-Beta", "true")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"data\": {\n    \"signer\": {\n      \"name\": \"Ada Lovelace\",\n      \"email\": \"ada@example.com\"\n    },\n    \"payment_method\": {\n      \"rail\": \"US_ACH\"\n    },\n    \"organization_id\": \"12345\"\n  }\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.letsdeel.com/rest/intents/child-account-onboardings', [
  'body' => '{
  "data": {
    "signer": {
      "name": "Ada Lovelace",
      "email": "ada@example.com"
    },
    "payment_method": {
      "rail": "US_ACH"
    },
    "organization_id": "12345"
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'Idempotency-Key' => '3f2b8c1e-6d4a-4e9b-9a1f-2c7d5e8b0a41',
    'X-Beta' => 'true',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://api.letsdeel.com/rest/intents/child-account-onboardings");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "3f2b8c1e-6d4a-4e9b-9a1f-2c7d5e8b0a41");
request.AddHeader("X-Beta", "true");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"data\": {\n    \"signer\": {\n      \"name\": \"Ada Lovelace\",\n      \"email\": \"ada@example.com\"\n    },\n    \"payment_method\": {\n      \"rail\": \"US_ACH\"\n    },\n    \"organization_id\": \"12345\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Idempotency-Key": "3f2b8c1e-6d4a-4e9b-9a1f-2c7d5e8b0a41",
  "X-Beta": "true",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["data": [
    "signer": [
      "name": "Ada Lovelace",
      "email": "ada@example.com"
    ],
    "payment_method": ["rail": "US_ACH"],
    "organization_id": "12345"
  ]] as [String : Any]

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

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