REST API

REST API

To communicate to the web service you will need to request the following URL as a web service URL using your programming language.

API URL: https://avidtrak.com/webservice/api.php

Web Service Type: REST

Required Parameters for all actions:

  • pincode: pincode for authentication purpose
  • method: data to be pulled for
  • format: json or xml

Note: Every method has its own set of parameters as well mentioned under each method detail below

Example URL: https://avidtrak.com/webservice/api.php?pincode=YOUR_PIN_CODE&format=xml&method=search_number

How to Get Pincode for Agency

  • Login to AvidTrak interface at https://passport.avidtrak.com
  • Navigate to “Account Settings” page and click “Preferences”
  • You will see your Pincode under "API" heading, If Pincode is empty then click "Generate" button to generate it

How to Get Pincode for Individual Client & Agency Client

For Agency Client

  • Login to AvidTrak interface at https://passport.avidtrak.com
  • Navigate to “Account Settings” page and click “Preferences”
  • You will see your Pincode under "API" heading, If Pincode is empty then click "Generate" button to generate it

For Client Accounts

Correct Response:

Following is the response upon successful query.

JSON XML
{
“code”:200,
“status”:”Success”,
“data”:[{
“channel”:”PORTAL”,
“campaign”:”Internet X-Sell
},
{
“channel”:”PORTAL”,
“campaign”:”Internet X-Sell
}]
}		 <response>
<code>1</code>
<status>Success</status>
<data>
<row>
<channel>PORTAL</channel>
<campaign>Internet X-Sell </campaign>
</row>
<row>
<channel>PORTAL</channel>
<campaign>Internet X-Sell West</campaign>
</row>
</data>
</response>

Incorrect Response:

Following is the response if an error is produced from the server

JSON XML
{
“code”:401,
“status”:”Authentication Failed”,
“data”:null
}		 <response>
<code>401</code>
<status>Authentication Failed</status>
<data><data/>
</response>

Response Codes and Status

Code Status Description
1 Success Successfully performed the action
0 Unknown Error Mostly if any method related parameters are invalid or missing or data not found
3 Authentication Required PINCODE not provided
4 Authentication Failed Invalid Pincode
6 Invalid Response Format Response format provided other then xml or json
404 Invalid Request Method Provided method name is invalid

Methods:

Create Client Account

This method is used to create new client account under agency

Method name: create_account

Parameters

Parameter Required Description
userid Yes User ID for new client
password Yes Password for new client Alphanumeric
account_type Yes
  • pro (Online/Offline tracking)
  • lite (Offline tracking)
email No Email address for client
contact_name No Name of Client
contact_number No Contact number for client
domain No Client Domain

Note: The Pincode for new account will be provided in method reply if account successfully created

Responses

You might get different responses as shared below.

>Upon finding that the UserID already exist you will get the response:-

Upon a successful account creation the response will be:-

Update User Detail:

This method is used modify user details like changing User ID or password contact name and email for agency or client

Method name: update_user_details

Parameters

Parameter Required Description
username No To change User id for provided Pincode
fullname No Change contact name
email No Change email
password No Change password

Note: Provide at least one parameter to make it function correctly

Upon a successful data update you will get the response:-

If a UserID already exist the response will be:-

Search and Purchase Number

Purchase number is divided in two methods. First you will search for numbers you want to purchase for your call tracking, it will give the available numbers according to your criteria. Then you will select and provide the number to another function from the available numbers for the final purchase.

Search Number

Method name: search_number

Parameters

Parameter Required Description
quantity Yes Quantity of numbers you want to search
(Maximum quantity is 30)
number_type Yes
  • toll (toll free numbers)
  • local (local numbers)
area_code Yes Area code for which you want to purchase numbers
country No ISO format Country code for which you want to purchase numbers. Default is US

The Successful response of method search_number will be:-

Purchase Number

Method name: purchase_number

Parameters

Parameter Required Description
number_type Yes
  • toll (toll free numbers)
  • local (local numbers)
number[] Yes Number(s) you want to purchase in array
Ex:
number[]=4101234567&number[]=2101234567
country No ISO format Country code for which you want to purchase numbers. Default is US

Note: Multiple numbers can be transferred as a batch to a single client specified by client pincode.

For Batch Process use “number” parameter like this:

number []=PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX1&number []=PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX2&number []=PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX3

in case you have no balance or fewer amounts then the purchase_number response will be:-

Upon a successful number purchase the response will be:-

Transfer Number

This method will transfer numbers, with the given SIDs, to the Client Account selected by the agency using “client_pin” parameter.

Method name:transfer_number

Parameters

Parameter Required Description
sid[] Yes Phone number SID
client_pin Yes Client’s Pincode.

Note: Multiple numbers can be transferred as a batch to a single client specified by client pincode.

For Batch Process use SID like this:

sid[]=PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX1&sid[]=PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX2&sid[]=PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX3

Upon a successful number transfer you will get the response:-

Number Assignment

After purchasing a number you have to assign it a marketing channel in case of an online dynamically inserted number or as static (LITE) in case of an offline number. This method will assign a search engine to the given SID.

Method name: assign_number

Parameters

Parameter Required Description
sid[] Yes Phone number SID
type Yes
  • gppc (Google PPC)
  • gseo (Google Organic)
  • yppc (Yahoo PPC)
  • yseo (Yahoo Organic)
  • bppc (Bing PPC)
  • bseo (Bing Organic)
  • direct (Direct Visit)
  • universal (Universal Number)
  • lite (Offline Number)
  • linksource (Link Source)

Note: For Batch Process use SID like this:

sid[]=PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX1&sid[]=PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX2&sid[]=PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX3

Upon a successful number assignment you will get the response:-

List Numbers

This method will list the numbers under client

Method name: list_numbers

Parameters

Parameter Required Description
number_type No
  • toll
  • local

If parameter not set, it will provide all types of numbers.
assignment_type No
  • assigned
  • unassigned
  • all

If parameter not set, it will provide all numbers.
area_code No Valid Area Code. In case of Toll Number, it can be provided as 800,855,866….
If parameter not set, it will provide all numbers.

Upon a successful number listing you will get the response:-

Set Forwarding (where calls are to be received)

This method will change the receiving number against the provided phone number SID or by type. The phone number SID is available from “list_number” method against each of your numbers.

Method name:set_forwarding

Parameters

Parameter Required Description
sid[] Yes (if type is provided as sid) Phone number SID
forward_number Yes Receiving number
extension No Extension of receiving number.
type Yes
  • pro
  • lite
  • sid

Note: If type=pro is requested, the same forwarding number will be set for all of the online (pro) tracking numbers.

If type=lite is requested , the same forwarding number will be set for all of the offline (lite) tracking numbers.

If type=sid is requested , the same forwarding number will be set for all of the phone numbers provided as sid[]=1112223331& sid[]=1112223332&sid[]=1112223333

The response of a set forwarding method will be :-

Remove Forwarding

This method will remove the receiving number against the provided phone number SID or by type. The phone number SID is available from “list_number” method against each of your numbers.

Method name:remove_forwarding

Parameters

Parameter Required Description
sid[] Yes (if type is provided as sid) Phone number SID
type Yes
  • pro
  • lite
  • sid

Note: If type=pro is requested, this will remove the forwarding number of all of the online (pro) tracking numbers.

If type=lite is requested, this will remove the forwarding number of all of the offline (lite) tracking numbers.

If type=sid is requested, this will remove the forwarding number of all of the phone numbers provided in sid parameter as sid[]=1112223331&sid[]=1112223332&sid[]=1112223333

Upon a successful forwarding removal you will get the response:-

Insert Round Robin Settings

Round Robin call forwarding allows you to sequentially forward an incoming call to different receiving numbers. In this method the system forwards the call first to your default receiving number and if the call is not answered by the default number, after a set number of rings the call is forwarded to the next receiving number on the list.

Method name:insert_round_robin

Parameters

Parameter Required Description
sid Yes Phone number SID
forwarding_number[] Yes 1st, 2nd,3rd… receiving numbers.
extension[] No Extension of a forwarding number.
label[] No Label of receiving number.
use_default_first No
  • yes
  • no

Enabling this feature allows for calls to be transmitted to a live
attendant rather than an auto-attendant.

Note: Default value of “use_default_first” parameter is “yes”. If provided as “no” receiving number will only be chosen from the round robin list set for that number.

For Batch Process use SID like this:.

sid[]=PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX1&sid[]=PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX2&sid[]=PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX3

First forwarding_number[] parameter will belong to first label[] parameter.

First forwarding_number[] parameter will belong to first label[] parameter.

e.g.

forwarding_number[]=1112223331& forwarding_number[]=1112223332&

forwarding_number[]=1112223333&label[]=label_for_1112223331&label[]=label_for_1112223332&label[]=label_for_1112223333

Upon adding a successful round robin setting you will get the response:-

List Round Robin Settings

This method will list round robin settings of provided number SID. The phone number SID is available from “list_number” method against each of your numbers

Method name:list_round_robin

Parameters

Parameter Required Description
sid Yes Phone number SID

Round robin list response will be:-

Edit Round Robin Settings

This method will update round robin settings of provided number SID. The phone number SID is available from “list_number” method against each of your numbers and “round_robin_list_id” is available from “list_round_robin” method against each of SID parameter.

Method name: edit_round_robin

Parameters

Parameter Required Description
sid Yes Phone number SID
forwarding_number Yes 1st, 2nd,3rd… receiving numbers.
extension[] No Extension of a forwarding number.
label No Label of receiving number.
round_robin_list_id Yes Round Robin List Id.
use_default_first No
  • yes
  • no

Enabling this feature allows for calls to be transmitted to a live
attendant rather than an auto-attendant.

Upon editing Round robin the response will be:-

Delete Round Robin Settings

This method will delete round robin settings of provided number SID. The phone number SID is available from “list_number” method against each of your numbers and “round_robin_list_id” is available from “list_round_robin” method against each of SID parameter.

Method name: delete_round_robin

Parameters

Parameter Required Description
sid Yes Phone number SID
round_robin_list_id Yes Round Robin List Id.

Upon deleting Round robin the response will be:-

Update Number Settings

This method will change the extra settings for your phone numbers like caller greeting, whisper message, call recording

Method name: update_number_setting

Parameters

Parameter Required Description
sid Yes Phone number SID
recording No 0 or 1
0 for recording off 1 for recording on
greet_caller No Preamble the caller will hear  when connected
whisper_message No Message receiver will hear  when receiver answers
enable_email No 0 or 1
1 to enable call data to be emailed to default email address of user
0 to off email alerts
email_alerts No Comma separated email addresses to which call data will be delivered

Note: Call data will be delivered once a day for the previous day’s calls. At least one parameter should be provided from the non required parameters to make this function work correctly

Update number settings response will be:-

Add Lite Campaign (add static number campaigns)

This method will create a new offline campaign for the given phone number.

Method name: add_lite_campaign

Parameters

Parameter Required Description
title Yes Title for offline campaign
sid Yes Phone number SID for which campaign will be created
adgroup No Only a caption to denote which ad group this campaign belongs
forward_number No If you wish to forward calls for this campaign to a separate number.
You can change forwarding for numbers later by using set_forwarding method
extension No Extension of forwarding number.

Lite Campaign (Example Offline Campaigns: Print, TV & Radio)

This method will provide all offline active campaign details with the number of calls.

Method name: lite_campaign

Parameters

Parameter Required Description
startdate No Date from which you want to extract data. This can be in two formats
YYYY-MM-DD (year-month-day)
YYYY-MM-DD HH:MM:SS (year-month-day hour:minute:second)
enddate No Date till which you want to extract data. This can be in two formats
YYYY-MM-DD (year-month-day)
YYYY-MM-DD HH:MM:SS (year-month-day hour:minute:second)

The offline campaigns response will be:-

Lite Campaign Calls

This method will provide all the offline campaign calls.

Method name: all_lite_calls

Parameters

Parameter Required Description
Startdate No Date from which you want to extract data. This can be in two formats
YYYY-MM-DD (year-month-day)
YYYY-MM-DD HH:MM:SS (year-month-day hour:minute:second)
Enddate No Date till which you want to extract data. This can be in two formats
YYYY-MM-DD (year-month-day)
YYYY-MM-DD HH:MM:SS (year-month-day hour:minute:second)

The response will be:-

Call Logs

This method will provide call data

Method name: call_logs

Parameters

Parameter Required Description
Startdate No Date from which you want to extract data. This can be in two formats
YYYY-MM-DD (year-month-day)
YYYY-MM-DD HH:MM:SS (year-month-day hour:minute:second)
Enddate No Date till which you want to extract data. This can be in two formats
YYYY-MM-DD (year-month-day)
YYYY-MM-DD HH:MM:SS (year-month-day hour:minute:second)

Note: By default the data will be provided for “yesterday”

The response will be:-

Client List

This method will provide the pincodes against each client username for an agency. This method will only work if the agency pincode is used

Method name: client_list

Parameters

No Parameters except required one mention in page 4.

The response will be:-

Get Remaining Balance

This method will provide remaining balance against the pincode.

Method name: get_remaining_balance

Parameters

No Parameters except required one mention in page 4.

The response will be:-

Return Number

This method will return numbers to Agency Account and/or Delete Permanently by returning to the Telephone Company (telco) for the given phone number SID.

Method name: return_number

Parameters

Parameter Required Description
sid[] Yes Phone number SID
location Yes Possible Values:

  • telco
  • agency

Note: Default value of “location” parameter is ‘telco’. This will effectively delete the number.

“location” can be provided as “agency” only if a client is under an agency.

“For Batch Process use SID like this:

sid[]=PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX1&sid[]=PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX2&sid[]=PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX3

WARNING: Number Returned to “telco” CAN NOT be re-acquired.

The response will be:-

Visit Data

This method will provide Visit data by keyword.

Method name: visit_data

Parameters

Parameter Required Description
filter Yes Fixed values for search engine:
gppc = Google PPC
gseo = Google Organic
yppc = Yahoo PPC
yseo = Yahoo Organic
bppc = Bing PPC
bseo = Bing Organic
startdate No Start Date of range from which you want to extract data. This can be in two formats
YYYY-MM-DD (year-month-day)
YYYY-MM-DD HH:MM:SS (year-month-day
hour:minute:second)
enddate No Date up to which you want to extract data. This can be in two formats
YYYY-MM-DD (year-month-day)
YYYY-MM-DD HH:MM:SS (year-month-day
hour:minute:second)

The response will be:-

Smart Replacement: Add Website Number(s) for Dynamic Replacement

This method will add or delete to the AvidTrak SMART REPLACE manifest of website telephone numbers that you wish to target for dynamic swap with AvidTrak call tracking number(s).

Method name: set_smart_replacement

Parameters

Parameter Required Description
site_phone[] Yes Phone number on your website.
action Yes
  • add
  • delete

Upon adding the smart replacement number the response will be:-

Upon deleting the smart replacement number the response will be:-

Metro: Add Site Number for Metro

This method will add the website phone number of a specific company based on a Metropolitan “Metro” page which is to be targeted for a dynamic swap and replaced by a call tracking tracking number assigned to it.

Method name: add_metro_site_number

Parameters

Parameter Required Description
site_number Yes Phone number on your website.
Title yes Title for site number
forward_number Yes Forward number where the associated tracking numbers will forward to

The response will be:-

Metro: List Metro Numbers

This method provides a manifest of all targeted website Swap numbers, any names thereof of targeted swap numbers; along with the tracking numbers associated with the targeted swap number.

Method name: list_metro_numbers

Parameters

None

The response will be:-

Metro: Allocate Tracking Number to Metro Site Number

This method will allocate tracking number(s) to metro site number. You will need to provide tracking number SIDs. You can find the SID by using list_numbers method and site id that you can get through the list_metro_numbers method

Method name: add_metro_site_number

Parameters

None

Parameter Required Description
sid Yes Provide single sid or array of sid
Example:
sid = abcxyz
sid[]=abcxyz&sid[]=xyzabc
site_id Yes Site ID of the site number

The response will be:-

Metro: Remove Metro Site Number

This method will remove metro site number along with the phone number allocation. This method also changes the forwarding of the allocated number of provided site id to the default forwarding number.

Method name: remove_metro_site_number

Parameters

None

Parameter Required Description
site_id Yes Site ID of the site number

The response will be:-

AVIDTRAK CALL TRACKING FAQs!

Use the Estimator tool to determine how many phone numbers you will need to perform keyword level call tracking.

If your account balance drops below $0 services to your account may be suspended. It is therefore essential that your account always maintain a positive balance. In the event that your credit card is declined AvidTrak’s billing system will issue a warning email advising you of the issues evidenced with your card. It is therefore important that you keep your billing email updated. Your billing email on file may be verified and/or updated by logging into your account and clicking My Account > My Account Setting.

Understand the customer’s digital journey on your website. Learn which pages are working for you in generatinggenerate the highest phone leads calls and sales.