Regulated numbers

Some countries let a carrier hand out a phone number immediately. Others require the carrier to register an end user against the number first. Which one you are in decides what you have to supply and when the number is ordered, so read the requirement before you build a checkout around it.

Read the requirement first

GET /v1/numbers/requirements (numbers:read) resolves one country, number type and profile type:

curl -H "Authorization: Bearer $OPENPHONEX_API_KEY" \
  "$OPENPHONEX_API_URL/v1/numbers/requirements?country=EE&number_type=national&profile_type=business"

Two fields drive everything else:

carrier_proof_requirement reports the carrier's published list and nothing else. It is not a statement that anything has been approved, and it never reflects your own profile's status.

• none — the carrier publishes an explicit zero for every proof type and names no document template. There is nothing for you to upload.
• required — the carrier asks for at least one proof document or a template it wants signed. personal_identity_fields, business_identity_fields, address_fields and document_names on the same response say what to collect.
• unknown — the carrier published nothing for this market. Treat it exactly like required: OpenPhonex does, and the number waits.

Where a number request waits

A number request reports a status and a sentence describing what it is waiting for. Registration changes which waits apply:

How the carrier learns who the end user is

From your approved verification profile OpenPhonex creates two records at the carrier: an identity — the person or company — and an address, which belongs to that identity. Neither is bound to a phone number on its own.

When a registered market number is ready, OpenPhonex opens a single verification task naming that number and that address. The carrier establishes the number's end user by approving the task; there is no separate step that attaches an identity to a number, and no state in which a number is waiting for one.

That makes the task the only thing standing between an ordered number and an approved one, which is what GET /v1/numbers/{number_id}/activation reports: submit_address_verification while the task has still to be opened, and wait_for_carrier_approval once the carrier has it.

Markets with no documents are ordered first

Where carrier_proof_requirement is none, the request goes to fulfillment_queued as soon as your profile is approved and the first payment is funded — before the carrier has verified anything.

That is not a shortcut. In these markets the carrier only ever reviews a registration that names an already-ordered number, so there is no verdict to wait for beforehand, and nothing you could upload to speed it up. Ordering first is the only sequence that can complete. Estonian national numbers work this way.

Two consequences worth designing for:

• The number is paid for before the carrier reviews the registration. If the carrier later refuses it, you hold a number that cannot carry production traffic. GET /v1/numbers/{number_id}/activation reports that outcome.
• The status copy on these requests says the carrier lists no documents and that OpenPhonex approved your profile. It deliberately does not claim the carrier approved anything, because at that point the carrier has not looked.

Where carrier_proof_requirement is required or unknown, nothing changes: the request stays in carrier_verification until the documents are supplied and approved, and it is never ordered on the strength of an unread requirement.

The inbound rate the quote is based on

Before any money moves, a number request carries a quote covering setup, monthly rental, and the per-minute price of the calls the number will carry. Read it on the request in the workspace, or on GET /v1/number-requests/{request_id} under quote_summary.source_breakdown.traffic_rates: each covered category appears in matched_rate_groups with a customer_price — the amount in micro-USD, the same figure as a decimal string, the unit it is charged per, the billing increment, and a confidence saying how firm the figure is.

In most regulated markets the carrier does not price inbound minutes against the number itself. It prices them against a shared inbound-capacity plan the number is attached to — and before purchase there is no number yet, so nothing on the number says which plan that will be.

Every managed OpenPhonex number is provisioned onto one standard metered capacity plan, so the plan is known before the number is ordered. The quote prices the inbound leg from that plan, so matched_rate_groups names inbound voice with its customer_price instead of waiting for someone to supply a rate. A request in a metered market therefore reaches a final quote on the same path as any other market.

Two consequences worth designing for:

• A number provisioned onto that plan is billed from the same published rate the quote was based on. The quote and the charge read one plan, not two.
• A number that ends up outside it — one the carrier delivers with its own included or dedicated channels, for example — has no metered rate to apply. OpenPhonex refuses the inbound call rather than billing it at the assumed rate. GET /v1/numbers/{number_id}/activation reports that outcome.

Where a deployment has no standard capacity plan configured — a self-hosted install, for example — traffic_rates.status stays traffic_rates_pending_rate_card_or_invoice, inbound voice stays in missing_rate_groups, and no customer_price is returned for it. It never falls back to a default rate.

What OpenPhonex still checks

Ordering first removes the carrier's precondition, never OpenPhonex's. In every market, regardless of carrier_proof_requirement, a number request still waits for all of these:

• your verification profile approved by OpenPhonex (identity check for a personal profile, company review or identity check for a business one);
• every requirement item OpenPhonex tracks for the market satisfied and reviewed;
• the first payment funded.