> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Child Account

> Rename a child or backfill external IDs that were never set.

Updates a child's `name` and/or backfills `externalIds`. Requires a **parent** key with `accounts.write`.

<Note>
  External IDs are **immutable once set**. You can fill in a field that was never set, but changing or clearing an existing value returns `409 external_id_immutable`.
</Note>

## Path Parameters

<ParamField path="child_id" type="integer" required>
  The child account's `accountId`.
</ParamField>

## Body Parameters

Supply at least one of:

<ParamField body="name" type="string">
  New display name. Max 255 characters.
</ParamField>

<ParamField body="externalIds" type="object">
  External IDs to **backfill** — only keys currently unset may be provided. Keys: `partnerId`, `businessId`, `locationId` (see [Create Child](/api-reference/v2/accounts/create-child)).
</ParamField>

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -X PATCH https://api.tracklysms.com/api/v2/accounts/children/1042 \
    -H "X-Api-Key: trk_your_parent_key" \
    -H "Content-Type: application/json" \
    -d '{ "name": "Acme West (Downtown)", "externalIds": { "businessId": "b_9" } }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success (200) theme={null}
  {
    "child": {
      "accountId": 1042,
      "name": "Acme West (Downtown)",
      "status": "active",
      "plan": "paid",
      "externalIds": { "partnerId": "p_1", "businessId": "b_9", "locationId": "loc_west" },
      "billedByParent": true,
      "createdAt": "2026-07-26T14:03:11.123456"
    }
  }
  ```

  ```json Immutable external ID (409) theme={null}
  { "error": "This external ID is already set and cannot be changed", "code": "external_id_immutable" }
  ```
</ResponseExample>

## Error Codes

| HTTP Status | Error Code                                                          | Description                                                      |
| ----------- | ------------------------------------------------------------------- | ---------------------------------------------------------------- |
| 400         | `invalid_name`                                                      | `name` is malformed or too long.                                 |
| 400         | `invalid_external_ids`                                              | An external ID is malformed or an unknown key was supplied.      |
| 400         | `empty_update`                                                      | No updatable field was provided.                                 |
| 404         | `child_not_found`                                                   | No child with that ID under this parent.                         |
| 409         | `child_deleted`                                                     | The child has been deleted.                                      |
| 409         | `external_id_immutable`                                             | Attempted to change/clear an already-set external ID.            |
| 409         | `duplicate_location`                                                | The backfilled `locationId` is already in use.                   |
| 403         | `not_a_parent_account` / `insufficient_scope` / `sandbox_read_only` | See [Accounts & Hierarchy](/api-reference/v2/accounts/overview). |