---
title: "Create a sender registration"
method: POST
path: "/v2/senders/registrations"
tags: ["Senders"]
---

# Create a sender registration

`POST /v2/senders/registrations`

Creates a sender registration and sets `status` to `PENDING_APPROVAL`.

  - If the account does not use parent/child accounts, the API ignores `child_account_id` and registers the sender for the authenticated account.
  - If the account is a parent account and you omit `child_account_id`, the API registers the sender for the parent account.
  - If you provide `child_account_id`, the API registers the sender for that child account.
  - If a registration for the same sender was already created within the last 30 minutes (for the same account or child account), the API returns `429 Too Many Requests`. This prevents abuse of the verification retry limit.
  - Any existing `PENDING_APPROVAL` registration for the same sender (for the same account or child account) is automatically cancelled before the new one is created.

## Request body

- SenderRegistrationRequest — Request body for creating a sender registration.
  - `sender` string, required — The sender number to register, for example a phone number.
  - `country` string, required — ISO 3166-1 alpha-2 country code for the sender, for example AU.
  - `type` 'PERSONAL_MOBILE_NUMBER', required — Type of sender registration that can be created through the public API. Only `PERSONAL_MOBILE_NUMBER` is supported here; alpha (`ALPHANUMERIC`) registrations are created through the registration backoffice and are read-only on this API.
  - `child_account_id` string — Child account ID to register the sender for. Ignored for accounts without parent/child accounts. If omitted for a parent account, the API registers the sender for the parent account.

## Response `201`

Successful response containing the new sender registration details.

- object
  - `data` object, required — A sender registration record.
    - `registration_id` string, uuid, required — Unique identifier for the registration.
    - `sender` string, required — The registered sender number.
    - `country` string, required — ISO 3166-1 alpha-2 country code for the sender.
    - `type` 'PERSONAL_MOBILE_NUMBER' | 'ALPHANUMERIC', required — Type of a sender registration record (as returned by the API). - `PERSONAL_MOBILE_NUMBER` — a personal mobile number registered as a sender. - `ALPHANUMERIC` — an alphanumeric (alpha) sender ID. Type-specific fields are returned under `details.alphanumeric`. Alpha registrations are created through the registration backoffice, not this public API.
    - `status` 'PENDING_APPROVAL' | 'VERIFIED' | 'REJECTED' | 'CANCELLED', required — Status of a sender registration. The same coarse set of statuses applies to every registration `type`: - `PERSONAL_MOBILE_NUMBER` — `PENDING_APPROVAL`, `VERIFIED`, `REJECTED`, `CANCELLED`. - `ALPHANUMERIC` — `PENDING_APPROVAL`, `VERIFIED`, `REJECTED`. The finer alpha registry lifecycle is surfaced separately and is not part of this coarse enum.
    - `created_at` string, date-time, required — Timestamp in RFC3339 format (e.g., 2025-08-26T10:30:00Z) when the registration was created.
    - `child_account_id` string — Child account ID the sender is registered for. Only present for registrations created under a child account.
    - `updated_at` string, date-time, required — Timestamp in RFC3339 format (e.g., 2025-08-26T10:32:00Z) when the registration was last updated.
    - `details` SenderRegistrationDetails — Type-specific details for a sender registration. The populated sub-object matches the registration `type` — for an `ALPHANUMERIC` registration, `alphanumeric` is present.
      - `alphanumeric` AlphanumericDetails — Details specific to an alphanumeric (alpha) sender registration.
        - `registry` 'ACMA', required — The registry body an alphanumeric sender registration is submitted to. - `ACMA` — Australian Communications and Media Authority.
        - `status` 'NEW' | 'SUBMITTED_TO_REGISTRY' | 'PENDING_CUSTOMER' | 'PENDING_APPROVAL' | 'VERIFIED' | 'READY_TO_USE' | 'FAILED' | 'REVOKED' | 'CANCELLED' — Fine-grained registry lifecycle status for an alphanumeric registration — the state the customer sees on screen, distinct from the coarse root `status`. This enum is **expected to grow** as a registry (e.g. ACMA) introduces new states. The server only ever returns a value it has explicitly mapped, and new values are added here additively — so **clients must render a graceful fallback for any value they don't yet recognise** rather than treating the set as fixed. Value → display label: - `NEW` — Initial Review - `SUBMITTED_TO_REGISTRY` — Submitted - `PENDING_CUSTOMER` — Awaiting Confirmation - `PENDING_APPROVAL` — In ACMA Review - `VERIFIED` — Provisioning - `READY_TO_USE` — Ready to Use - `FAILED` — Failed - `REVOKED` — Revoked - `CANCELLED` — Cancelled
        - `status_reason` string — Optional human-readable reason for the current `status` (verbatim registry status description), suitable for tooltips. May be absent or blank.
  - `request` object — Optional metadata (e.g. requestId, traceId)
  - `meta` object — Optional pagination, feature flags, etc.

## Other responses

- `400` — Input Validation Error
- `401` — Unauthorized
- `409` — Conflict
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.net/kudosity/apis/transmit-sms-api.md) · [All operations](https://skmtc.net/kudosity/apis/transmit-sms-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kudosity/transmit-sms-api/versions/9f6c34b849af/schema)