Country Routing for OTP — Choosing Routes, Prices and Fallbacks

Country routing for OTP is the practice of deciding, per service, which country's numbers to request first and what to do when that choice is unavailable or underperforms. A sound strategy keeps an ordered preference list per service, filters it by live availability and a price ceiling from the catalog, falls back to the next country on HTTP 409 or an expired activation, and reorders routes over time based on your own receive rates. It also respects the regulatory and platform rules that apply to each country.

This guide covers the inputs to a routing decision, the trade-off between availability and price, a working fallback implementation, and the compliance questions to settle before you go live.

What a route is

In OTP Route, a route is effectively a pair of a service and a country. For each pair the catalog tells you whether it is supported and what it costs:

• GET /v1/services lists supported services.
• GET /v1/countries lists supported countries. The countries page shows the same coverage for humans.
• GET /v1/prices?service=&country= returns the current price for a specific pair.

Creating an activation with POST /v1/activations {service, country} is the moment the route is used. If no numbers are available for that pair at that moment, the API returns HTTP 409, and that response is the most important signal in any routing system.

Inputs to a routing decision

The first three come from the API. The next two come from your own data and are the inputs most teams neglect. The last two are constraints rather than preferences, so they decide which countries are eligible at all.

Availability versus price

Every routing strategy trades availability against cost. The right balance depends on what a failure costs you. A failed activation is refunded, so the money is recovered, but time is not. In a blocking CI run, a delayed verification holds up a pipeline. In an overnight provisioning batch, it may not matter.

A practical starting point is preference with a ceiling. Pick a primary country that matches the market of the flow you are testing, add one or two fallbacks, set a maximum price per activation, and review the order monthly using your own metrics.

Building a route table from the catalog

Refresh a local route table on a schedule, for example hourly, rather than calling the catalog on every activation:

import os
import requests

API = "https://otproute.com/api/v1"
session = requests.Session()
session.headers.update({"Authorization": f"Bearer {os.environ['OTPROUTE_API_KEY']}"})

PREFERENCES = {
    # service identifier -> ordered country identifiers (placeholders; use catalog values)
    "example-service": ["us", "ca", "gb"],
}
PRICE_CEILING = {"example-service": 1.00}  # USD per activation, set by you


def build_route_table():
    table = {}
    for service, countries in PREFERENCES.items():
        routes = []
        for country in countries:
            r = session.get(f"{API}/prices",
                            params={"service": service, "country": country}, timeout=10)
            if r.status_code != 200:
                continue  # pair not supported or temporarily unavailable
            price = float(r.json()["price"])  # field name per the schema in /docs
            if price <= PRICE_CEILING[service]:
                routes.append({"country": country, "price": price})
        table[service] = routes  # preserves preference order
    return table

Fallback routing logic

The router walks the route table in order and decides at each step whether to stop, move on or wait. The rules map directly to API responses and activation outcomes:

• HTTP 409 means no numbers are available on this route right now. Move to the next country immediately.
• HTTP 402 means insufficient balance. Stop routing entirely, because no other country will succeed either.
• HTTP 429 means you are being rate limited. Back off and retry the same route. This is not a routing failure.
• Expired or soft-deadline timeout means the route did not deliver this time. Cancel the activation, which is refunded if no SMS arrived, and try the next country.

import random
import time


class StopRouting(Exception):
    pass


def create_activation(service, country, attempts=5):
    for attempt in range(attempts):
        r = session.post(f"{API}/activations",
                         json={"service": service, "country": country}, timeout=(5, 30))
        if r.status_code == 429:
            time.sleep(min(2 ** attempt, 30) + random.uniform(0, 0.5))
            continue
        if r.status_code == 402:
            raise StopRouting("insufficient balance")
        if r.status_code == 409:
            return None  # route unavailable now
        r.raise_for_status()
        return r.json()
    return None


def route_and_verify(service, route_table, submit_number, wait_for_code, soft_deadline_s):
    for route in route_table.get(service, []):
        activation = create_activation(service, route["country"])
        if activation is None:
            record_outcome(service, route["country"], "unavailable")
            continue

        submit_number(activation["number"])                 # illustrative field names
        code = wait_for_code(activation["id"], soft_deadline_s)
        if code:
            record_outcome(service, route["country"], "received")
            return code, route["country"]

        session.post(f"{API}/activations/{activation['id']}/cancel", timeout=10)
        record_outcome(service, route["country"], "no_sms")

    raise StopRouting(f"no route delivered a code for {service}")

wait_for_code should read from your webhook store, populated by verified activation.sms_received events, as described in webhook-based OTP capture. record_outcome feeds the metrics that keep your preference list honest.

Learning from outcomes

A static preference list decays. Use your recorded outcomes to adjust it:

Require a minimum sample size before reordering, so that a handful of unlucky attempts does not reshuffle the table. For high-volume workloads, the bulk verification guide shows how to collect these counters per service, country and API key.

Regulatory and platform considerations

Routing is not only an engineering decision. Before you add a country to a preference list, settle these questions with whoever owns compliance in your organization:

• Platform terms. Many services restrict how accounts may be created or verified, and some tie eligibility to the user's real location. Choose countries that are consistent with the terms of the platform and the purpose of the test.
• Telecom rules by country. Countries differ in how phone numbers may be assigned and used, and some require identity checks for certain number types. Rules change, so treat this as an ongoing review rather than a one-off.
• Messaging rules for dedicated lines. If you use dedicated virtual numbers in the United States or Canada for outbound SMS, follow the applicable carrier and consent requirements for the messages you send.
• Data protection. Verification messages can contain personal data. Define how long you retain codes and message bodies, restrict who can see them, and include webhook payloads in your data inventory.
• Auditability. Separate API keys per workload, with usage logs per key, make it possible to show which team used which routes and why.

None of this is legal advice. It is a checklist to make sure routing choices are reviewed by the right people.

Temporary routes versus dedicated lines

Country routing applies to temporary activations, where each verification can take a different path. When a workflow needs the same number over time, such as a long-lived test account or an operational inbox, routing gives way to a fixed choice. Rent a dedicated US or Canada line, receive number.sms_received events by webhook, and release it when the need ends. Compare options on the pricing page and in the OTP gateway overview.

Responsible use

Choose routes to make legitimate verification reliable, for QA and testing, privacy-preserving sign-ups, app verification flows and operational lines. Do not use country selection to misrepresent location in breach of platform rules, and never use OTP Route for fraud, spam or abuse.

Frequently asked questions

Topics: otp country routing · otp routing strategy · otp fallback routing · sms verification country · otp price by country · otp availability · virtual number country