{"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"],"_id":"558d9c33beb7c719007f631c","createdAt":"2015-06-26T18:38:43.154Z","project":"558d9c32beb7c719007f6319","releaseDate":"2015-06-26T18:38:43.153Z","__v":20},"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":"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.

API Security

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]

Request Header
Required
Value
Description

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.

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 /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

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*]

Response

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"
    }
]
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, 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

Additional Functions

Name
Endpoint
Description

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.