compliance

Get what a registration needs

Changed on

Returns everything a country requires before a registration can be approved, in the order to present it, along with what you have already supplied and where each item stands.

Everything you need to answer an item comes back with it. That covers the accepted values where an item takes a fixed set, the constraints a value must satisfy, and guidance on what a good answer looks like. Items that take a document say so, and some offer a blank form to download and complete. An unsupported country returns 422 rather than an empty result.

This answers one country for one registration you already hold. Omit subject_id and it answers the form alone, unanswered: every requirement reads not_supplied, nothing is satisfied, and there is no submission behind it, which is the state a registration you have not started is in anyway. Reading it that way needs program, since the coordinate is otherwise resolved from the registration.

For a number you hold, pass its ID from GET /v1/numbers as subject_id. For an SMS sender, call GET /v1/sms/senders/{sender_id}/requirements and pass a row's registration_id as subject_id.

get/v1/compliance/requirements

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/compliance/requirements
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Query parameters

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.

What you are registering.

subject_idstring

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.

Example:scr_01krdgeqcxet5s7t44vh8rt9mg

The registration to answer for. Omit it to read the form on its own, before you hold anything to register: the requirements come back unanswered, which is what to do when you are deciding whether to take a number or a sender on in the first place. Omitting it makes program required, since the coordinate is otherwise resolved from the subject. When you do supply it, it is an scr_ id when subject_kind is sms_sender, an nda_ id when it is number, and a cid_ party id when it is identity.

country_codestring required

ISO 3166-1 alpha-2 country code.

Example:US

The destination country. For identity send ZZ, the international coordinate: your business registers once, not per country.

programstring

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.

The programme to read. Optional alongside subject_id, because a registration is under exactly one programme and that is the one used; supply it there only to confirm the programme you expect, since one that is not the registration's own returns a 422, as does supplying one at all for a country that runs no registration programme. Required when subject_id is omitted, because there is then no registration to resolve it from and a country can run more than one.

identity_idstring
Example:cid_01krdgeqcxet5s7t44vh8rt9mg

Prefill the business details from a party you have already described. Requirements that ask about the party come back carrying its answers, marked prefilled; requirements about this sender never prefill because you write the sender's intended use fresh each time. Anything you have already filed for this registration wins over the party's answer.

Headers

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.

Response

What this country requires, and where you stand with it.

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.

satisfiedboolean required

Whether this country's requirements are met. true when no requirements apply, or 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.

needs_inputboolean required

Whether anything is waiting on you. True when a required requirement has no answer, its answer was refused or has gone stale, or the registration needs correction as described by reason. False does not imply that review is pending: a closed verifier correction can leave the requirements unsatisfied with no editable answers. Read review_pending to determine whether an answer is awaiting review. Read this independently of satisfied, which reports whether your paperwork is accepted. An unresolved verifier correction also sets it while the matching grant is live and the correction deadline has not passed, until you supply updated details. At the deadline or after grant withdrawal, an unresolved rejection alone does not set it because accepted answers can no longer be replaced. A corrected optional answer that is rejected or expires still needs your input through ordinary resupply, including after that deadline.

review_pendingboolean required

Whether any submitted answer is awaiting or undergoing review. False after all answers have received verdicts. A closed verifier correction can remain unsatisfied with no review pending and no editable answers.

reasonstring nullable required

What to correct about the registration as a whole, or null when no registration-wide correction is requested. Reasons about individual answers are on the entries in fields.

guidancestring nullable required

What this country expects of you before and while you fill in the form, written by Bird's compliance team. It may point you to a registration you must complete elsewhere first. null when the form needs no introduction, or when no program applies.

submission_idstring required
general_reasonsstring[] required

Feedback about the submission as a whole from an external verifier. It can remain visible while corrections are under review. Empty when no unresolved verifier feedback applies. On requirements responses, read needs_input to determine whether action is needed and editable_for_verifier_repair on each field to determine whether an approved or not-applicable answer can be replaced.

closed_atstring date-time nullable

When the submission for these requirements was closed. Null while open or not yet submitted.

Example response

{
  "subject_id": "scr_01krdgeqcxet5s7t44vh8rt9mg",
  "country_code": "US",
  "submission_id": "csb_01krdgeqcxet5s7t44vh8rt9mg",
  "fields": [
    {
      "attachment_id": "tca_01krdgeqcxet5s7t44vh8rt9mg",
      "attachment_ids": [
        "tca_01krdgeqcxet5s7t44vh8rt9mg"
      ]
    }
  ]
}

Changes