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
What's New in Bid Management API v3
Version 3 of the Bid Management API includes several renamed parameters, deprecated parameters, and a variety of additional parameters.
Parameter Name Changes:
| /v2 parameter name | /v3 parameter name |
|---|---|
| baseuri | first_touch |
| adwords_account_id | ppc_account_id |
| adwords_campaign_id | ppc_campaign_id |
| adwords_adgroup_id | ppc_adgroup_id |
| adwords_keyword_id | ppc_keyword_id |
Deprecated Parameters:
- phone_number -- If the numbers associated with a call are required, please use
dnisandani - super_id
- call_logging_id
Parameter Additions:
- first_touch_title
- first_touch_domain
- landing_page
- last_touch_title
- last_touch_domain
- conversion_page
- ppc_status
- ppc_match_type
- ppc_campaign
- ppc_ad_group
- ppc_keywords
- ppc_ad_id
- ppc_gclid
- os
- os_version
- browser
- browser_version
- location_id
- call_duration
- pid
API Security
DialogTech's Bid Management API expects two header keys: access_key and secret_key with corresponding values equal to your Access Key and Secret Key respectively.
Legacy users may still use a Bid Management Token by instead submitting 1 header key Authorization with a value of Bearer Token where Token is replaced by the appropriate account token provided by DialogTech.
NOTICE
Your API Keys should be protected. They should be stored in a secure location and only accessed by authorized DialogTech users or in applications with associated data. If you think your API Keys have been compromised, please contact us immediately at [email protected].
| Request Header | Required | Value | Description |
|---|---|---|---|
| access_key | Yes | {your-access_key} | One of two keys provided by DialogTech required to authorize the Bid Management API for a specific account |
| secret_key | Yes | {your-secret_key} | The second of two keys provided by DialogTech required to authorize the Bid Management API for a specific account |
| Authorization | Yes* | Bearer {your-token} | A token provided by DialogTech to authorize the Bid Management API for a specific account *Legacy users can authorize using their Bearer token instead of access_key and secret_key |
| 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 /v3/user/bid-management?rows=2&start=1
Content-Type: application/json
access_key: abc123
secret_key: xzy456
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 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 requesting 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 |
, | Deliminate Querystring parts |
inc_gce:1 | Return results for Google Call Extensions calls |
The following request is going to filter based on the date_added value.
date_added Should be any calls on or between 2018-01-01 at 06:30 EST and 2018-01-01 18:00 EST.
/v3/user/bid-management?q=date_added:[2018-01-01%2006:30:00%20TO%202018-01-01%2018:00:00]
Response
The response to this API will be demonstrated assuming the Content-Type from the request is application/json.
[
{
"acct_id": "12345",
"smart_minutes": "0.8",
"date_added": "2018-10-16 18:04:01",
"talk_minutes": "5.8",
"talk_start": "2018-10-16 18:04:49.0",
"talk_end": "2018-10-16 18:10:37.0",
"dnis": "5555555555",
"ani": "5551231234",
"first_name": null,
"last_name": null,
"street_address": null,
"city": null,
"state": null,
"zipcode": null,
"call_logging_id": null,
"sid": "181001008712111",
"rank": "2",
"search_term": null,
"incoming_keyword": "www.google.com",
"activity_type_id": 2,
"url_tag": "",
"first_touch": "https://www.mydomain.com/sample-landing-page",
"first_touch_title": "Company ABC | Sample Landing Page",
"first_touch_domain": "www.mydomain.com",
"landing_page": "/sample-landing-page",
"last_touch": "https://www.mydomain.com/sample-conversion-page",
"last_touch_title": "Company ABC | Sample Conversion Page",
"last_touch_domain": "www.mydomain.com",
"last_touch_timestamp": "2018-10-16 18:03:39",
"conversion_page": "/sample-conversion-page",
"referrer": "https://www.google.com/",
"ip_address": "111.11.11.111",
"displayed_timestamp": "2018-10-16 18:00:55",
"pool_id": 12345,
"domain_set_id": 54321,
"activity_keyword": "*google.com*",
"phone_label": "Website (Mobile) - Google Organic",
"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,
"ppc_account_id": null,
"ppc_ad_id": null,
"ppc_campaign_id": null,
"ppc_campaign": null,
"ppc_adgroup_id": null,
"ppc_adgroup": null,
"ppc_keyword_id": null,
"ppc_keywords": null,
"ppc_status": "N/A",
"ppc_match_type": null,
"ppc_gclid": null,
"channel": "SourceTrak",
"custom_id": null,
"custom_value": null,
"os": "Android",
"os_version": "7.1.2",
"browser": "Chrome Mobile",
"browser_version": "68.0.3550",
"location_id": 98765,
"call_duration": "7",
"pid": "783eefg0-c5c5-11e8-a81f-9b87d0e36788"
}
]
| 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, where a call is on the system while connected to another party. |
| talk_start | The timestamp where a call on the system is connected to a second party. |
| talk_end | The timestamp where a call on the system is 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. |
| 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 user's visit that matched the SourceTrak activity. |
| activity_type_id | The SourceTrak activity type by id which triggered DNI: 1 - Direct Default 2 - Referrer Domain 3 - Tagged URL 4 - Organic Search Keyword 5 - All Organic Search 6 - Url Path 7 - Custom Tagged URL 8 - Direct Visit |
| 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 )*. |
| first_touch | The full url of the page where the user was first attributed to a SourceTrak visit (e.g. https://www.mydomain.com/sample-landing-page). |
| first_touch_title | The document title of the first page where the user was first attributed to a SourceTrak visit (e.g. "Sample Landing Page"). |
| first_touch_domain | The domain of the location where the user was first attributed to a SourceTrak visit (e.g. www.mydomain.com). |
| landing_page | The first page where the user was first attributed to a SourceTrak visit, excluding the domain (e.g. /sample-landing-page). |
| last_touch | The full url location where the user was last attributed to a visit before placing a phone call (e.g. https://www.mydomain.com/sample-conversion-page). |
| last_touch_title | The document title of the last page where a user was attributed to a visit before placing a phone call (e.g. "Sample Conversion Page". |
| last_touch_domain | The domain of the last location where the user was attributed to a visit before placing a phone call (e.g. www.mydomain.com). |
| last_touch_timestamp | The timestamp when the last touch occurred. |
| conversion_page | The last page where the user was attributed to a visit before placing a phone call, excluding the domain (e.g. /sample-conversion-page). |
| referrer | The domain where 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. |
| 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. |
| ppc_account_id | The Google Ads account ID if available. |
| ppc_campaign_id | The Google Ads campaign ID if available. |
| ppc_campaign | The text name of the Google Ads campaign if available. |
| ppc_adgroup_id | The Google Ads ad group ID if available. |
| ppc_adgroup | The text name of the Google Ads ad group if available. |
| ppc_keyword_id | The Google Ads Keyword ID if available. |
| ppc_keywords | The text of Google Ads keywords if available. |
| ppc_status | Indicates the state of processing for Google Call Extension calls and SourceTrak calls when the first touch includes a Google Click ID (gclid). Possible values include: Not ProcessedWaiting For KeywordProcessedDesktopNo MatchN/A (SourceTrak call with no GCLID) |
| ppc_match_type | The Google Ads Match Type if available Note: Match Type is not available for legacy Google Call Extensions. |
| ppc_ad_id | The Google Ads ad ID if available. |
| ppc_gclid | The Google Ads click id if available. |
| channel | The DialogTech tracked channel the call originated from. Either SourceTrak or Google Call Extensions. |
| custom_id | The value of the _st_custom_id variable used with SourceTrak from a website visitor. |
| custom_value | The value of the _st_custom_value variable used with SourceTrak from a website visitor. |
| os | The operating system of the SourceTrak visitor if applicable. |
| os_version | The operating system version of the SourceTrak visitor if applicable. |
| browser | The web browser of the SourceTrak visitor if applicable. |
| browser_version | The web browser version of the SourceTrak visitor if applicable. |
| location_id | The SourceTrak location ID if applicable. |
| call_duration | The duration of the phone call, rounded up to the next minute. |
| pid | Unique DialogTech assigned identifier for a SourceTrak visitor. |
Additional Functions
| Name | Endpoint | Description |
|---|---|---|
| Single Sid Request | /v3/user/bid-management/:sid | :sid can be replaced with any valid Session ID for the account. This is used for Single Record Retrieval. |