DialogTech's Bid Management API is designed as a REST API which provides well-formed JSON responses. As the API is accessible via HTTP, any programming language with the ability to make web-service calls can be used to create applications which leverage this API.
Base URI
API Security
DialogTech's Bid Management API expects 1 header key Authorization with a value of Bearer Token where Token is replaced by the appropriate account token provided by DialogTech.
NOTICE
Your Bid Management Token should be protected. It should not be written anywhere they can be accessed by anyone not authorized to use your DialogTech account or its associated data. If you think your Bid Management Token has been compromised, please contact us immediately at [email protected].
| Request Header | Required | Value | Description |
|---|---|---|---|
| Authorization | Yes | Bearer Token | A token provided by DialogTech to authorize the Bid Management API for a specific account |
| Content-Type | No | application/json | Though this header is not required, we strongly suggest deliberately specifying the application/json Content-Type type for web-enabled applications using this API. |
Pagination
There are 2 URL Parameters that can be used to leverage pagination within these APIs
| Parameter | Description |
|---|---|
| &start= | Determines the record set of items returned. |
| &rows= | Determines the amount of records returned in 1 request. Also defines the record set size when using the start parameter. |
Example Pagination Request/Response
GET /v2/user/bid-management?rows=2&start=1
Content-Type: application/json
Authorization: Bearer 12345abcde
Content-Range: 3-4/18
In this response note the Content-Range: 3-4/18 represents rows 3-4 were returned (1 offset of 2 rows) and there is a a total record count of 18.
Filtering
Filtering is available by use of a structured Querystring parameter.
Best Practice
When requesting data from the Bid Management API, we recommend using a date filter on every request or request details for a single call using a Single Sid Request
q= | URL Parameter to represent the filtering query |
: | Query operation delimiter |
[ and ] | Inclusive Range Identifier |
{ and } | Exclusive Range Identifier |
, | Deliminate Querystring Parts |
The following request is going to filter based on the date_added value, and the talk_minutes value.
date_added Should be any calls on or after 2017-01-01 at 06:30 EST, but before 2017-01-01 18:00 EST.
talk_minutes Should be greater than or equal to 0.5 minutes.
/v2/user/bid-management?q=date_added:[2017-01-01%2006:30:00%20TO%202017-01-01%2018:00:00},talk_minutes:[0.5%20TO%20*]
Response
The response to this API will be demonstrated assuming the Content-Type from the request is application/json.
[
{
"acct_id": "55555",
"smart_minutes": "0.1",
"date_added": "2017-12-01 16:38:13",
"talk_minutes": "0.0",
"talk_start": "2017-12-01 16:38:19.0",
"talk_end": "2017-12-01 16:38:19.0",
"dnis": "5556667777",
"ani": "8887776666",
"first_name": null,
"last_name": null,
"street_address": null,
"city": null,
"state": null,
"zipcode": null,
"call_logging_id": null,
"sid": "1712010011223344",
"rank": "1",
"search_term": null,
"incoming_keyword": "tag",
"activity_type_id": 3,
"url_tag": "tag",
"baseuri": "http://www.example.com/?st-t=tag",
"last_touch": null,
"last_touch_timestamp": null,
"referrer": "",
"ip_address": "127.0.0.1",
"displayed_timestamp": "2017-12-01 16:29:21",
"phone_number": "",
"super_id": null,
"pool_id": 00000,
"domain_set_id": 00000,
"activity_keyword": "tag",
"phone_label": null,
"vt_keyword": null,
"vt_matchtype": null,
"vt_network": null,
"vt_device": null,
"vt_devicemodel": null,
"vt_creative": null,
"vt_placement": null,
"vt_target": null,
"vt_param1": null,
"vt_param2": null,
"vt_random": null,
"vt_aceid": null,
"vt_adposition": null,
"vt_adwords_producttargetid": null,
"vt_adtype": null,
"recording": null,
"adwords_account_id": null,
"adwords_campaign_id": null,
"adwords_adgroup_id": null,
"adwords_keyword_id": null,
"channel": "SourceTrak"
}
]
| Key | Value |
|---|---|
| acct_id | The DialogTech Account ID |
| smart_minutes | The duration, in tenths of a minute, a call is on the system while not connected to another party. |
| date_added | Date and time the call was made. |
| talk_minutes | The duration, in tenths of a minute, a call is on the system while connected to another party. |
| talk_start | The timestamp a call on the system connected to a second party. |
| talk_end | The timestamp a call on the system disconnected from a second party. |
| dnis | The number dialed |
| ani | Caller ID of the caller |
| first_name | First name of caller if reverse-lookup is enabled and data was found |
| last_name | Last name of caller if reverse-lookup is enabled and data was found |
| street_address | Street address of caller if reverse-lookup is enabled and data was found |
| city | City of caller if reverse-lookup is enabled and data was found |
| state | State of caller if reverse-lookup is enabled and data was found |
| zipcode | Zipcode of caller if reverse-lookup is enabled and data was found |
| call_logging_id | Deprecated - We do not advise collecting, logging, or leveraging this value. It should be null at all times. |
| sid | Unique DialogTech assigned identifier for the call |
| rank | A general confidence indicator between 1 and 5 of how a phone call is matched to an individual session. A lower rank indicates a higher confidence. |
| search_term | The literal search string (keywords) that resulted in the display of a phone number on a website. |
| incoming_keyword | Property of the users visit that matched the SourceTrak activity |
| activity_type_id | The SourceTrak activity type by id which triggered DNI |
| url_tag | The URL tag from SourceTrak that caused the number to rotate with wildcards replaced by the value associated with the website visit (i.e. st-t=googlebogo_campaign as opposed to st-t=google )* |
| baseuri | The location where the user was first attributed to a visit. |
| last_touch | The location where the user was last attributed to a visit. |
| last_touch_timestamp | The timestamp the last touch ocurred |
| referrer | The domain the visitor originated from |
| ip_address | The IP address of the visitor |
| displayed_timestamp | The timestamp the visitor was first shown a DNI number and tracking began |
| phone_number | Deprecated - We do not advise collecting, logging, or leveraging this value. It should be null most times. If the numbers associated with a call are required, please use dnis and ani |
| super_id | An ID associated with the visitor |
| pool_id | The ID of the pool the SourceTrak number originated from |
| domain_set_id | The ID of the domain set the SourceTrak visit is tracked from |
| activity_keyword | The URL tag from SourceTrak that caused the number to rotate (i.e. gclid= *) |
| phone_label | The label assigned to the phone number |
| vt_keyword vt_matchtype vt_network vt_device vt_devicemodel vt_creative vt_placement vt_target vt_param1 vt_param2 vt_random vt_aceid vt_adposition vt_adtype | Please refer to the ValueTrack Parameters section of the Call Detail Report API for a definition and usage of these fields. There are no required URL Parameters on the Bid Management API to return these fields. This means you do not need to add &valuetrack=1 like you would in the Call Detail Report API. |
| adwords_account_id | The Google Adwords Account ID if available |
| adwords_campaign_id | The Google Adwords Campaign ID if available |
| adwords_adgroup_id | The Google Adwords Adgroup ID if available |
| adwords_keyword_id | The Google Adwords Keyword ID if available |
| channel | The DialogTech tracked channel the call originated from. Either SourceTrak or Call Extension |
Additional Functions
| Name | Endpoint | Description |
|---|---|---|
| Single Sid Request | /v2/user/bid-management/:sid | :sid can be replaced with any valid Session ID for the account. This is used for Single Record Retrieval. |
| Count Request | /v2/user/bid-management/count | Makes a record count request. |