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

baseuri

first_touch

adwords_account_id

ppc_account_id

adwords_campaign_id

ppc_campaign_id

adwords_adgroup_id

ppc_adgroup_id

adwords_keyword_id

ppc_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 Header

Required

Value

Description

access_key

Yes

{your-access_key}

One of two keys provided by DialogTech required to authorize the Bid Management API for a specific account

secret_key

Yes

{your-secret_key}

The second of two keys provided by DialogTech required to authorize the Bid Management API for a specific account

Authorization

Yes*

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

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

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, where a call is on the system while connected to another party.

talk_start

The timestamp where a call on the system is connected to a second party.

talk_end

The timestamp where a call on the system is 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.

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 user's visit that matched the SourceTrak activity.

activity_type_id

The 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_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=googlebogo_campaign as opposed to st-t=google )*.

first_touch

The 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_title

The document title of the first page where the user was first attributed to a SourceTrak visit (e.g. "Sample Landing Page").

first_touch_domain

The domain of the location where the user was first attributed to a SourceTrak visit (e.g. www.mydomain.com).

landing_page

The first page where the user was first attributed to a SourceTrak visit, excluding the domain (e.g. /sample-landing-page).

last_touch

The 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_title

The 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_domain

The 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_timestamp

The timestamp when the last touch occurred.

conversion_page

The last page where the user was attributed to a visit before placing a phone call, excluding the domain (e.g. /sample-conversion-page).

referrer

The domain where 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.

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.

ppc_account_id

The Google Ads account ID if available.

ppc_campaign_id

The Google Ads campaign ID if available.

ppc_campaign

The text name of the Google Ads campaign if available.

ppc_adgroup_id

The Google Ads ad group ID if available.

ppc_adgroup

The text name of the Google Ads ad group if available.

ppc_keyword_id

The Google Ads Keyword ID if available.

ppc_keywords

The text of Google Ads keywords if available.

ppc_status

Indicates 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_type

The Google Ads Match Type if available

Note: Match Type is not available for legacy Google Call Extensions.

ppc_ad_id

The Google Ads ad ID if available.

ppc_gclid

The Google Ads click id if available.

channel

The DialogTech tracked channel the call originated from. Either SourceTrak or Google Call Extensions.

custom_id

The value of the _st_custom_id variable used with SourceTrak from a website visitor.

custom_value

The value of the _st_custom_value variable used with SourceTrak from a website visitor.

os

The operating system of the SourceTrak visitor if applicable.

os_version

The operating system version of the SourceTrak visitor if applicable.

browser

The web browser of the SourceTrak visitor if applicable.

browser_version

The web browser version of the SourceTrak visitor if applicable.

location_id

The SourceTrak location ID if applicable.

call_duration

The duration of the phone call, rounded up to the next minute.

pid

Unique DialogTech assigned identifier for a SourceTrak visitor.

Additional Functions

Name

Endpoint

Description

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.