{"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}
Bid Management API 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.
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]
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.
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 /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 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*]
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"
}
]
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=google_bogocampaign 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
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.