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://avidtrak.com/accounts
• Navigate to “Settings” page and click “Generate New PIN”
• A new Pincode will be generated and shown with the generate button as shown in image below

How to Get Pincode for Client

For Agency Client

• Navigate through “API” under agency area
• Select client for you wish to generate Pincode
• Click “Generate Pin” to generate new Pincode as shown in image below

For Individual Client

• Navigate to “My Accounts” -> “My Account Settings”
• Click “Show/Hide” button to show advance settings
• Open “Generate APIPin” area and click “Regenerate Pin” to generate new Pincode as shown below

Response:

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.

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:-