compliance

Create a registration submission

Changed on Oct 20, 2026

Submits every answer at once. Because submissions have no multi-call draft, send a complete set; anything missing or malformed comes back named field by field.

Each answer is then reviewed on its own. Submitting again for a registration that already has one returns a 409. Use POST /v1/compliance/submissions/{submission_id}/resupply to replace rejected, expired, or missing answers, and read the submission ID from the requirements for that registration. Accepted answers normally cannot be changed. During an open verifier correction and before its deadline, you can replace selected accepted answers. Unchanged entries are ignored; at least one answer must change. Other answers remain unchanged. A closed number or SMS sender submission must be reopened by Bird before you can submit an updated form.

An identity submission registers your business itself. Its subject is the party: send the cid_ id of a party your workspace holds as subject_id, with program business and country_code ZZ, the international coordinate: your business registers once, not per country. When subject_kind is identity, send neither identity_id nor identity, because the subject already names the party.

The answers are a legal representation under the name of the business they describe. Accepted dossiers can be registered with the carrier or regulator after compliance review. For SMS sender registrations with an unpaid setup fee, your wallet must cover setup and the first recurring charge. This submission charges the setup fee; insufficient funds return 402.

Idempotency-Keystring

Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay.

On a supported operation, if idempotency protection is unavailable before execution, the API returns 503 IdempotencyUnavailable (E01033) without executing this attempt. Retry with backoff using the same key and request. An operation that takes effect before its response is retained can still execute again on retry.

Two distinct 409 errors signal misuse:

request_in_progress (E01004): The same key is currently being processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
idempotency_key_reuse (E01005): The same key has already completed against a different request body or method. Generate a new key.

Recommended key format is <event-type>/<entity-id> (for example welcome-user/usr_abc123).

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Request body

subject_kind'sms_sender' | 'number' | 'identity' required

What is being registered.

sms_sender: a sender registered to send to one country.
number: a phone number you hold that needs ownership paperwork before it can carry traffic.
identity: a business you operate as, registered once and reused by later registrations that name it.

subject_idstring required

What is being registered. For sms_sender this is the scr_ id returned when you register a sender for a country. For number it is the nda_ id of a dedicated number you hold, as returned by GET /v1/numbers. A shared short code (nal_) is not accepted: it is shared, so its ownership paperwork is not yours to file. For identity it is the cid_ id of the party being registered, picked from the parties your workspace holds, as returned by GET /v1/compliance/identities.

programstring required

The registration program a country runs. Available programs depend on the registered resource. An SMS sender registers under an authority regime (alpha or numeric). A phone number proves ownership under its number type (mobile, local, national, short_code, short_code_fteu, or toll_free), matching the values of NumberType. An identity registers your business itself under business, internationally: its coordinate's country is always ZZ. A value is therefore only meaningful alongside the subject it describes. More are added as coverage grows, so treat this as an open set rather than a fixed list.

country_codestring required

ISO 3166-1 alpha-2 country code.

identity_idstring

Example request

{
  "subject_id": "scr_01krdgeqcxet5s7t44vh8rt9mg",
  "country_code": "US",
  "identity_id": "cid_01krdgeqcxet5s7t44vh8rt9mg",
  "identity": {
    "name": "Goldcrest Communications SAS"
  },
  "answers": [
    {
      "key": "business_registration_number",
      "value": "90012768",
      "attachment_id": "tca_01krdgeqcxet5s7t44vh8rt9mg",
      "attachment_ids": [
        "tca_01krdgeqcxet5s7t44vh8rt9mg"
      ]
    }
  ]
}

Response

The new submission, with every answer on it.

idstring required

subject_kind'sms_sender' | 'number' | 'identity' required

What is being registered.

sms_sender: a sender registered to send to one country.
number: a phone number you hold that needs ownership paperwork before it can carry traffic.
identity: a business you operate as, registered once and reused by later registrations that name it.

subject_idstring required

What is being registered. For sms_sender this is the scr_ id returned when you register a sender for a country. For number it is the nda_ id of a dedicated number you hold, as returned by GET /v1/numbers. A shared short code (nal_) is not accepted: it is shared, so its ownership paperwork is not yours to file. For identity it is the cid_ id of the party being registered, picked from the parties your workspace holds, as returned by GET /v1/compliance/identities.

programstring required

The registration program a country runs. Available programs depend on the registered resource. An SMS sender registers under an authority regime (alpha or numeric). A phone number proves ownership under its number type (mobile, local, national, short_code, short_code_fteu, or toll_free), matching the values of NumberType. An identity registers your business itself under business, internationally: its coordinate's country is always ZZ. A value is therefore only meaningful alongside the subject it describes. More are added as coverage grows, so treat this as an open set rather than a fixed list.

country_codestring required

ISO 3166-1 alpha-2 country code.

identity_idstring required

satisfiedboolean required

Whether this country's requirements are met. true once the submission is approved and every required requirement is approved or marked not applicable. This can remain true when an external verifier requests a correction. Once you submit that correction, it must pass review before this becomes true again, including any optional answers you change.

created_atstring date-time required

When this was submitted.

updated_atstring date-time required

When it last changed.

closed_atstring date-time nullable

When this submission was closed. Null while it remains open.

closure_reasonstring nullable

The decline reason for a closed submission, or null while open.

Example response

{
  "id": "csb_01krdgeqcxet5s7t44vh8rt9mg",
  "subject_id": "scr_01krdgeqcxet5s7t44vh8rt9mg",
  "country_code": "US",
  "identity_id": "cid_01krdgeqcxet5s7t44vh8rt9mg",
  "items": [
    {
      "id": "cit_01krdgeqcxet5s7t44vh8rt9mg",
      "attachment_id": "tca_01krdgeqcxet5s7t44vh8rt9mg",
      "attachment_ids": [
        "tca_01krdgeqcxet5s7t44vh8rt9mg"
      ]
    }
  ]
}

Create a registration submission

Request

Headers

Request body

Example request

Response

Example response

Changes