Migrate from Vonage Number Insight to Bird

Identify whether your application uses Number Insight Basic, Standard or Advanced, then list the fields that influence its next action. Replace the result interpretation along with the HTTP call.

This guide covers Number Insight. Vonage also documents an Identity Insights transition; an integration already using that API has a different request and response contract. Check the actual endpoint before applying a mapping.

Map the integration

Existing integration	Bird migration action
Number and country input	Resolve the customer's country context, then send an international phone_number.
Basic, Standard or Advanced selection	Choose a base lookup plus the optional properties needed by the application.
Current and original carrier	Read the separately identified current and original networks.
Porting, reachability and roaming	Preserve each property's status before interpreting its answer.
Asynchronous completion	Consume the Bird HTTP result in your application worker; retain your own task identity.
Caller-name data	Keep a separately verified source where the application depends on caller identity.

Use the Number Insight reference to inventory fields, then check Bird's phone-number reference:

Map the normalized international number to phone_number. Bird does not guess the country for a national-format number.
Map current_carrier and original_carrier to network_info and original_network_info. Read carrier names and MCC/MNC when present. Store network codes as strings so leading zeros survive; an absent network is not an empty carrier match.
Replace the old network-type enum checks with Bird's line_type vocabulary. A number's type or valid format alone does not prove present reachability or ownership.
Vonage ported includes assumed and unknown states. Request Bird porting for a conclusive ported value and any supplied history. Require status: ok; retain approximate dates as approximate.
Vonage reachable is a multi-state field. Bird presence separates status from the Boolean reachable. An unanswered property cannot be mapped to false.
Vonage roaming can be an object or an unknown result. Bird roaming has its own status and, when answered, is_roaming. Read visited-network codes only when supplied.

The CNAM guide describes caller-name fields. The Bird phone-number lookup operation has no CNAM request property. Keep a caller-name dependency separate from phone validation; do not fill it with a carrier name or infer identity from a reachability check.

Build and test the receiving path

Vonage's asynchronous example first acknowledges a request, then posts the lookup result to a callback. Bird returns the lookup result in the HTTP response. If your application already queues these tasks, let its worker call Bird, store the result and complete the original task. Do not wait for a Number Insight callback on the Bird path.

Create a key with the Lookup scope. Install messagebird-sdk, then set BIRD_API_KEY, BIRD_TEST_PHONE and LOOKUP_REQUEST_ID. The request ID is one UUID retained with this attempt's unchanged number and properties. The SDK selects the API region from the key. This example performs a billed lookup; review pricing and use a number you control.

Save as lookup.py:

Code example

import json
import os

from bird import Bird

with Bird(api_key=os.environ["BIRD_API_KEY"]) as client:
    result = client.lookup.phone_number(
        phone_number=os.environ["BIRD_TEST_PHONE"],
        type=["porting", "presence", "roaming"],
        options={"idempotency_key": os.environ["LOOKUP_REQUEST_ID"]},
    )

print(json.dumps({
    "line_type": result.line_type,
    "porting_status": result.porting.status if result.porting else "missing",
    "ported": result.porting.ported
    if result.porting and result.porting.status == "ok" else None,
    "presence_status": result.presence.status if result.presence else "missing",
    "reachable": result.presence.reachable
    if result.presence and result.presence.status == "ok" else None,
    "roaming_status": result.roaming.status if result.roaming else "missing",
    "is_roaming": result.roaming.is_roaming
    if result.roaming and result.roaming.status == "ok" else None,
}, indent=2))

Run python lookup.py. A conclusive false remains false; an unanswered result prints null with its status. This script reads the observations and does not send a message or verification challenge. Build the customer-facing path with the FastAPI form or Next.js form.

Test the application with these cases before changing traffic:

A national-format input requires correction or explicit country normalization before the billed request.
A ported number preserves the distinction between its current and original network.
Conclusive false, unavailable, inconclusive and unfamiliar statuses remain different outcomes.
An absent carrier, missing roaming network or approximate porting date does not become invented detail.
An operational error remains a failed lookup task, not a rejected customer or an unreachable number.
A lost response retries with the same body and key under the idempotency rules.
A late callback from an older Vonage task cannot overwrite the newer task's result or trigger a second customer action.

Switch traffic and reconcile

Keep existing callbacks available for Number Insight requests already in flight. Store the provider and provider request ID beside your own application task ID so the two integrations cannot finish each other's work. A provider request ID is a correlation value; it does not replace a Bird idempotency key.

Route a controlled cohort to the Bird worker. Compare the application decision, response time, unanswered properties and billed property selection for the destinations you actually serve. Treat live observations as time-specific, so different query times can yield different answers.

Move new tasks only after the fallback behavior is acceptable. If you roll back, change routing for new work and reconcile existing attempts before repeating them. Keep one owner for the resulting verification or customer action. A successful lookup does not demonstrate possession; use Verify when that is required.

References and next steps

Related resources

Continue with the documentation, guides and examples for this topic. Resources are in English.

Watch the guidePhone number lookup: check a number before you send Explore the capabilityLookup Implementation guideLookup overview

Get an implementation brief