Create Child Account

curl -X POST https://api.tracklysms.com/api/v2/accounts/children \
  -H "X-Api-Key: trk_your_parent_key" \
  -H "Idempotency-Key: create-child-loc-west-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme West",
    "externalIds": { "partnerId": "p_1", "businessId": "b_9", "locationId": "loc_west" },
    "paidIntent": true,
    "billedByParent": true
  }'

import requests

resp = requests.post(
    "https://api.tracklysms.com/api/v2/accounts/children",
    headers={
        "X-Api-Key": "trk_your_parent_key",
        "Idempotency-Key": "create-child-loc-west-0001",
    },
    json={
        "name": "Acme West",
        "externalIds": {"partnerId": "p_1", "businessId": "b_9", "locationId": "loc_west"},
        "paidIntent": True,
        "billedByParent": True,
    },
)
child = resp.json()["child"]
print(child["accountId"])

{
  "child": {
    "accountId": 1042,
    "name": "Acme West",
    "status": "active",
    "plan": "paid",
    "externalIds": { "partnerId": "p_1", "businessId": "b_9", "locationId": "loc_west" },
    "billedByParent": true,
    "createdAt": "2026-07-26T14:03:11.123456"
  }
}

{
  "error": "A child with this locationId already exists",
  "code": "duplicate_location",
  "existingAccountId": 1042
}

POST

accounts

children

curl -X POST https://api.tracklysms.com/api/v2/accounts/children \
  -H "X-Api-Key: trk_your_parent_key" \
  -H "Idempotency-Key: create-child-loc-west-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme West",
    "externalIds": { "partnerId": "p_1", "businessId": "b_9", "locationId": "loc_west" },
    "paidIntent": true,
    "billedByParent": true
  }'

import requests

resp = requests.post(
    "https://api.tracklysms.com/api/v2/accounts/children",
    headers={
        "X-Api-Key": "trk_your_parent_key",
        "Idempotency-Key": "create-child-loc-west-0001",
    },
    json={
        "name": "Acme West",
        "externalIds": {"partnerId": "p_1", "businessId": "b_9", "locationId": "loc_west"},
        "paidIntent": True,
        "billedByParent": True,
    },
)
child = resp.json()["child"]
print(child["accountId"])

{
  "child": {
    "accountId": 1042,
    "name": "Acme West",
    "status": "active",
    "plan": "paid",
    "externalIds": { "partnerId": "p_1", "businessId": "b_9", "locationId": "loc_west" },
    "billedByParent": true,
    "createdAt": "2026-07-26T14:03:11.123456"
  }
}

{
  "error": "A child with this locationId already exists",
  "code": "duplicate_location",
  "existingAccountId": 1042
}

Creates a child account under your parent. Use your parent key. Requires the accounts.write scope (or an unscoped grandfathered key). See Accounts & Hierarchy for the model.

This endpoint is idempotent: send an Idempotency-Key header to make retries safe. Duplicate businesses are separately prevented by externalIds.locationId uniqueness.

Body Parameters

string

required

Display name for the child account. Max 255 characters.

object

Your own identifiers for this account. Each value is a non-empty printable-ASCII string, max 128 characters, and immutable once set. Unknown keys are rejected.

Show externalIds

string

Your partner/tenant identifier.

string

Your business identifier.

string

Your location identifier. Globally unique within a parent — a duplicate returns 409 duplicate_location.

boolean

default:"false"

Whether this child should be a paid account. When false, the child is created on the free plan and self-pays, and billedByParent is ignored.

boolean

default:"true"

Whether the parent pools this child’s billing. Only honored when paidIntent is true. When honored, the child is created on the paid plan and the parent must have a payment method on file.

Response Fields

object

The created child.

Show child

integer

The new account’s ID — use it in the child-scoped account endpoints.

string

Display name.

string

active.

string

paid or free, per the billing fields above.

object

The external IDs you supplied.

boolean

Whether billing pools to the parent.

string

ISO-8601 creation time.

boolean

Present only if the requested paid/pooled state was downgraded (e.g. parent had no payment method path); indicates the child was created self-paying instead.

Examples

curl -X POST https://api.tracklysms.com/api/v2/accounts/children \
  -H "X-Api-Key: trk_your_parent_key" \
  -H "Idempotency-Key: create-child-loc-west-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme West",
    "externalIds": { "partnerId": "p_1", "businessId": "b_9", "locationId": "loc_west" },
    "paidIntent": true,
    "billedByParent": true
  }'

import requests

resp = requests.post(
    "https://api.tracklysms.com/api/v2/accounts/children",
    headers={
        "X-Api-Key": "trk_your_parent_key",
        "Idempotency-Key": "create-child-loc-west-0001",
    },
    json={
        "name": "Acme West",
        "externalIds": {"partnerId": "p_1", "businessId": "b_9", "locationId": "loc_west"},
        "paidIntent": True,
        "billedByParent": True,
    },
)
child = resp.json()["child"]
print(child["accountId"])

{
  "child": {
    "accountId": 1042,
    "name": "Acme West",
    "status": "active",
    "plan": "paid",
    "externalIds": { "partnerId": "p_1", "businessId": "b_9", "locationId": "loc_west" },
    "billedByParent": true,
    "createdAt": "2026-07-26T14:03:11.123456"
  }
}

{
  "error": "A child with this locationId already exists",
  "code": "duplicate_location",
  "existingAccountId": 1042
}

Error Codes

HTTP Status	Error Code	Description
400	`missing_name`	`name` is required.
400	`name_too_long`	`name` exceeds 255 characters.
400	`invalid_external_ids`	An external ID is malformed, too long, empty, or an unknown key was supplied.
400	`invalid_paid_intent`	`paidIntent` is not a boolean.
400	`invalid_billed_by_parent`	`billedByParent` is not a boolean.
400	`children_cap_exceeded`	The parent has reached its 100-children limit.
400	`invalid_body`	The request body is not a JSON object.
403	`not_a_parent_account`	The calling key belongs to a child account.
403	`sandbox_read_only`	Sandbox keys cannot create children.
403	`insufficient_scope`	The key lacks the `accounts.write` scope.
409	`duplicate_location`	`externalIds.locationId` is already in use (see `existingAccountId`).
409	`parent_payment_method_required`	A pooled paid child needs a parent payment method on file.
429	`rate_limited`	Child-creation rate limit (100/hour) hit; see the `Retry-After` header.

Authenticated requests can also fail with 401 invalid_credentials, 403 account_suspended, and rare 502 link_failed / 503 rate_limiter_unavailable transients.

API Reference

V2 API Reference

Partner Accounts (v2)

Messages (v2)

Contacts (v2)

Lists (v2)

Number Requests (v2)

Business Profiles (v2)

Creatives (v2)

Audiences (v2)

Offers (v2)

Schedules (v2)

Revenue (v2)

Usage & Billing (v2)

Data Import (v2)

Links (v2)

Clicks (v2)

Webhooks (v2)

Phone Validation (v1)

API Reference (v1 - Deprecated)

Body Parameters

Response Fields

Examples

Error Codes

Next Steps

Mint an API key

Register a webhook

​Body Parameters

​Response Fields

​Examples

​Error Codes

​Next Steps

Mint an API key

Register a webhook

Body Parameters

Response Fields

Examples

Error Codes

Next Steps