{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","settings":"","results":{"codes":[]},"params":[]},"next":{"description":"","pages":[]},"title":"Bid Management API Overview","type":"basic","slug":"bid-management-api-overview","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.ifbyphone.com/v2/user/bid-management\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"API Security\"\n}\n[/block]\nDialogTech'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.\n\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"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 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    \"0-0\": \"Authorization\",\n    \"0-1\": \"Yes\",\n    \"h-3\": \"Description\",\n    \"0-2\": \"**Bearer _Token_**\",\n    \"0-3\": \"A token provided by DialogTech to authorize the Bid Management API for a specific account\",\n    \"1-0\": \"Content-Type\",\n    \"1-1\": \"No\",\n    \"1-2\": \"**application/json**\",\n    \"1-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  },\n  \"cols\": 4,\n  \"rows\": 2\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 /v2/user/bid-management?rows=2&start=1\\nContent-Type: application/json\\nAuthorization: Bearer 12345abcde\",\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 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 request 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\": \"`{` and `}`\",\n    \"3-1\": \"Exclusive Range Identifier\",\n    \"4-0\": \"`,`\",\n    \"4-1\": \"Deliminate Querystring Parts\"\n  },\n  \"cols\": 2,\n  \"rows\": 5\n}\n[/block]\nThe following request is going to filter based on the `date_added` value, and the `talk_minutes` value.\n\n`date_added` Should be any calls on or after 2017-01-01 at 06:30 EST, but before 2017-01-01 18:00 EST.\n`talk_minutes` Should be greater than or equal to 0.5 minutes.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/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*]\",\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\\\": \\\"55555\\\",\\n        \\\"smart_minutes\\\": \\\"0.1\\\",\\n        \\\"date_added\\\": \\\"2017-12-01 16:38:13\\\",\\n        \\\"talk_minutes\\\": \\\"0.0\\\",\\n        \\\"talk_start\\\": \\\"2017-12-01 16:38:19.0\\\",\\n        \\\"talk_end\\\": \\\"2017-12-01 16:38:19.0\\\",\\n        \\\"dnis\\\": \\\"5556667777\\\",\\n        \\\"ani\\\": \\\"8887776666\\\",\\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\\\": \\\"1712010011223344\\\",\\n        \\\"rank\\\": \\\"1\\\",\\n        \\\"search_term\\\": null,\\n        \\\"incoming_keyword\\\": \\\"tag\\\",\\n        \\\"activity_type_id\\\": 3,\\n        \\\"url_tag\\\": \\\"tag\\\",\\n        \\\"baseuri\\\": \\\"http://www.example.com/?st-t=tag\\\",\\n        \\\"last_touch\\\": null,\\n        \\\"last_touch_timestamp\\\": null,\\n        \\\"referrer\\\": \\\"\\\",\\n        \\\"ip_address\\\": \\\"127.0.0.1\\\",\\n        \\\"displayed_timestamp\\\": \\\"2017-12-01 16:29:21\\\",\\n        \\\"phone_number\\\": \\\"\\\",\\n        \\\"super_id\\\": null,\\n        \\\"pool_id\\\": 00000,\\n        \\\"domain_set_id\\\": 00000,\\n        \\\"activity_keyword\\\": \\\"tag\\\",\\n        \\\"phone_label\\\": null,\\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        \\\"adwords_account_id\\\": null,\\n        \\\"adwords_campaign_id\\\": null,\\n        \\\"adwords_adgroup_id\\\": null,\\n        \\\"adwords_keyword_id\\\": null,\\n        \\\"channel\\\": \\\"SourceTrak\\\"\\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, a call is on the system while connected to another party.\",\n    \"4-0\": \"talk_start\",\n    \"4-1\": \"The timestamp a call on the system connected to a second party.\",\n    \"5-0\": \"talk_end\",\n    \"5-1\": \"The timestamp a call on the system 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\": \"call_logging_id\",\n    \"14-1\": \"_Deprecated_ - We do not advise collecting, logging, or leveraging this value. It should be `null` at all times.\",\n    \"15-0\": \"sid\",\n    \"15-1\": \"Unique DialogTech assigned identifier for the call\",\n    \"16-0\": \"rank\",\n    \"16-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    \"17-0\": \"search_term\",\n    \"17-1\": \"The literal search string (keywords) that resulted in the display of a phone number on a website.\",\n    \"18-0\": \"incoming_keyword\",\n    \"18-1\": \"Property of the users visit that matched the SourceTrak activity\",\n    \"19-0\": \"activity_type_id\",\n    \"19-1\": \"The SourceTrak activity type by id which triggered DNI\",\n    \"20-0\": \"url_tag\",\n    \"20-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    \"21-0\": \"baseuri\",\n    \"21-1\": \"The location where the user was first attributed to a visit.\",\n    \"22-0\": \"last_touch\",\n    \"22-1\": \"The location where the user was last attributed to a visit.\",\n    \"23-0\": \"last_touch_timestamp\",\n    \"23-1\": \"The timestamp the last touch ocurred\",\n    \"24-0\": \"referrer\",\n    \"24-1\": \"The domain the visitor originated from\",\n    \"25-0\": \"ip_address\",\n    \"25-1\": \"The IP address of the visitor\",\n    \"26-0\": \"displayed_timestamp\",\n    \"26-1\": \"The timestamp the visitor was first shown a DNI number and tracking began\",\n    \"27-0\": \"phone_number\",\n    \"27-1\": \"_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`\",\n    \"28-0\": \"super_id\",\n    \"28-1\": \"An ID associated with the visitor\",\n    \"29-0\": \"pool_id\",\n    \"29-1\": \"The ID of the pool the SourceTrak number originated from\",\n    \"30-0\": \"domain_set_id\",\n    \"30-1\": \"The ID of the domain set the SourceTrak visit is tracked from\",\n    \"31-0\": \"activity_keyword\",\n    \"31-1\": \"The URL tag from SourceTrak that caused the number to rotate _(i.e. gclid= *)_\",\n    \"32-0\": \"phone_label\",\n    \"32-1\": \"The label assigned to the phone number\",\n    \"33-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    \"33-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    \"34-0\": \"adwords_account_id\",\n    \"34-1\": \"The Google Adwords Account ID if available\",\n    \"36-0\": \"adwords_adgroup_id\",\n    \"36-1\": \"The Google Adwords Adgroup ID if available\",\n    \"38-0\": \"channel\",\n    \"38-1\": \"The DialogTech tracked channel the call originated from. Either `SourceTrak` or `Call Extension`\",\n    \"35-0\": \"adwords_campaign_id\",\n    \"37-0\": \"adwords_keyword_id\",\n    \"35-1\": \"The Google Adwords Campaign ID if available\",\n    \"37-1\": \"The Google Adwords Keyword ID if available\"\n  },\n  \"cols\": 2,\n  \"rows\": 39\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\": \"/v2/user/bid-management/:sid\",\n    \"1-0\": \"Count Request\",\n    \"1-1\": \"/v2/user/bid-management/count\",\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    \"1-2\": \"Makes a record count request.\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]","updates":[],"order":0,"isReference":false,"hidden":true,"sync_unique":"","link_url":"","link_external":false,"_id":"5a2855f92bb42100124e04a3","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":"58cadf93d223510f005d27db","createdAt":"2017-12-06T20:41:29.330Z","githubsync":"","__v":0,"parentDoc":null}