API & DOCS

My Account            

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.

📘

Base URI

https://api.ifbyphone.com/v2/user/bid-management

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 HeaderRequiredValueDescription
AuthorizationYesBearer TokenA token provided by DialogTech to authorize the Bid Management API for a specific account
Content-TypeNoapplication/jsonThough 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

ParameterDescription
&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"
    }
]
KeyValue
acct_idThe DialogTech Account ID
smart_minutesThe duration, in tenths of a minute, a call is on the system while not connected to another party.
date_addedDate and time the call was made.
talk_minutesThe duration, in tenths of a minute, a call is on the system while connected to another party.
talk_startThe timestamp a call on the system connected to a second party.
talk_endThe timestamp a call on the system disconnected from a second party.
dnisThe number dialed
aniCaller ID of the caller
first_nameFirst name of caller if reverse-lookup is enabled and data was found
last_nameLast name of caller if reverse-lookup is enabled and data was found
street_addressStreet address of caller if reverse-lookup is enabled and data was found
cityCity of caller if reverse-lookup is enabled and data was found
stateState of caller if reverse-lookup is enabled and data was found
zipcodeZipcode of caller if reverse-lookup is enabled and data was found
call_logging_idDeprecated - We do not advise collecting, logging, or leveraging this value. It should be null at all times.
sidUnique DialogTech assigned identifier for the call
rankA 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_termThe literal search string (keywords) that resulted in the display of a phone number on a website.
incoming_keywordProperty of the users visit that matched the SourceTrak activity
activity_type_idThe SourceTrak activity type by id which triggered DNI
url_tagThe 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=googlebogo_campaign as opposed to st-t=google )*
baseuriThe location where the user was first attributed to a visit.
last_touchThe location where the user was last attributed to a visit.
last_touch_timestampThe timestamp the last touch ocurred
referrerThe domain the visitor originated from
ip_addressThe IP address of the visitor
displayed_timestampThe timestamp the visitor was first shown a DNI number and tracking began
phone_numberDeprecated - 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_idAn ID associated with the visitor
pool_idThe ID of the pool the SourceTrak number originated from
domain_set_idThe ID of the domain set the SourceTrak visit is tracked from
activity_keywordThe URL tag from SourceTrak that caused the number to rotate (i.e. gclid= *)
phone_labelThe 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_idThe Google Adwords Account ID if available
adwords_campaign_idThe Google Adwords Campaign ID if available
adwords_adgroup_idThe Google Adwords Adgroup ID if available
adwords_keyword_idThe Google Adwords Keyword ID if available
channelThe DialogTech tracked channel the call originated from. Either SourceTrak or Call Extension

Additional Functions

NameEndpointDescription
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/countMakes a record count request.