Review a contact list with IllyVoIP HLR before a messaging campaign

Use IllyVoIP number analysis and optional HLR to enrich a contact list before an authorized messaging workflow. Run a controlled worker over explicit records; do not treat HLR as permission to contact someone or as a guarantee that an SMS will arrive.

Use an authenticated backend and the API base https://api.illyvoip.com. Send X-Api-Key and JSON bodies. Keep credentials out of browser code. Calls, SMS, lookups and speech can incur charges; examples are templates, not completed transactions.

1. Prepare a bounded list

1. Select records you are authorized to process and retain their stable internal IDs.
2. Resolve country context and normalize numbers deliberately.
3. Deduplicate identical numbers within the intended scope so repeated rows do not cause repeated paid work.
4. Keep suppression, consent and contact preferences separate from network lookup data.

Do not overwrite the customer’s original number until the normalization result is reviewed. Ambiguous national numbers, extensions and multiple pasted values should be held for correction rather than guessed.

2. Use free analysis first

Request GET /api/v1/lookup/number with the number query parameter. Read the returned lookup object, including available formatted_e164, valid_number_format and number_type. A formatting result is not a current handset reachability check.

Store rejected and unknown results explicitly. Do not map absent carrier metadata to “inactive.” A ported number’s current network can differ from static range information.

3. Decide which records need paid HLR

1. State the network or portability question HLR should answer.
2. Review current pricing and account access.
3. Set a maximum record count, bounded concurrency and a spending allowance in your worker.
4. Enable optional deeper checks only when relevant to supported number types and destinations.

The optional fields include include_ported_date, check_landline_activity and check_us_mobile_activity. They are not universally available. Use the lookup guide and current reference for their restrictions; a large list does not justify automatically enabling every paid option.

4. Save one lookup intent per reviewed input

Before POST /api/v1/lookup/hlr, store the normalized number, exact options, job reference and attempt state. Checkpoint each completed row. After a timeout or worker restart, reconcile pending work before issuing another paid request for the same intent.

{
  "number": "+12025550123",
  "include_ported_date": false,
  "check_landline_activity": false,
  "check_us_mobile_activity": false
}

The number is illustrative. This is a paid-request template, not a request to run against the sample. Do not assume an arbitrary new retry is free merely because the endpoint has duplicate-charge protection. Keep its current request contract and returned references with your job evidence.

5. Preserve result meaning and freshness

Store cost_eur, result_source, result_fetched_at and the needed lookup fields. Keep replayed separate from cached network data. Missing optional information stays unknown; a new HTTP response does not prove every field is a fresh live observation.

Put uncertain rows in a review queue instead of deleting contacts or automatically suppressing them. A supported activity result may inform your process, but sender eligibility, destination rules and actual SMS delivery remain separate checks.

6. Review before messaging

Export or display the reviewed lookup outcome with its timestamp and reason. Recheck consent and suppression immediately before any later SMS dispatch. Test duplicate numbers, invalid input, partial job failure, cached results and an uncertain paid response with fixtures before running a small authorized sample. Never restart the whole list blindly after a partial failure.

Related guides

• Check phone numbers with the IllyVoIP Lookup API and optional HLR
• Check a phone number with Number Lookup
• Send an SMS with the IllyVoIP API and track delivery

Reference

Current instructions and technical reference: IllyVoIP API documentation.

Reviewed 13 October 2026 against the current IllyVoIP controls, implementation and applicable references. Available options depend on account permissions and service state.