Why was my toll-free SMS verification rejected?

After a carrier rejects a dossier, the verification exposes its reason separately from the item statuses. denial_reasons carries the carrier's explanation. The requirements list records what you supplied, not which answer caused the rejection.

The place people look first is the requirements list, and it cannot answer this. Understanding why saves a lot of time.

Where is the reason for the rejection?

Use bird sms tfn verifications get to read the verification. It returns the state, the sender it licenses and the carrier's response. denial_reasons carries that response as text.

One detail to plan for: reasons come with a rejection. When a carrier asks for changes instead of declining outright, the verification moves to info_requested and records the new status without reasons attached. So a verification asking you for more information will not tell you what, and the requirements list is where you look then, to see which items it is still missing.

Why can't the requirements list say which answer was wrong?

Because the carrier does not decide answer by answer. It decides the dossier as a whole, and Bird projects that single verdict onto every item you supplied.

On a rejected verification, every supplied item reads rejected, whether or not it caused the problem. Every blank item reads not_supplied. Nothing in the list is more rejected than another item. The list gives you no culprit, so use denial_reasons.

What the requirements list is genuinely for is the shape of the dossier: what is asked, what you have answered, and what is still missing.

What does the carrier actually ask for?

Ask for the requirements with no verification named and you get the blank form: every item the carriers ask for, in the order to present it. Name one with --verification-id and you get the same list carrying its own answers.

Each item comes with a key to submit it under, a label to put in front of whoever has to answer it, help_text describing what a good answer looks like, and whether an answer is required. Optional items are still reviewed when you supply them.

Two answers are closed sets worth knowing before you start:

• Legal structure, one of sole_proprietor, private_profit, public_profit, non_profit or government. These are spelled the same as 10DLC's five structures and are deliberately a separate list, because each authority decides for itself what it accepts.
• Monthly volume, as a band rather than a number: eleven of them, from up_to_10 through up_to_1m and up_to_5m, ending at above_5m.

Each item also reports a state, and a toll-free read emits five of them: not_supplied, supplied, in_review, approved and rejected. Treat the set as open, since review can gain stages.

How do I tell whether it is waiting on me or on the carrier?

Two booleans on the requirements read answer it, and only one of them is about you.

satisfied is true only once the verification is approved. A complete application can still await approval.

needs_input is true when the next move is yours. That covers four situations: a required item has no answer, the carrier has asked for changes, your draft is complete but nobody has submitted it, or a rejection is still inside its resubmission window.

Both false is the combination worth recognising, because it has two meanings. Either the carrier is holding the dossier and there is nothing to do but wait, or your verification was rejected and its resubmission window has already closed. resubmit_allowed is what separates those two, which is a good reason to read it whenever you read a rejection.

What do the six verification states mean?

Can I fix a rejected verification?

Sometimes, and one field answers it: a rejected verification can be corrected and resubmitted only while resubmit_allowed is true. Use the returned flag and review state before editing or resubmitting rather than calculating eligibility from a date alone.

A verification is editable while it is a draft, when the carrier has asked for more information, and while a rejection is still inside its resubmission window. Everything else is locked, which includes submitted and under_review as well as approved, so the two states you spend the most time waiting in are both states you cannot edit from. Trying anyway returns a conflict.

Correcting one answer does not mean re-entering the others. An update applies only the fields you send, so a single bad answer costs you that answer rather than the dossier.

Which commands do I use?

Six commands cover the lifecycle, and one step is missing from them on purpose.

bird sms tfn verifications requirements reads the item-by-item view, and get, create, update, list and cancel do what their names say. Submitting a verification for review is not among them: it happens in the dashboard.

One shortcut is worth knowing while you fill the form in. Passing --identity-id prefills the business and contact requirements from a party you have already described, and those come back marked as prefilled. The messaging and opt-in requirements never prefill, because you write those fresh for each verification, and anything you have already filed for this verification wins over the party's answer.

There is also no public webhook event for toll-free verification state, so a subscription cannot tell you when a decision lands. Polling the get command is the way to find out.