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.

Some markets cannot be ordered at all

Registration decides when a number is ordered. A separate field decides whether the market can be ordered, and it is worth reading before you show a country and number type as buyable.

The carrier sells every market under one or more products. Most are sold with no call channels bundled into the number, and OpenPhonex prices their inbound calls per minute. Some markets are sold only with call channels bundled in. OpenPhonex has no per-minute inbound rate for a bundled-channel number, so it does not sell one, and an order naming that product is refused before anything reaches the carrier.

GET /v1/numbers/requirements and GET /v1/number-catalog both answer this with the same pair of fields:

Three reasons exist. Two describe a market, and the third describes a single product within one:

• number_type_not_priced — OpenPhonex prices incoming calls per minute and has no per-minute rate for this number type at all. Toll-free and shared-cost markets are in this group. Nothing about the carrier's stock changes it.
• carrier_bundles_channels — every number product the carrier currently has available for this country and number type bundles call channels into the number. It describes available stock, not the carrier's whole price list: a zero-channel product the carrier lists but has none of reads the same way.
• sku_bundles_channels — the same fact about ONE product rather than the market. It appears only on catalogue rows, where another product in the same country and number type may still be orderable. A market summary never carries it.

Where both apply, number_type_not_priced is reported, because it is the one that stays true regardless of how bundled-channel numbers come to be priced.

On GET /v1/number-catalog the pair appears on each catalogue row, describing that one product, and on each market summary, describing the country and number type as a whole. A market is orderable when at least one available row is the zero-channel product.

Treat null as "not answered", never as a refusal. It means the catalogue held no rows for that market, or held rows that recorded no channel count, so nothing was established either way. A client should leave such a market exactly as it would have before these fields existed. An unknown refusal reason still blocks ordering, but should use neutral copy such as "Cannot order now" rather than asserting the market is permanently unavailable.

Every affected national and local market also has exact_number_browsing_enabled false, so exact-number selection never reached them; only a category order did.

If a request somehow reaches ordering, it stops before anything is sent to the carrier and says that OpenPhonex could not confirm the number is on a product it can price. That refusal is about the selected product, not the market: it also fires when the product's channel count was never recorded, so it does not tell you to abandon the country.

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:

Inbound activation and outbound calling are separate

A managed number becomes active for inbound routing once the carrier confirms its registration, routing and inbound capacity. Outbound caller-ID setup does not keep a carrier-ready number in provisioning. Routing, an AI agent and call-time funding still need to be ready before an inbound call can connect.

The selected number panel shows Outbound calling is being set up while OpenPhonex registers its caller ID. Inbound calls can continue; outbound attempts from that number are refused until registration succeeds. OpenPhonex retries setup every five minutes for up to seven days, without ordering the number again. If setup still fails, the panel says Outbound calling needs support.

The Numbers aggregate exposes this distinction in calling_readiness.outbound.registration_status: pending, failed, registered, not_required, or legacy for numbers activated under the earlier combined readiness contract. An outbound destination and the usual admission checks are still required after caller-ID registration succeeds.

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.

Capacity pricing for an owned number

For managed DIDWW numbers, inbound pricing uses the number's verified capacity plan. The Numbers page explains why an individual number cannot be priced:

• capacity_hybrid_unsupported: the number includes fixed-price channels, so a per-minute capacity rate does not apply.
• capacity_separate_metering_unsupported: the carrier uses separate metering for this number group, outside the supported capacity-plan contract.
• capacity_plan_unavailable: the capacity facts or supported plan are missing.

Contact support for any of these reasons. A blocked number does not disable pricing for other numbers. Capacity facts are refreshed by provisioning or an explicit operator action; opening the Numbers page does not contact the carrier. A price change applies to new call reservations. A call already reserved keeps its original price through settlement.