{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","results":{"codes":[]},"settings":"","params":[]},"next":{"description":"","pages":[]},"title":"Bid Management API v3 Overview","type":"basic","slug":"bid-management-api-overview-v3","excerpt":"","body":"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.\n[block:callout]\n{\n \"type\": \"info\",\n \"title\": \"Base URI\",\n \"body\": \"https://api.dialogtech.com/v3/user/bid-management\"\n}\n[/block]\n\n[block:api-header]\n{\n \"title\": \"What's New in Bid Management API v3\"\n}\n[/block]\nVersion 3 of the Bid Management API includes several renamed parameters, deprecated parameters, and a variety of additional parameters.\n\n**Parameter Name Changes:**\n\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"/v2 parameter name\",\n \"h-1\": \"/v3 parameter name\",\n \"2-0\": \"adwords_campaign_id\",\n \"3-0\": \"adwords_adgroup_id\",\n \"4-0\": \"adwords_keyword_id\",\n \"2-1\": \"ppc_campaign_id\",\n \"3-1\": \"ppc_adgroup_id\",\n \"4-1\": \"ppc_keyword_id\",\n \"0-0\": \"baseuri\",\n \"0-1\": \"first_touch\",\n \"1-0\": \"adwords_account_id\",\n \"1-1\": \"ppc_account_id\"\n },\n \"cols\": 2,\n \"rows\": 5\n}\n[/block]\n**Deprecated Parameters:**\n\n * phone_number -- If the numbers associated with a call are required, please use `dnis` and `ani`\n * super_id\n * call_logging_id\n\n**Parameter Additions:**\n\n * first_touch_title\n * first_touch_domain\n * landing_page\n * last_touch_title\n * last_touch_domain\n * conversion_page\n * ppc_status\n * ppc_match_type\n * ppc_campaign\n * ppc_ad_group\n * ppc_keywords\n * ppc_ad_id\n * ppc_gclid\n * os\n * os_version\n * browser\n * browser_version\n * location_id\n * call_duration\n * pid\n[block:api-header]\n{\n \"title\": \"API Security\"\n}\n[/block]\nDialogTech'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.\n\nLegacy 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.\n\n[block:callout]\n{\n \"type\": \"warning\",\n \"body\": \"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 api:::at:::dialogtech.com.\",\n \"title\": \"NOTICE\"\n}\n[/block]\n\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Request Header\",\n \"h-1\": \"Required\",\n \"h-2\": \"Value\",\n \"h-3\": \"Description\",\n \"3-0\": \"Content-Type\",\n \"3-1\": \"No\",\n \"3-2\": \"**application/json**\",\n \"3-3\": \"Though this header is not required, we strongly suggest deliberately specifying the *application/json* Content-Type type for web-enabled applications using this API.\",\n \"0-0\": \"access_key\",\n \"0-1\": \"Yes\",\n \"0-2\": \"**{your-access_key}**\",\n \"1-0\": \"secret_key\",\n \"1-1\": \"Yes\",\n \"1-2\": \"**{your-secret_key}**\",\n \"2-0\": \"Authorization\",\n \"2-1\": \"Yes*\",\n \"2-2\": \"**Bearer {your-token}**\",\n \"2-3\": \"A token provided by DialogTech to authorize the Bid Management API for a specific account\\n\\n*Legacy users can authorize using their Bearer token instead of access_key and secret_key\",\n \"0-3\": \"One of two keys provided by DialogTech required to authorize the Bid Management API for a specific account\",\n \"1-3\": \"The second of two keys provided by DialogTech required to authorize the Bid Management API for a specific account\"\n },\n \"cols\": 4,\n \"rows\": 4\n}\n[/block]\n\n[block:api-header]\n{\n \"title\": \"Pagination\"\n}\n[/block]\nThere are 2 URL Parameters that can be used to leverage pagination within these APIs\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Parameter\",\n \"h-1\": \"Description\",\n \"0-0\": \"&start=\",\n \"1-0\": \"&rows=\",\n \"0-1\": \"Determines the record set of items returned.\",\n \"1-1\": \"Determines the amount of records returned in 1 request. Also defines the record set size when using the `start` parameter.\"\n },\n \"cols\": 2,\n \"rows\": 2\n}\n[/block]\n**Example Pagination Request/Response**\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"GET /v3/user/bid-management?rows=2&start=1\\nContent-Type: application/json\\naccess_key: abc123\\nsecret_key: xzy456\",\n \"language\": \"text\",\n \"name\": \"Pagination Request\"\n }\n ]\n}\n[/block]\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"Content-Range: 3-4/18\",\n \"language\": \"text\",\n \"name\": \"Pagination Response Headers\"\n }\n ]\n}\n[/block]\nIn 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.\n[block:api-header]\n{\n \"title\": \"Filtering\"\n}\n[/block]\nFiltering is available by use of a structured Querystring parameter.\n[block:callout]\n{\n \"type\": \"success\",\n \"title\": \"Best Practice\",\n \"body\": \"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](https://apidocs.dialogtech.com/docs/bid-management-api-overview#section-additional-functions)\"\n}\n[/block]\n\n[block:parameters]\n{\n \"data\": {\n \"0-0\": \"`q=`\",\n \"0-1\": \"URL parameter to represent the filtering query\",\n \"1-0\": \"`:`\",\n \"1-1\": \"Query operation delimiter\",\n \"2-0\": \"`[` and `]`\",\n \"2-1\": \"Inclusive range identifier\",\n \"3-0\": \"`,`\",\n \"3-1\": \"Deliminate Querystring parts\",\n \"4-0\": \"`inc_gce:1`\",\n \"4-1\": \"Return results for Google Call Extensions calls\"\n },\n \"cols\": 2,\n \"rows\": 5\n}\n[/block]\nThe following request is going to filter based on the `date_added` value.\n\n`date_added` Should be any calls on or between 2018-01-01 at 06:30 EST and 2018-01-01 18:00 EST.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"/v3/user/bid-management?q=date_added:[2018-01-01%2006:30:00%20TO%202018-01-01%2018:00:00]\",\n \"language\": \"text\",\n \"name\": \"Filtered Request\"\n }\n ]\n}\n[/block]\n\n[block:api-header]\n{\n \"title\": \"Response\"\n}\n[/block]\nThe response to this API will be demonstrated assuming the Content-Type from the request is application/json.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"[\\n {\\n \\\"acct_id\\\": \\\"12345\\\",\\n \\\"smart_minutes\\\": \\\"0.8\\\",\\n \\\"date_added\\\": \\\"2018-10-16 18:04:01\\\",\\n \\\"talk_minutes\\\": \\\"5.8\\\",\\n \\\"talk_start\\\": \\\"2018-10-16 18:04:49.0\\\",\\n \\\"talk_end\\\": \\\"2018-10-16 18:10:37.0\\\",\\n \\\"dnis\\\": \\\"5555555555\\\",\\n \\\"ani\\\": \\\"5551231234\\\",\\n \\\"first_name\\\": null,\\n \\\"last_name\\\": null,\\n \\\"street_address\\\": null,\\n \\\"city\\\": null,\\n \\\"state\\\": null,\\n \\\"zipcode\\\": null,\\n \\\"call_logging_id\\\": null,\\n \\\"sid\\\": \\\"181001008712111\\\",\\n \\\"rank\\\": \\\"2\\\",\\n \\\"search_term\\\": null,\\n \\\"incoming_keyword\\\": \\\"www.google.com\\\",\\n \\\"activity_type_id\\\": 2,\\n \\\"url_tag\\\": \\\"\\\",\\n \\\"first_touch\\\": \\\"https://www.mydomain.com/sample-landing-page\\\",\\n \\\"first_touch_title\\\": \\\"Company ABC | Sample Landing Page\\\",\\n \\\"first_touch_domain\\\": \\\"www.mydomain.com\\\",\\n \\\"landing_page\\\": \\\"/sample-landing-page\\\",\\n \\\"last_touch\\\": \\\"https://www.mydomain.com/sample-conversion-page\\\",\\n \\\"last_touch_title\\\": \\\"Company ABC | Sample Conversion Page\\\",\\n \\\"last_touch_domain\\\": \\\"www.mydomain.com\\\",\\n \\\"last_touch_timestamp\\\": \\\"2018-10-16 18:03:39\\\",\\n \\\"conversion_page\\\": \\\"/sample-conversion-page\\\",\\n \\\"referrer\\\": \\\"https://www.google.com/\\\",\\n \\\"ip_address\\\": \\\"111.11.11.111\\\",\\n \\\"displayed_timestamp\\\": \\\"2018-10-16 18:00:55\\\",\\n \\\"pool_id\\\": 12345,\\n \\\"domain_set_id\\\": 54321,\\n \\\"activity_keyword\\\": \\\"*google.com*\\\",\\n \\\"phone_label\\\": \\\"Website (Mobile) - Google Organic\\\",\\n \\\"vt_keyword\\\": null,\\n \\\"vt_matchtype\\\": null,\\n \\\"vt_network\\\": null,\\n \\\"vt_device\\\": null,\\n \\\"vt_devicemodel\\\": null,\\n \\\"vt_creative\\\": null,\\n \\\"vt_placement\\\": null,\\n \\\"vt_target\\\": null,\\n \\\"vt_param1\\\": null,\\n \\\"vt_param2\\\": null,\\n \\\"vt_random\\\": null,\\n \\\"vt_aceid\\\": null,\\n \\\"vt_adposition\\\": null,\\n \\\"vt_adwords_producttargetid\\\": null,\\n \\\"vt_adtype\\\": null,\\n \\\"recording\\\": null,\\n \\\"ppc_account_id\\\": null,\\n \\\"ppc_ad_id\\\": null,\\n \\\"ppc_campaign_id\\\": null,\\n \\\"ppc_campaign\\\": null,\\n \\\"ppc_adgroup_id\\\": null,\\n \\\"ppc_adgroup\\\": null,\\n \\\"ppc_keyword_id\\\": null,\\n \\\"ppc_keywords\\\": null,\\n \\\"ppc_status\\\": \\\"N/A\\\",\\n \\\"ppc_match_type\\\": null,\\n \\t\\\"ppc_gclid\\\": null,\\n \\\"channel\\\": \\\"SourceTrak\\\",\\n \\\"custom_id\\\": null,\\n \\\"custom_value\\\": null,\\n \\\"os\\\": \\\"Android\\\",\\n \\\"os_version\\\": \\\"7.1.2\\\",\\n \\\"browser\\\": \\\"Chrome Mobile\\\",\\n \\\"browser_version\\\": \\\"68.0.3550\\\",\\n \\\"location_id\\\": 98765,\\n \\\"call_duration\\\": \\\"7\\\",\\n \\\"pid\\\": \\\"783eefg0-c5c5-11e8-a81f-9b87d0e36788\\\"\\n }\\n]\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\n\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Key\",\n \"h-1\": \"Value\",\n \"0-0\": \"acct_id\",\n \"0-1\": \"The DialogTech Account ID.\",\n \"1-0\": \"smart_minutes\",\n \"1-1\": \"The duration, in tenths of a minute, a call is on the system while not connected to another party.\",\n \"2-0\": \"date_added\",\n \"2-1\": \"Date and time the call was made.\",\n \"3-0\": \"talk_minutes\",\n \"3-1\": \"The duration, in tenths of a minute, where a call is on the system while connected to another party.\",\n \"4-0\": \"talk_start\",\n \"4-1\": \"The timestamp where a call on the system is connected to a second party.\",\n \"5-0\": \"talk_end\",\n \"5-1\": \"The timestamp where a call on the system is disconnected from a second party.\",\n \"6-0\": \"dnis\",\n \"6-1\": \"The number dialed.\",\n \"7-0\": \"ani\",\n \"7-1\": \"Caller ID of the caller.\",\n \"8-0\": \"first_name\",\n \"8-1\": \"First name of caller if reverse-lookup is enabled and data was found.\",\n \"9-0\": \"last_name\",\n \"9-1\": \"Last name of caller if reverse-lookup is enabled and data was found.\",\n \"10-0\": \"street_address\",\n \"10-1\": \"Street address of caller if reverse-lookup is enabled and data was found.\",\n \"11-0\": \"city\",\n \"11-1\": \"City of caller if reverse-lookup is enabled and data was found.\",\n \"12-0\": \"state\",\n \"12-1\": \"State of caller if reverse-lookup is enabled and data was found.\",\n \"13-0\": \"zipcode\",\n \"13-1\": \"Zipcode of caller if reverse-lookup is enabled and data was found.\",\n \"14-0\": \"sid\",\n \"14-1\": \"Unique DialogTech assigned identifier for the call.\",\n \"15-0\": \"rank\",\n \"15-1\": \"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.\",\n \"16-0\": \"search_term\",\n \"16-1\": \"The literal search string (keywords) that resulted in the display of a phone number on a website.\",\n \"17-0\": \"incoming_keyword\",\n \"17-1\": \"Property of the user's visit that matched the SourceTrak activity.\",\n \"18-0\": \"activity_type_id\",\n \"18-1\": \"The SourceTrak activity type by id which triggered DNI:\\n\\n1 - Direct Default\\n2 - Referrer Domain\\n3 - Tagged URL\\n4 - Organic Search Keyword\\n5 - All Organic Search\\n6 - Url Path\\n7 - Custom Tagged URL\\n8 - Direct Visit\",\n \"19-0\": \"url_tag\",\n \"19-1\": \"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=google_bogo_campaign as opposed to st-t=google_ *)*.\",\n \"20-0\": \"first_touch\",\n \"20-1\": \"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).\",\n \"24-0\": \"last_touch\",\n \"24-1\": \"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).\",\n \"29-0\": \"referrer\",\n \"29-1\": \"The domain where the visitor originated from.\",\n \"30-0\": \"ip_address\",\n \"30-1\": \"The IP address of the visitor.\",\n \"31-0\": \"displayed_timestamp\",\n \"31-1\": \"The timestamp the visitor was first shown a DNI number and tracking began.\",\n \"32-0\": \"pool_id\",\n \"32-1\": \"The ID of the pool the SourceTrak number originated from.\",\n \"33-0\": \"domain_set_id\",\n \"33-1\": \"The ID of the domain set the SourceTrak visit is tracked from.\",\n \"34-0\": \"activity_keyword\",\n \"34-1\": \"The URL tag from SourceTrak that caused the number to rotate _(i.e. gclid= *)_.\",\n \"35-0\": \"phone_label\",\n \"35-1\": \"The label assigned to the phone number.\",\n \"36-0\": \"vt_keyword\\nvt_matchtype\\nvt_network\\nvt_device\\nvt_devicemodel\\nvt_creative\\nvt_placement\\nvt_target\\nvt_param1\\nvt_param2\\nvt_random\\nvt_aceid\\nvt_adposition\\nvt_adtype\",\n \"36-1\": \"Please refer to the [ValueTrack Parameters](https://apidocs.dialogtech.com/v1.0/docs/call-detail-report#section-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.\",\n \"37-0\": \"ppc_account_id\",\n \"37-1\": \"The Google Ads account ID if available.\",\n \"40-0\": \"ppc_adgroup_id\",\n \"40-1\": \"The Google Ads ad group ID if available.\",\n \"48-0\": \"channel\",\n \"48-1\": \"The DialogTech tracked channel the call originated from. Either `SourceTrak` or `Google Call Extensions`.\",\n \"38-0\": \"ppc_campaign_id\",\n \"42-0\": \"ppc_keyword_id\",\n \"38-1\": \"The Google Ads campaign ID if available.\",\n \"42-1\": \"The Google Ads Keyword ID if available.\",\n \"44-0\": \"ppc_status\",\n \"44-1\": \"Indicates the state of processing for Google Call Extension calls and SourceTrak calls when the first touch includes a Google Click ID (gclid).\\n\\nPossible values include:\\n`Not Processed`\\n`Waiting For Keyword`\\n`Processed`\\n`Desktop`\\n`No Match`\\n`N/A` (SourceTrak call with no GCLID)\",\n \"49-0\": \"custom_id\",\n \"50-0\": \"custom_value\",\n \"45-0\": \"ppc_match_type\",\n \"45-1\": \"The Google Ads Match Type if available\\n\\nNote: Match Type is not available for legacy Google Call Extensions.\",\n \"49-1\": \"The value of the _st_custom_id variable used with SourceTrak from a website visitor.\",\n \"50-1\": \"The value of the _st_custom_value variable used with SourceTrak from a website visitor.\",\n \"39-0\": \"ppc_campaign\",\n \"39-1\": \"The text name of the Google Ads campaign if available.\",\n \"41-0\": \"ppc_adgroup\",\n \"41-1\": \"The text name of the Google Ads ad group if available.\",\n \"43-0\": \"ppc_keywords\",\n \"43-1\": \"The text of Google Ads keywords if available.\",\n \"46-0\": \"ppc_ad_id\",\n \"46-1\": \"The Google Ads ad ID if available.\",\n \"51-0\": \"os\",\n \"51-1\": \"The operating system of the SourceTrak visitor if applicable.\",\n \"52-0\": \"os_version\",\n \"52-1\": \"The operating system version of the SourceTrak visitor if applicable.\",\n \"53-0\": \"browser\",\n \"53-1\": \"The web browser of the SourceTrak visitor if applicable.\",\n \"54-0\": \"browser_version\",\n \"54-1\": \"The web browser version of the SourceTrak visitor if applicable.\",\n \"55-0\": \"location_id\",\n \"55-1\": \"The SourceTrak location ID if applicable.\",\n \"56-0\": \"call_duration\",\n \"56-1\": \"The duration of the phone call, rounded up to the next minute.\",\n \"57-0\": \"pid\",\n \"21-0\": \"first_touch_title\",\n \"22-0\": \"first_touch_domain\",\n \"23-0\": \"landing_page\",\n \"27-0\": \"last_touch_timestamp\",\n \"27-1\": \"The timestamp when the last touch occurred.\",\n \"25-0\": \"last_touch_title\",\n \"26-0\": \"last_touch_domain\",\n \"28-0\": \"conversion_page\",\n \"57-1\": \"Unique DialogTech assigned identifier for a SourceTrak visitor.\",\n \"21-1\": \"The document title of the first page where the user was first attributed to a SourceTrak visit (e.g. \\\"Sample Landing Page\\\").\",\n \"22-1\": \"The domain of the location where the user was first attributed to a SourceTrak visit (e.g. www.mydomain.com).\",\n \"23-1\": \"The first page where the user was first attributed to a SourceTrak visit, excluding the domain (e.g. /sample-landing-page).\",\n \"25-1\": \"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\\\".\",\n \"26-1\": \"The domain of the last location where the user was attributed to a visit before placing a phone call (e.g. www.mydomain.com).\",\n \"28-1\": \"The last page where the user was attributed to a visit before placing a phone call, excluding the domain (e.g. /sample-conversion-page).\",\n \"47-0\": \"ppc_gclid\",\n \"47-1\": \"The Google Ads click id if available.\"\n },\n \"cols\": 2,\n \"rows\": 58\n}\n[/block]\n\n[block:api-header]\n{\n \"title\": \"Additional Functions\"\n}\n[/block]\n\n[block:parameters]\n{\n \"data\": {\n \"0-0\": \"Single Sid Request\",\n \"h-0\": \"Name\",\n \"h-1\": \"Endpoint\",\n \"0-1\": \"/v3/user/bid-management/:sid\",\n \"h-2\": \"Description\",\n \"0-2\": \"**:sid** can be replaced with any valid Session ID for the account. This is used for Single Record Retrieval.\"\n },\n \"cols\": 3,\n \"rows\": 1\n}\n[/block]","updates":["5bb7b69a08f9550003f359e4"],"order":1,"isReference":false,"hidden":true,"sync_unique":"","link_url":"","link_external":false,"_id":"5b802dfa2ff2bf0003441eb4","project":"558d9c32beb7c719007f6319","version":{"version":"1.0","version_clean":"1.0.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["558d9c33beb7c719007f631d","558db0bc7afc102f008ed863","558db0d07afc102f008ed864","558db3c84cd25f0d00b7ecb2","558dbace7afc102f008ed894","558dbd104cd25f0d00b7ecca","558dbd4c4cd25f0d00b7eccb","559d3e858639bd21008e90a6","55bb8ca5a8400c2d00873e70","58fdfb438fbd2819000db9eb","590829c7ade4172d006a87b8","59082a11beedcf0f00235d87","5908bd2cba2afd23007d6d12","5908d1f64f544425002b6aae","591e5e9e2c1b1f0f000fa4e5","5a283434aba91f002834ea86","5a69fe5cde745d002c936c66","5a81e6ef761cf300127317f8","5a81e7d63b1e120012bed5a1","5f6cf225ba56a40011bff62d","5f970e8b7617eb041ae758bb","602adb88243fbc0056918566","602adbb91828a600535980c4"],"_id":"558d9c33beb7c719007f631c","createdAt":"2015-06-26T18:38:43.154Z","project":"558d9c32beb7c719007f6319","releaseDate":"2015-06-26T18:38:43.153Z","__v":23},"category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Partner Documentation","slug":"partner-documentation","order":11,"from_sync":false,"reference":false,"_id":"5a283434aba91f002834ea86","project":"558d9c32beb7c719007f6319","version":"558d9c33beb7c719007f631c","createdAt":"2017-12-06T18:17:24.447Z","__v":0},"user":"570eaa3cd6c6f00e00b98606","createdAt":"2018-08-24T16:10:34.762Z","__v":1,"parentDoc":null}
Bid Management API v3 Overview
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.
Version 3 of the Bid Management API includes several renamed parameters, deprecated parameters, and a variety of additional parameters.
Parameter Name Changes:
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
dnis
andani
- 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
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]
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.
There are 2 URL Parameters that can be used to leverage pagination within these APIs
&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 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]
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"
}
]
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=google_bogocampaign 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 Processed
Waiting For Keyword
Processed
Desktop
No Match
N/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.
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.