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.dialogtech.com/v3/user/bid-management

What's New in Bid Management API v3

Version 3 of the Bid Management API includes several renamed parameters, deprecated parameters, and a variety of additional parameters.

Parameter Name Changes:

/v2 parameter name/v3 parameter name
baseurifirst_touch
adwords_account_idppc_account_id
adwords_campaign_idppc_campaign_id
adwords_adgroup_idppc_adgroup_id
adwords_keyword_idppc_keyword_id

Deprecated Parameters:

  • phone_number -- If the numbers associated with a call are required, please use dnis and ani
  • super_id
  • call_logging_id

Parameter Additions:

  • first_touch_title
  • first_touch_domain
  • landing_page
  • last_touch_title
  • last_touch_domain
  • conversion_page
  • ppc_status
  • ppc_match_type
  • ppc_campaign
  • ppc_ad_group
  • ppc_keywords
  • ppc_ad_id
  • ppc_gclid
  • os
  • os_version
  • browser
  • browser_version
  • location_id
  • call_duration
  • pid

API Security

DialogTech'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.

Legacy 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.

🚧

NOTICE

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 [email protected]

Request HeaderRequiredValueDescription
access_keyYes{your-access_key}One of two keys provided by DialogTech required to authorize the Bid Management API for a specific account
secret_keyYes{your-secret_key}The second of two keys provided by DialogTech required to authorize the Bid Management API for a specific account
AuthorizationYes*Bearer {your-token}A token provided by DialogTech to authorize the Bid Management API for a specific account

*Legacy users can authorize using their Bearer token instead of access_key and secret_key
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 /v3/user/bid-management?rows=2&start=1
Content-Type: application/json
access_key: abc123
secret_key: xzy456
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 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 requesting 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
,Deliminate Querystring parts
inc_gce:1Return results for Google Call Extensions calls

The following request is going to filter based on the date_added value.

date_added Should be any calls on or between 2018-01-01 at 06:30 EST and 2018-01-01 18:00 EST.

/v3/user/bid-management?q=date_added:[2018-01-01%2006:30:00%20TO%202018-01-01%2018:00:00]

Response

The response to this API will be demonstrated assuming the Content-Type from the request is application/json.

[
    {
        "acct_id": "12345",
        "smart_minutes": "0.8",
        "date_added": "2018-10-16 18:04:01",
        "talk_minutes": "5.8",
        "talk_start": "2018-10-16 18:04:49.0",
        "talk_end": "2018-10-16 18:10:37.0",
        "dnis": "5555555555",
        "ani": "5551231234",
        "first_name": null,
        "last_name": null,
        "street_address": null,
        "city": null,
        "state": null,
        "zipcode": null,
        "call_logging_id": null,
        "sid": "181001008712111",
        "rank": "2",
        "search_term": null,
        "incoming_keyword": "www.google.com",
        "activity_type_id": 2,
        "url_tag": "",
        "first_touch": "https://www.mydomain.com/sample-landing-page",
        "first_touch_title": "Company ABC | Sample Landing Page",
        "first_touch_domain": "www.mydomain.com",
        "landing_page": "/sample-landing-page",
        "last_touch": "https://www.mydomain.com/sample-conversion-page",
        "last_touch_title": "Company ABC | Sample Conversion Page",
        "last_touch_domain": "www.mydomain.com",
        "last_touch_timestamp": "2018-10-16 18:03:39",
        "conversion_page": "/sample-conversion-page",
        "referrer": "https://www.google.com/",
        "ip_address": "111.11.11.111",
        "displayed_timestamp": "2018-10-16 18:00:55",
        "pool_id": 12345,
        "domain_set_id": 54321,
        "activity_keyword": "*google.com*",
        "phone_label": "Website (Mobile) - Google Organic",
        "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,
        "ppc_account_id": null,
        "ppc_ad_id": null,
        "ppc_campaign_id": null,
        "ppc_campaign": null,
        "ppc_adgroup_id": null,
        "ppc_adgroup": null,
        "ppc_keyword_id": null,
        "ppc_keywords": null,
        "ppc_status": "N/A",
        "ppc_match_type": null,
        "ppc_gclid": null,
        "channel": "SourceTrak",
        "custom_id": null,
        "custom_value": null,
        "os": "Android",
        "os_version": "7.1.2",
        "browser": "Chrome Mobile",
        "browser_version": "68.0.3550",
        "location_id": 98765,
        "call_duration": "7",
        "pid": "783eefg0-c5c5-11e8-a81f-9b87d0e36788"
    }
]
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, where a call is on the system while connected to another party.
talk_startThe timestamp where a call on the system is connected to a second party.
talk_endThe timestamp where a call on the system is 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.
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 user's visit that matched the SourceTrak activity.
activity_type_idThe SourceTrak activity type by id which triggered DNI:

1 - Direct Default
2 - Referrer Domain
3 - Tagged URL
4 - Organic Search Keyword
5 - All Organic Search
6 - Url Path
7 - Custom Tagged URL
8 - Direct Visit
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 )*.
first_touchThe full url of the page where the user was first attributed to a SourceTrak visit (e.g. https://www.mydomain.com/sample-landing-page).
first_touch_titleThe document title of the first page where the user was first attributed to a SourceTrak visit (e.g. "Sample Landing Page").
first_touch_domainThe domain of the location where the user was first attributed to a SourceTrak visit (e.g. www.mydomain.com).
landing_pageThe first page where the user was first attributed to a SourceTrak visit, excluding the domain (e.g. /sample-landing-page).
last_touchThe 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).
last_touch_titleThe document title of the last page where a user was attributed to a visit before placing a phone call (e.g. "Sample Conversion Page".
last_touch_domainThe domain of the last location where the user was attributed to a visit before placing a phone call (e.g. www.mydomain.com).
last_touch_timestampThe timestamp when the last touch occurred.
conversion_pageThe last page where the user was attributed to a visit before placing a phone call, excluding the domain (e.g. /sample-conversion-page).
referrerThe domain where 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.
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.
ppc_account_idThe Google Ads account ID if available.
ppc_campaign_idThe Google Ads campaign ID if available.
ppc_campaignThe text name of the Google Ads campaign if available.
ppc_adgroup_idThe Google Ads ad group ID if available.
ppc_adgroupThe text name of the Google Ads ad group if available.
ppc_keyword_idThe Google Ads Keyword ID if available.
ppc_keywordsThe text of Google Ads keywords if available.
ppc_statusIndicates the state of processing for Google Call Extension calls and SourceTrak calls when the first touch includes a Google Click ID (gclid).

Possible values include:
Not Processed
Waiting For Keyword
Processed
Desktop
No Match
N/A (SourceTrak call with no GCLID)
ppc_match_typeThe Google Ads Match Type if available

Note: Match Type is not available for legacy Google Call Extensions.
ppc_ad_idThe Google Ads ad ID if available.
ppc_gclidThe Google Ads click id if available.
channelThe DialogTech tracked channel the call originated from. Either SourceTrak or Google Call Extensions.
custom_idThe value of the _st_custom_id variable used with SourceTrak from a website visitor.
custom_valueThe value of the _st_custom_value variable used with SourceTrak from a website visitor.
osThe operating system of the SourceTrak visitor if applicable.
os_versionThe operating system version of the SourceTrak visitor if applicable.
browserThe web browser of the SourceTrak visitor if applicable.
browser_versionThe web browser version of the SourceTrak visitor if applicable.
location_idThe SourceTrak location ID if applicable.
call_durationThe duration of the phone call, rounded up to the next minute.
pidUnique DialogTech assigned identifier for a SourceTrak visitor.

Additional Functions

NameEndpointDescription
Single Sid Request/v3/user/bid-management/:sid:sid can be replaced with any valid Session ID for the account. This is used for Single Record Retrieval.