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

# Execute a Child Account onboarding intent action

POST https://api.letsdeel.com/rest/intents/child-account-onboardings/{intent_id}/actions/{action_key}
Content-Type: application/json

Does the action of a step that is due. A signer step answers a one-time link in action_result.url: send the signer there. The link runs every signer step that is due. A new call stops the previous link if the signer has not opened it yet. A repeat with the same Idempotency-Key and body returns the first answer with a new token for the same link, or 409 ACTION_RESULT_EXPIRED when that link no longer works. An action that is not due answers 409. Answers 404 while the feature is not open to you.

 **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/do-child-account-onboarding-intent-action-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

### Path parameters

- `intent_id` (string, required) — Id of the intent.
- `action_key` (string, required) — Key of the step to do, as in next_actions of the intent.

### Headers

- `Idempotency-Key` (string, required) — A UUID that identifies this call. A repeat with the same key and body returns the first answer.
- `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` (IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostRequestBodyContentApplicationJsonSchemaData, optional)

## Response

### 200

The intent and what to do next for the action.

- `data` (IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaData, required) — The intent after the action.
- `action_result` (IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaActionResult, required) — What the partner does next for the action.

## Errors

### 400 Bad Request Error

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

- `fix` (IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaFix, 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 of the intent 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` (IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaFix, 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 id is unknown or of another organization, the action is unknown, or the feature is not open to you.

- `fix` (IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaFix, 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 action is not due, another action is running, the key was used with another body, the link of an earlier call stopped working, or the bank account is not awaiting verification (NOT_PENDING).

- `fix` (IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaFix, 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.

### 422 Unprocessable Entity Error

The micro-deposit amounts do not match (INVALID_AMOUNTS, attempts_remaining says how many tries are left), or the verification was refused (BANK_ACCOUNT_VERIFICATION_REFUSED, refusal_code says why).

- `fix` (IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaFix, 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.
- `attempts_remaining` (integer, optional) — Micro-deposit attempts left. Only on INVALID_AMOUNTS.

### 429 Too Many Requests Error

Too many verification attempts in a short time. Try again later.

- `fix` (IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaFix, 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 IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaErrorsItems, optional)

### 503 Service Unavailable Error

The bank account cannot be verified right now. Nothing changed.

- `fix` (IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaFix, 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.
- `retry_after` (integer, optional) — Seconds to wait before a retry. Only on UPSTREAM_UNAVAILABLE.

## Types

### IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostRequestBodyContentApplicationJsonSchemaData

- `amounts` (list of double, optional) — verify_bank_account only, and required there: the two deposit amounts in US dollars, in any order.

### IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaData

The intent after the action.

- `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` (IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaDataDetails, required) — What the intent sets up.
- `subject` (IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaDataSubject, 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` (IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaDataCancellation, required, nullable) — The cancellation of a canceled intent, or null.
- `next_actions` (list of IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaDataNextActionsItems, required) — The actions for the steps that are due, in step order.
- `requirements` (IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaDataRequirements, required) — The steps by status.
- `type_version` (string, required) — Version of the type the intent was opened with, as a date.
- `steps` (list of IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaDataStepsItems, optional) — Every step of the intent in definition order. Only with `include=steps`.

### IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaActionResult

What the partner does next for the action.

- `url` (string, required, nullable) — One-time link to the signer session. It runs every signer step that is due. A new call stops the previous link if the signer has not opened it yet. Deel does not store it and never shows it again; a repeat with the same Idempotency-Key signs a new token for the same link. Null for a `CALL`.
- `type` (enum, required) — How the partner finishes the action. `REDIRECT`: send the signer to `url`. `CALL`: the call did the action; read the intent in `data`.
  - Allowed values: `REDIRECT`, `CALL`
- `expires_at` (string, required, nullable) — When the link stops working. Null for a `CALL`.

### IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaFix

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

### IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaErrorsItems

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

### IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaDataDetails

What the intent sets up.

- `payment_method` (IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaDataDetailsPaymentMethod, 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.

### IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaDataSubject

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.

### IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaDataCancellation

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).

### IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaDataNextActionsItems

- `key` (string, required) — Key of the step the action does.
- `why` (string, required) — Why the action is needed.
- `call` (IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaDataNextActionsItemsCall, 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` (IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaDataNextActionsItemsRedirect, optional) — Only on a `REDIRECT` action: who the returned link is for, and what the call returns.

### IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaDataRequirements

The steps by status.

- `errors` (list of IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaDataRequirementsErrorsItems, 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.

### IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaDataStepsItems

- `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.

### IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaDataDetailsPaymentMethod

The payment method the intent sets up.

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

### IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaDataNextActionsItemsCall

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.

### IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaDataNextActionsItemsRedirect

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`

### IntentsChildAccountOnboardingsIntentIdActionsActionKeyPostResponsesContentApplicationJsonSchemaDataRequirementsErrorsItems

- `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": {
    "amounts": [
      0.32,
      0.45
    ]
  }
}
```

**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"
      }
    ]
  },
  "action_result": {
    "url": "https://app.deel.com/embedded/signer-session#eyJhbGciOiJIUzI1NiJ9.example.signature",
    "type": "REDIRECT",
    "expires_at": "2026-11-25T10:00:00Z"
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.letsdeel.com/rest/intents/child-account-onboardings/int_5b1f0f3e-0000-4000-8000-000000000000/actions/accept_terms"

payload = { "data": { "amounts": [0.32, 0.45] } }
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/int_5b1f0f3e-0000-4000-8000-000000000000/actions/accept_terms';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '3f2b8c1e-6d4a-4e9b-9a1f-2c7d5e8b0a41',
    'X-Beta': 'true',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"data":{"amounts":[0.32,0.45]}}'
};

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/int_5b1f0f3e-0000-4000-8000-000000000000/actions/accept_terms"

	payload := strings.NewReader("{\n  \"data\": {\n    \"amounts\": [\n      0.32,\n      0.45\n    ]\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/int_5b1f0f3e-0000-4000-8000-000000000000/actions/accept_terms")

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    \"amounts\": [\n      0.32,\n      0.45\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<String> response = Unirest.post("https://api.letsdeel.com/rest/intents/child-account-onboardings/int_5b1f0f3e-0000-4000-8000-000000000000/actions/accept_terms")
  .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    \"amounts\": [\n      0.32,\n      0.45\n    ]\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/int_5b1f0f3e-0000-4000-8000-000000000000/actions/accept_terms', [
  'body' => '{
  "data": {
    "amounts": [
      0.32,
      0.45
    ]
  }
}',
  '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/int_5b1f0f3e-0000-4000-8000-000000000000/actions/accept_terms");
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    \"amounts\": [\n      0.32,\n      0.45\n    ]\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": ["amounts": [0.32, 0.45]]] 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/int_5b1f0f3e-0000-4000-8000-000000000000/actions/accept_terms")! 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()
```