Zalo Number Checker API Workflow for Automated Checks
The API route for Zalo is not about convenience. It is about turning the on-Zalo rate into a live number you can watch. Where Zalo has reach is a Vietnam question, so the on-Zalo share per country works as the natural KPI: Vietnam’s number drives the campaign decision, the regional numbers serve as warnings. Zalo Number Checker is the ZelNum page built for this job: Zalo Number Checker.
Quick answer
send the list to the API, receive on-Zalo status and country per record, and store the result with a timestamp. Aggregate by country on every run and watch the Vietnam rate over time. The schedule is not an upgrade to the workflow. It is the workflow.
The market you are measuring
It helps to know what the number should look like when things are healthy. Zalo publishes near 80 million monthly users in Vietnam, more than two billion messages per day, and the top spot among messaging apps in the country. Against that baseline, a healthy Vietnamese contact file typically shows a high on-Zalo share, while files from neighboring markets show almost none of the same signal.
This is why a flat aggregate number is worse than useless in an automated pipeline. A dashboard that reads "62% on-Zalo" across a mixed file tells the on-call analyst nothing. The same pipeline reporting "81% Vietnam, 5% region" tells them the Vietnamese segment is routable today and the regional segment never was.
The API workflow
- Start the job. One request goes out per batch, carrying the record set and the country field for each row.
- Poll or receive callbacks. At low volume, polling works fine; webhooks become worthwhile when results trigger immediate action.
- Store per record. Keep the on-Zalo status, the country, and the checked timestamp with the record ID.
- Aggregate by country. The Vietnam on-Zalo rate and the regional rates are the output the pipeline exists to produce.
- Alert on the trend, not the point. A single run's number is a sample. Alert when the Vietnam rate drops across two consecutive runs, not when it wobbles once.
Keep the first call small. Push a few records through, verify the response shape, then scale up.
The market read over time
Here is what an aggregated history looks like after a few months:
| Run | Vietnam on-Zalo | Region on-Zalo | Read |
|---|---|---|---|
| January | 84% | 6% | Vietnam is Zalo-first, region is SMS. |
| April | 81% | 5% | Vietnam drifting, still Zalo-first. |
| July | 78% | 6% | Two consecutive drops; re-verify the segment before the next campaign. |
(Numbers here are illustrative examples, not performance claims about the product.)
It’s the July row that makes the entire pipeline worthwhile. Checking once, back in January, would have meant shipping an August campaign at a segment that had quietly lost six points. The schedule caught it.
Webhooks, polling, and idempotent handling
For most teams, polling on a short interval is the simpler option, and when the next action is a quarterly campaign latency hardly matters. Webhooks earn their complexity when results trigger immediate downstream actions, such as releasing a contact into a Zalo broadcast queue the moment the check clears.
If you use webhooks, make the callback idempotent. A single event processed twice must never bill twice or write twice. The sender will retry deliveries with or without your cooperation, and one missed callback should never spin up a second paid job or blank out a clean result with an empty write. Key the handler on job ID plus record ID so duplicate events simply fall through as no-ops.
Unknown rows need a retry budget
Unknown is a normal output on a Zalo file, not an error state. Numbers can be temporarily unreachable at check time and resolve cleanly on a later run. Treat them as a queue:
- Keep unknowns separate from invalid rows in storage and in every export.
- Re-check unknowns on the next scheduled run before spending a new check on them.
- Cap the retries. A row that comes back unknown three runs in a row should move to a manual review list, not cycle forever at full price.
Without a cap, a stubborn 2% of the file can quietly consume a visible share of the quarterly budget. With one, unknowns stay what they should be: a small holding queue with a defined exit.
Which export fields matter
| Field | Why you want it |
|---|---|
record_id |
Connects each result to its source row. |
input_number / normalized_e164 |
Original and comparable forms. |
on_zalo |
The channel signal. |
country_or_region |
The key for the market read. |
checked_at |
The timestamp that makes the trend line possible. |
Mistakes to avoid
- Automating the check but not the market read. A chart nobody reads is decoration. Route the country aggregates into campaign planning; otherwise the schedule is just a report generator.
- Treating the most recent run as current truth. An on-Zalo rate from March is a guess by July.
- Flattening the country split in the export. A single overall percentage hides exactly the Vietnam/region separation the pipeline exists to show.
- Alerting on single-run wobble. Accounts go dormant and numbers recycle constantly; two consecutive drops is a signal, one is noise.
FAQ
How often should the API run?
Monthly is a reasonable baseline for a Zalo list, with a re-check before any big campaign. What matters isn’t which interval you pick; it’s picking one at all.
Why aggregate by country?
Because Zalo is a Vietnam market. The Vietnam on-Zalo rate is the campaign decision; the regional rates are the warnings. A flat number hides both.
Webhooks or polling?
Polling, for most teams. Fewer failure modes, simpler to run, and at low volume the latency cost is nil.
What happens to unknown rows?
They wait for a retry, with a cap of two or three runs before moving to manual review. Keep unknowns separate from invalid rows in the export.
Can the API detect account activity?
No. It reports what the number-level signal shows at check time: on-Zalo status and country. Activity is a separate check.
Related ZelNum pages
- Zalo Number Checker Use Cases, showing how various teams read the same export.
- Bulk Zalo Number Checker: the CSV guide & export format, which covers the file format in detail.
Julian works on verification API integrations, batch jobs, CSV workflows, task polling, retry handling, result exports, and developer documentation. His guides explain how teams can integrate verification APIs safely and connect results with internal data systems.
View full author profile →