{"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"],"_id":"558d9c33beb7c719007f631c","createdAt":"2015-06-26T18:38:43.154Z","project":"558d9c32beb7c719007f6319","releaseDate":"2015-06-26T18:38:43.153Z","__v":19},"category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Partner Documentation","slug":"partner-documentation","order":7,"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}