Get what a registration needs

GET

/v1/compliance/requirements

const requirement = await bird.complianceRequirements.get({
  subject_kind: "number",
  subject_id: "nda_01krdgeqcxet5s7t44vh8rt9mg",
  country_code: "US",
});
for (const field of requirement.fields ?? []) {
  console.log(field.key, field.state);
}

requirement = client.compliance_requirements.get(
    subject_kind="number",
    subject_id="nda_01krdgeqcxet5s7t44vh8rt9mg",
    country_code="US",
)
for field in requirement.fields or []:
    print(field.key, field.state)

req, err := client.ComplianceRequirements.Get(context.Background(), bird.ComplianceRequirementsGetParams{
	SubjectKind: "number",
	SubjectID:   "nda_01krdgeqcxet5s7t44vh8rt9mg",
	CountryCode: "US",
})
if err != nil {
	log.Fatal(err)
}
for _, f := range *req.Fields {
	fmt.Println(*f.Key, *f.State)
}

$requirement = $bird->complianceRequirements->get([
    'subject_kind' => 'number',
    'subject_id' => 'nda_01krdgeqcxet5s7t44vh8rt9mg',
    'country_code' => 'US',
]);
foreach ($requirement->getFields() ?? [] as $field) {
    echo $field->getKey(), ' ', $field->getState(), "\n";
}

bird compliance requirements

curl -X GET "https://us1.platform.bird.com/v1/compliance/requirements" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "country_code=US"

Response200

{
  "next": [
    {
      "kind": "operation"
    }
  ],
  "subject_kind": "sms_sender",
  "subject_id": "scr_01krdgeqcxet5s7t44vh8rt9mg",
  "program": "alpha",
  "country_code": "US",
  "submission_id": "csb_01krdgeqcxet5s7t44vh8rt9mg",
  "obligation": {
    "reason": "policy_change",
    "state": "open"
  },
  "fields": [
    {
      "data_type": "string",
      "attachment_id": "tca_01krdgeqcxet5s7t44vh8rt9mg",
      "attachment_ids": [
        "tca_01krdgeqcxet5s7t44vh8rt9mg"
      ],
      "state": "not_supplied"
    }
  ]
}

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.

Query Parameters

subject_kindstring

What you are registering.

Possible values: sms_sender, number, identity

subject_idstring

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

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

programstring

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.

Possible values (may grow over time): alpha, numeric, mobile, local, national, short_code, short_code_fteu, toll_free, business

identity_idstring

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.

Response Payload

next

array of object

What to do next about this country's requirements, given the state it is in. Each entry names one action and says why it is worth taking, so you can act on this response without working out the order yourself. Present on reads that compute it: an empty list means there is nothing to do, and the field is absent entirely on responses that do not report next actions.

Whether anything is asked of you is needs_input, and this says what to do about it: send your answers where none have been filed, or replace the ones that were refused. Which items those are, and why each was refused, is on the item in fields. For feedback about the whole submission, read reason and general_reasons and update the details that need correction.

Show child attributes

subject_kind

string

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.

Possible values: sms_sender, number, identity

subject_id

nullable string

required

The registration these requirements are for, the same one you asked about. null when you asked without one, which is how a form read on its own says it is answering for nothing yet.

program

nullable string

required

The registration program these requirements belong to. null when the country runs no registration program at all, in which case nothing is required and the field list is empty.

country_code

string

required

ISO 3166-1 alpha-2 country code.

satisfied

boolean

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_input

boolean

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_pending

boolean

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.

reason

nullable string

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.

guidance

nullable string

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_id

nullable string

required

The submission carrying your answers, once you have made one. null before that.

obligation

nullable object

required

What this registration has to do to keep sending, and by when. Null when nothing is outstanding. An obligation does not stop you sending: the registration stays authorised until the date passes, and supplying what is asked for before then closes it with no interruption.

Show child attributes

general_reasons

array of string

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.

fields

array of object

required

Every requirement for this country, in the order to present them.

Show child attributes

fields.parent_key

string

Parent field grouping this named document. Absent for an ordinary field.

fields.document_key

string

Stable document key within the parent field. Absent for an ordinary field.

fields.parent_label

string

Display name of the parent field grouping this document. Absent for an ordinary field.

fields.parent_help_text

string

The parent field's own description, shared by every document in the group. Each document's help_text describes that document alone. Absent for an ordinary field and when the parent has no description.

fields.key

string

required

Identifies this requirement. Use it as the key when you submit a value.

fields.label

string

required

What to call this requirement when you ask someone for it.

fields.help_text

nullable string

required

Guidance on what a good answer looks like, including anything the destination country expects. null when the label speaks for itself.

fields.data_type

string

required

The kind of value a requirement takes. The string value is a single line, while text runs to several. The enum value accepts only the values listed with the requirement. The number, boolean, and date values take their corresponding data types. The url value takes a link. The country value takes an uppercase ISO 3166-1 alpha-2 code, such as NL. The document value means a file you upload first and then reference. All other values are supplied inline.

Possible values: string, text, enum, number, boolean, date, url, country, document

fields.required

boolean

required

Whether an answer is needed before the registration can be approved. Optional requirements are still reviewed when you supply them.

fields.section

string

required

A stable key grouping related requirements together. Use it to keep your own grouping consistent across requests; use section_label for what to show someone.

fields.section_label

string

required

What to call this requirement's group when you present it.

fields.options

array of object

required

The accepted values, already resolved, when the data type is enum. Empty for every other type.

Show child attributes

fields.options.value

string

required

What to send.

fields.options.label

string

required

What to show.

fields.validation

object

required

Constraints a value must satisfy, where the requirement sets any. Which of these apply follows from its data type: pattern, min_length and max_length constrain string and text values, minimum and maximum constrain number values, and everything else is null. Check these before submitting and you avoid a round trip.

Show child attributes

fields.template_url

nullable string

required

A blank form to download, complete and upload back, for requirements that need a signed document. null when the requirement has no form to download.

fields.max_items

nullable integer

required

How many answers this requirement takes, when it takes more than one. null for a requirement answered once, which is most of them. Where it is set, answer with values or attachment_ids and read your answer back from the same pair; value and attachment_id stay null. Order is kept as you send it, and it is part of the answer: a keyword list beginning with STOP is not the same declaration as one ending with it.

fields.value

nullable string

required

Your answer, for a requirement answered inline. Every answer travels as a string whatever its data type, so a number reads back as "1500" and a yes-or-no as "true". Use the data type to parse it. null for a requirement that takes a document, and before you have answered.

fields.prefilled

boolean

required

true when value comes from the party this registration is for. Accept it as it stands or replace it; either way it becomes your answer when you submit. Only a requirement that asks about the party is ever prefilled.

fields.attachment_id

nullable string

required

The document you supplied, for a requirement that takes one. null otherwise.

fields.values

nullable array

required

Your answers, for a requirement that takes several and is answered inline. Set only when max_items is, and null otherwise, including before you have answered. Each answer travels as a string whatever the data type, the same as value.

fields.attachment_ids

nullable array

required

The documents you supplied, for a requirement that takes several. Set only when max_items is and the requirement takes documents, and null otherwise.

fields.state

string

required

Where one requirement stands. The not_supplied state means nothing has been given for it yet. The supplied state means we have your answer and review has not started. The in_review state means someone is looking at it. The approved and rejected states are decisions. You can replace a rejected item without refiling the rest. The not_applicable state means this requirement does not apply to you. The expired state means the value was accepted but has since gone stale.

An item only ever reports its state. Treat this as an open set because review can gain stages. A value you do not recognise is a valid state that this server added.

Possible values (may grow over time): not_supplied, supplied, in_review, approved, rejected, not_applicable, expired

fields.decided_at

nullable string

required

When this was decided. null while no decision has been made.

fields.expires_at

nullable string

required

When this answer goes stale and must be supplied again. null when it does not expire.

fields.editable_for_verifier_repair

boolean

required

Whether you may replace this accepted answer to correct the submission after external verification. This permission does not change its state or reason. Submit only answers whose content or attachment identity you change.

fields.reason

nullable string

required

Why this requirement was rejected, when it was. null otherwise.

closed_at

nullable string

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

Continue with the documentation, guides and examples for this topic.

Get an implementation brief

const requirement = await bird.complianceRequirements.get({
  subject_kind: "number",
  subject_id: "nda_01krdgeqcxet5s7t44vh8rt9mg",
  country_code: "US",
});
for (const field of requirement.fields ?? []) {
  console.log(field.key, field.state);
}

requirement = client.compliance_requirements.get(
    subject_kind="number",
    subject_id="nda_01krdgeqcxet5s7t44vh8rt9mg",
    country_code="US",
)
for field in requirement.fields or []:
    print(field.key, field.state)

req, err := client.ComplianceRequirements.Get(context.Background(), bird.ComplianceRequirementsGetParams{
	SubjectKind: "number",
	SubjectID:   "nda_01krdgeqcxet5s7t44vh8rt9mg",
	CountryCode: "US",
})
if err != nil {
	log.Fatal(err)
}
for _, f := range *req.Fields {
	fmt.Println(*f.Key, *f.State)
}

$requirement = $bird->complianceRequirements->get([
    'subject_kind' => 'number',
    'subject_id' => 'nda_01krdgeqcxet5s7t44vh8rt9mg',
    'country_code' => 'US',
]);
foreach ($requirement->getFields() ?? [] as $field) {
    echo $field->getKey(), ' ', $field->getState(), "\n";
}

bird compliance requirements

curl -X GET "https://us1.platform.bird.com/v1/compliance/requirements" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "country_code=US"

Response200

{
  "next": [
    {
      "kind": "operation"
    }
  ],
  "subject_kind": "sms_sender",
  "subject_id": "scr_01krdgeqcxet5s7t44vh8rt9mg",
  "program": "alpha",
  "country_code": "US",
  "submission_id": "csb_01krdgeqcxet5s7t44vh8rt9mg",
  "obligation": {
    "reason": "policy_change",
    "state": "open"
  },
  "fields": [
    {
      "data_type": "string",
      "attachment_id": "tca_01krdgeqcxet5s7t44vh8rt9mg",
      "attachment_ids": [
        "tca_01krdgeqcxet5s7t44vh8rt9mg"
      ],
      "state": "not_supplied"
    }
  ]
}

Get what a registration needs

Query Parameters

Response Payload

Related resources