Validating a number before dialing with check_phone_number

Dialing a number that is malformed, in the wrong time zone, or on a do-not-call list wastes a channel and can land you in compliance trouble. The check_phone_number function checks all of that up front, so you can screen a number before it ever reaches the dialer.

It is part of the Non-agent API, reachable over HTTP with no agent session. Run it from a lead loader or a CRM hook to validate numbers in real time. The VICIdial API and AGI overview places it among the other calls. A clean number is also one that is not on a DNC (do not call) list.

Required fields

• phone_number — all numbers, 6 to 16 digits.
• phone_code — all numbers, 1 to 4 digits, defaults to 1 if you leave it off.
• local_call_time — a valid call time id that already exists in the system.

The phone_code is the Phone Number Prefix dialed ahead of the number, usually the country code.

The checks you can turn on

Each check is its own setting, default off, so you opt into the ones you care about:

• dnc_check — Y, N, or AREACODE. Test the number against the internal do-not-call list.
• campaign_dnc_check — Y, N, or AREACODE. Test against a campaign-specific DNC list. Pass campaign_id with it.
• usacan_prefix_check — Y or N. Confirm the 4th digit is valid for USA and Canada numbers (it cannot be 0 or 1).
• usacan_areacode_check — Y or N. Confirm the area code is valid for USA and Canada.
• tz_method — empty, POSTAL, TZCODE, NANPA, or AREACODE, to pick how the time zone is worked out. You can combine them, like AREACODEPOSTAL.

Permission requirement

The API user needs user_level 8 or higher. Securing that user is worth doing right, which the guide to securing the VICIdial API covers.

Example call

Validate a number with several time-zone methods at once:

http://your-server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=check_phone_number&phone_number=3125551212&postal_code=81009&owner=GST&local_call_time=9am-9pm&tz_method=AREACODEPOSTALNANPATZCODE

How a number gets screened

flowchart TD
  Number[phone_number] --> Length{length 6 to 16}
  Length -- bad --> LenErr[INVALID LENGTH]
  Length -- ok --> Prefix{prefix valid}
  Prefix -- bad --> PreErr[INVALID PREFIX]
  Prefix -- ok --> DNC{dnc_check}
  DNC -- on list --> DncErr[PHONE NUMBER IN DNC]
  DNC -- clear --> TZ[time zone lookup]
  TZ --> Result[Dialable result returned]

Reading the response

A success response does not print SUCCESS. For each tz_method it prints a 0 or 1 for dialable plus the GMT offset, then a hash, then the phone details. For example:

AREACODE: 1|-6#PHONE: 3125551212|1||||

That leading 1 means dialable. The failure strings are blunt: ERROR: check_phone_number INVALID PHONE NUMBER LENGTH, ERROR: check_phone_number INVALID PHONE NUMBER PREFIX, ERROR: check_phone_number INVALID PHONE NUMBER AREACODE, and the one you most want to catch, ERROR: check_phone_number PHONE NUMBER IN DNC. A bad call time returns ERROR: check_phone_number THIS IS NOT A VALID CALL TIME, and a missing permission returns ERROR: check_phone_number USER DOES NOT HAVE PERMISSION TO CHECK PHONE NUMBERS.

Screening with check_phone_number pairs well with adding leads through the API: validate first, insert only the clean numbers. On a VICIfast server the API answers from the moment your box is up, in under 40 seconds. See our plans.