Pulling every call to a number with phone_number_log

When a customer calls in asking "have you ever called my number?" you want one query that answers it — every dial to that number, inbound or outbound, with the result of each. The Non-Agent API function phone_number_log is that query. It exports the list of calls placed to one or more phone numbers, and unlike a DID export it can cover several numbers in a single call.

Fields and filters

Only one field is required:

• phone_number — one or more numbers, separated by commas

From there, a few optional settings shape the result:

• detail — ALL calls (default) or only the LAST call to each number
• type — IN inbound, OUT outbound (default), or ALL calls
• archived_lead — set Y to query the archive list table instead of the live one (default N)
• stage and header — output format (csv, tab, json, pipe) and optional header row

As with the other reporting functions, the api user needs user_level 7 or higher with "view reports" enabled.

A real example call

Here is a lookup across two numbers at once. The source parameter is your free-text label for who made the request.

http://your-server/vicidial/non_agent_api.php?source=test&function=phone_number_log&stage=pipe&user=6666&pass=1234&phone_number=3125551212,9998887112

A successful call prints one pipe-delimited line per call, no SUCCESS header:

phone_number|call_date|list_id|length_in_sec|lead_status|hangup_reason|call_status|source_id|user

9998887112|2017-01-06 08:11:01|82106|25|TD|AGENT|SALE|mail098|6666

You get the number, timestamp, the list it came from, call length, the lead's Disposition (the agent's chosen outcome code, TD here), the hangup reason, the Called status (the dialer's call result, SALE here), the lead source id, and the agent. That single row tells you who touched the number, when, and how the call ended.

How the export flows

sequenceDiagram
    participant R as Reporting client
    participant API as non_agent_api.php
    participant L as vicidial_log
    participant C as vicidial_closer_log
    R->>API: phone_number_log + numbers + type
    API->>API: check user_level >= 7
    API->>L: match outbound calls
    API->>C: match inbound calls
    L-->>API: rows
    C-->>API: rows
    API-->>R: pipe stream merged by number

One performance gotcha

The phone_number field is not indexed by default in the vicidial_log and vicidial_closer_log tables. If you plan to lean on this function, ask whoever runs your database to add an index on that column in both tables — otherwise each lookup does a full table scan and gets slower as your call volume grows. On a managed VICIfast box you have full root, so you (or our support) can add those indexes without a ticket war.

Errors and limits

A permission failure returns ERROR: phone_number_log USER DOES NOT HAVE PERMISSION TO GET CALL LOG INFO - 6666|0. If no valid numbers parse out of your input you get ERROR: phone_number_log NO VALID PHONE NUMBERS DEFINED, and a valid search with no matches returns ERROR: phone_number_log NO RECORDS FOUND. There is a hard limit of 100,000 results. For a single inbound number on a single day, did_log_export is the lighter-weight option.

Every VICIfast plan ships with the Non-agent API and full API (application programming interface) access, so you can build a number-history lookup into your CRM in an afternoon. Compare what is included on the pricing page.