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.

Incorrect Response:

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

Response Codes and Status

Methods:

Create Client Account

This method is used to create new client account under agency

Method name: create_account

Parameters

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

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

The Successful response of method search_number will be:-

Purchase Number

Method name: purchase_number

Parameters

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

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

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

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

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

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

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

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

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

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

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

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

The offline campaigns response will be:-

Lite Campaign Calls

This method will provide all the offline campaign calls.

Method name:all_lite_calls

Parameters

The response will be:-

Call Logs

This method will provide call data

Method name:call_logs

Parameters

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

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

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

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

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

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

The response will be:-