Carrier Lookup API Workflow for Automated Checks

Three things an endpoint alone will not give you

Building carrier lookup into your pipeline means more than hitting an endpoint. You need error handling that doesn’t duplicate work, retry logic that doesn’t retry bad inputs, and routing rules that turn API output into action.

Carrier Lookup on ZelNum supports API and CSV workflows. Here’s the pattern that works in production.

Integration shape

Treat the API workflow as a job, not a single call. Submit, store the task ID, poll or receive completion, then join results back to source.

Example request

{
  "job_type": "carrier_lookup_api_workflow",
  "source": "crm_export_2026_07",
  "input_column": "phone",
  "row_id_column": "record_id",
  "callback_url": "https://example.com/api/callbacks/model-checkZelNum/callback"
}

Response fields worth keeping

Reading the carrier field correctly

The carrier field is the one most teams route on, and the one most often misread. It reflects the number’s current network assignment, and that assignment changes whenever a customer ports to a new provider. A carrier value cached from last quarter can describe the network the number used to be on, not the one it uses today.

Two habits keep the problem small. Re-check numbers before a major send instead of trusting stored values, and treat network_name as detail rather than as the routing key. Some markets have brands that lease capacity across several networks, so the name on the bill and the network underneath don’t always match. When SMS routing is the goal, map lookup results to a route table and confirm the mapping still holds after every bulk refresh. For how those decisions attach to carrier data, see carrier lookup and SMS routing.

Teams also tend to assume one carrier per market. In practice most regions have a few national networks plus resellers, so segmenting on country_or_region together with carrier works better than carrier alone. Porting is the other blind spot: a number that moved networks keeps looking valid, which is why cached carrier data goes stale quietly.

Retry and cost rules

Don’t retry every failed row. Retry timeouts and temporary unknowns. Don’t retry rows that failed because the input was empty, badly formatted, or outside supported markets.

• Cap retries per record
• Store the first failure reason — don’t overwrite it
• Run a small batch after every parser or upload change
• Track cost per usable row, rather than total lookup cost

What failure looks like in practice

The failure mode we see most often isn’t a dramatic outage. It’s a quiet one: a CRM export arrives with a different column layout, the parser accepts it, the job runs to completion, and every row comes back repair because the phone column was empty. A small pilot batch after every upload change catches this in minutes instead of after a full-priced run.

Every one of these shows up in the export before it shows up in billing, which is why the routing rules and the cost-per-usable-row metric matter more than raw API logs. If you’re still designing the intake side, the pre-flight checks in bulk phone number validation catch most of these before a job is submitted.

Roll out safely

Start with CSV if the workflow is still being designed. Move to API only after result fields and routing rules are stable. That keeps developers from hard-coding decisions the operations team hasn’t agreed on yet.

Before-and-after rows

The fastest way to validate your pipeline: examine one row before and after the check. When the result can’t alter a downstream decision, a retry policy, or a cleanup task, running the check probably buys you nothing.

record_id,phone,source,segment
crm_40355,+61491570156,partner_upload,leads
crm_40127,+16465550283,optin_form,signups_q2
crm_40243,020 7946 2215,past_import,customer_base

Routing rules to set after the check

Write these down before the full run; otherwise the export sits in a folder.

When to sit out the lookup

Don’t fire a lookup just because the tool happens to be there.

FAQ

Is an API required for carrier lookup?

Use an API when the check is part of a product flow, scheduled job, or internal data pipeline. For one-time uploads, CSV is faster to start. Most teams begin with CSV and add API when volume demands it.

Which fields should I store?

Source row ID, original input, normalized value, status, reason code, and when the row was checked, plus the product-specific fields: carrier, country_or_region, network_name, line_type. These plus your internal identifiers are the minimum for a production pipeline.

How should I handle unknown results?

Keep unknowns out of the failed bucket. Retry once, then route valuable records to manual review or a slower fallback workflow. Unknown ≠ bad — deleting unknowns deletes records a retry would recover.

Related ZelNum pages

• ZelNum pricing
• Carrier Lookup
• ZelNum API
• ZelNum product directory

Try the Carrier Lookup →

Further reading

• the find-the-carrier explainer
• this landline/mobile detection guide