Publisher / Affiliate

Signal Transactions Rollup

If you're upgrading from API versions older than 2020-10-01 we suggest testing to familiarize yourself with the updated Signal data structure.

For more information, view the support documentation for best practices in accessing Invoca Call Data via the Transactions API.

URL

The API follows REST conventions. Perform an HTTPS GET to the URL with the format in which you’d like to receive data. The following response formats are supported, where 33 is the affiliate id.

Format

Description and URL

csv

Comma-Separated Values, or really Anything-Separated Values (see column_separator= below). Returns an optional header row followed by one row for each transaction, with delimited values for each row. https://mynetwork.invoca.net/api/2020-10-01/affiliates/transactions/33.csv

xml

Returns an XML document with an array of Transaction elements. https://mynetwork.invoca.net/api/2020-10-01/affiliates/transactions/33.xml

json

Returns a JSON array of transaction objects. https://mynetwork.invoca.net/api/2020-10-01/affiliates/transactions/33.json

Authentication

The API uses OAuth to validate access. The OAuth Token can be passed in two ways. The first way is to pass the OAuth Token in the header of the request. The second is to pass the OAuth Token like any other query parameter. Please note that the OAuth Token is a required parameter. OAuth Tokens may be generated from the Manage API Credentials page.

Query Parameters

The API takes the following optional query parameters:

Parameter

Description

from=

Starting date in user’s time zone, in format YYYY-MM-DD. Example: 2011-06-01. Inclusive. Note: When using from and to params, transactions are returned based on the associated call start time.

to=

Ending date in user’s time zone, in format YYYY-MM-DD. Example: 2011-06-07. Inclusive. Note: When using from and to params, transactions are returned based on the associated call start time.

limit=

Max number of transactions to return at a time. Defaults to 1000. Limited to at most 4000.

transaction_id=

A specific transaction. If transaction_id is specified and no transaction with that ID is found, nothing will be returned. Returns at most 1 transaction.

call_record_id=

All transactions belonging to a specific call. If call_record_id is specified and no call with that ID is found, nothing will be returned. Returns all transactions belonging to the call record. Note: If transaction_id and call_record_id are passed, the specified transaction must belong to the specified call. If it does, the transaction will be returned. If it does not, nothing will be returned.

start_after_transaction_id=

Transaction_id to start retrieving after. This should be the last value retrieved previously. Default (or empty string) means start at the oldest.

include_columns=

comma-separated list of field names to be returned in the response for each transaction (if not specified, all available fields for the account will be returned, minus any columns in exclude_columns)

exclude_columns=

comma-separated list of field names to be excluded in the response for each transaction

column_separator=

[.csv format only] Separator between columns. Default is , for comma-separated values. (Can be set to any other separator like | for pipe-separated values or %09 for tab-separated values.)

row_separator=

[.csv format only] Separator between lines. Defaults to %0A for n (line feed). Use %0D%0A for rn (carriage return + line feed).

include_header=

[.csv format only] 1 to include a header row; 0 to omit the header row. Default is 1.

force_quotes=

[.csv format only] 1 to quote all CSV fields; 0 to only quote fields that contain separators. Default is 0.

transaction_type=

Filters for the type of transaction. Valid inputs are Call, PostCallEvent, Sale, or Signal. Sale maps to the Reported Conversion type.

In order to ensure that all transactions are returned when using the from= and to= date query parameters, you should store the last transaction id you have downloaded and pass it as the start_after_transaction_id to the next request so long as you do not change the date range. Once you update the date range, the best practice is to omit the start_after_transaction_id param for the first request, then use the last transaction id you have downloaded until the date range is complete. This is because using from and to params sorts transactions in relation to the call start time, not the transaction time. Typical usage on the polling interval is to repeatedly call the API until no rows are returned, meaning you have downloaded all transactions. Please note, the “to” and “from” date range parameters are both necessary, providing only one or the other will not filter the results.

We provide a helpful constant that can be used in the include_columns and exclude_columns options:

$invoca_default_columns represents the default set of columns provided by the Transactions API for your requested version

Response

General Parameters

Field

Name in Reports

Description

advertiser_campaign_id

Advertiser Campaign ID (Invoca ID)

The Invoca identifier of the campaign.

advertiser_campaign_id_from_network

Advertiser Campaign ID

The Campaign ID from the network as set on the advertiser campaign.

advertiser_campaign_name

Advertiser Campaign

Name of the campaign.

advertiser_id

Advertiser ID (Invoca ID)

The Invoca identifier of the advertiser

advertiser_id_from_network

Advertiser ID

Advertiser ID from the network as set on the Invoca advertiser.

advertiser_name

Advertiser

Name of the advertiser.

affiliate_payout_localized

Earnings

Amount paid out to the affiliate (Summed total amount for the call for Signal Transactions Rollup)

call_result_description_detail

Call Result

Status of the transaction (For the call for Signal Transactions Rollup)

call_source_description

Source

Source of the transaction

city

City

City where transaction originated

complete_call_id

Call Record ID

Globally unique identifier for the call this transaction is part of. Up-to 32 character string, can contain alphanumeric characters (i.e. 0-9A-Z) and the -.

connect_duration

Connected Duration

Duration in seconds that the call that was connected to the call center.

corrected_at

Corrected At

[Correction only] Date and time the transaction was corrected, in user’s time zone, followed by offset from GMT.

corrects_transaction_id

Corrects Call

[Correction only] Id of the original transaction that this transaction updates. Values in this row are the corrected ones and should replace the original values. Same format as transaction_id. Up-to 32 character string, can contain alphanumeric characters (i.e. 0-9A-Z) and the -.

duration

Total Duration

Duration of the call in seconds. Includes any time spent in an IVR tree before transferring to the call center.

ivr_duration

IVR Duration

Duration in seconds that the call spent in the IVR tree.

keypress_1

Key 1

Name of the first key that was pressed

keypress_2

Key 2

Name of the second key that was pressed

keypress_3

Key 3

Name of the third key that was pressed

keypress_4

Key 4

Name of the fourth key that was pressed

keypresses

Keypresses

List of unique keynames that were pressed during the call

matching_affiliate_payout_policies

Matching Affiliate Payout Policies

List of affiliate policies that matched (base, bonus1, bonus2, etc.) to determine the affiliate payout, separated by +. For example, base+bonus2. Note that if there was any affiliate payout, this field guaranteed to start with base.

media_type

Media Type

Media type of the transaction source

mobile

Phone Type

Landline or Mobile or empty string if type is unknown

notes

Notes

Free-form notations on transaction

opt_in_SMS

Opt In Sms

Whether the caller opted in to receive an SMS promotion.

original_order_id

Order ID

[Sales reporting only] Id of the original transaction that this row is in reference to. Up-to 32 character string, can contain alphanumeric characters (i.e. 0-9A-Z) and the -.

payout_conditions

Payout Conditions

Base condition with { highlighting } around the term(s) that disqualified affiliate payout. For example: duration > 1 min and {in_region}

promo_line_description

Promo Number Description

Additional details about the transaction source

qualified_regions

Qualified Regions

The list of regions that that the caller matched

region

Region

Region (state, province or country) where transaction originated

start_time_local

Call Start Time

Start of the call in the API user’s time zone, followed by offset from GMT.

start_time_utc

Call Start Time (UTC timestamp)

Start of the call in milliseconds since Jan 1, 1970. Divide by 1000 to get Unix epoch time.

start_time_xml

Call Start Time (XML formatted)

Start of the call in Soap XML formatted time.

start_time_network_timezone

Call Start Time Network Timezone

Start of the call in the networks’s time zone, followed by offset from GMT.

start_time_network_timezone_xml

Call Start Time Network Timezone (XML formatted)

Start of the call in the network’s time zone in Soap XML formatted time.

syndicated_ident

Syndicated ID

The syndicated id for this call. Uniquely identifies syndication sources for a campaign.

transaction_id

Transaction ID

Globally unique identifier for this transaction. Up-to 32 character string, can contain alphanumeric characters (i.e. 0-9A-Z) and the -. This is the Primary Key of the results.

transaction_type

Type

The type of transaction - Call, Post Call Event, Reported Conversion, or Signal.

transfer_from_type

Transfer Type

Where the call came from

verified_zip

Verified Zip Code

Zip Code entered by callers when prompted during call treatment

virtual_line_id

Promo Number ID

The Promo Number ID from the network

RingPool Parameters

Field

Name in Reports

Description

dynamic_number_pool_id

Pool ID

The ID of the pool.

dynamic_number_pool_pool_type

Pool Type

The type of pool: Search, SearchKeyword or Custom

dynamic_number_pool_referrer_param1_name

Pool Param 1 Name

The name for parameter 1

dynamic_number_pool_referrer_param1_value

Pool Param 1 Value

The value for parameter 1

dynamic_number_pool_referrer_param2_name

Pool Param 2 Name

The name for parameter 2

dynamic_number_pool_referrer_param2_value

Pool Param 2 Value

The value for parameter 2

dynamic_number_pool_referrer_param3_name

Pool Param 3 Name

The name for parameter 3

dynamic_number_pool_referrer_param3_value

Pool Param 3 Value

The value for parameter 3

dynamic_number_pool_referrer_param4_name

Pool Param 4 Name

The name for parameter 4

dynamic_number_pool_referrer_param4_value

Pool Param 4 Value

The value for parameter 4

dynamic_number_pool_referrer_param5_name

Pool Param 5 Name

The name for parameter 5

dynamic_number_pool_referrer_param5_value

Pool Param 5 Value

The value for parameter 5

dynamic_number_pool_referrer_param6_name

Pool Param 6 Name

The name for parameter 6

dynamic_number_pool_referrer_param6_value

Pool Param 6 Value

The value for parameter 6

dynamic_number_pool_referrer_param7_name

Pool Param 7 Name

The name for parameter 7

dynamic_number_pool_referrer_param7_value

Pool Param 7 Value

The value for parameter 7

dynamic_number_pool_referrer_param8_name

Pool Param 8 Name

The name for parameter 8

dynamic_number_pool_referrer_param8_value

Pool Param 8 Value

The value for parameter 8

dynamic_number_pool_referrer_param9_name

Pool Param 9 Name

The name for parameter 9

dynamic_number_pool_referrer_param9_value

Pool Param 9 Value

The value for parameter 9

dynamic_number_pool_referrer_param10_name

Pool Param 10 Name

The name for parameter 10

dynamic_number_pool_referrer_param10_value

Pool Param 10 Value

The value for parameter 10

dynamic_number_pool_referrer_param11_name

Pool Param 11 Name

The name for parameter 11

dynamic_number_pool_referrer_param11_value

Pool Param 11 Value

The value for parameter 11

dynamic_number_pool_referrer_param12_name

Pool Param 12 Name

The name for parameter 12

dynamic_number_pool_referrer_param12_value

Pool Param 12 Value

The value for parameter 12

dynamic_number_pool_referrer_param13_name

Pool Param 13 Name

The name for parameter 13

dynamic_number_pool_referrer_param13_value

Pool Param 13 Value

The value for parameter 13

dynamic_number_pool_referrer_param14_name

Pool Param 14 Name

The name for parameter 14

dynamic_number_pool_referrer_param14_value

Pool Param 14 Value

The value for parameter 14

dynamic_number_pool_referrer_param15_name

Pool Param 15 Name

The name for parameter 15

dynamic_number_pool_referrer_param15_value

Pool Param 15 Value

The value for parameter 15

dynamic_number_pool_referrer_param16_name

Pool Param 16 Name

The name for parameter 16

dynamic_number_pool_referrer_param16_value

Pool Param 16 Value

The value for parameter 16

dynamic_number_pool_referrer_param17_name

Pool Param 17 Name

The name for parameter 17

dynamic_number_pool_referrer_param17_value

Pool Param 17 Value

The value for parameter 17

dynamic_number_pool_referrer_param18_name

Pool Param 18 Name

The name for parameter 18

dynamic_number_pool_referrer_param18_value

Pool Param 18 Value

The value for parameter 18

dynamic_number_pool_referrer_param19_name

Pool Param 19 Name

The name for parameter 19

dynamic_number_pool_referrer_param19_value

Pool Param 19 Value

The value for parameter 19

dynamic_number_pool_referrer_param20_name

Pool Param 20 Name

The name for parameter 20

dynamic_number_pool_referrer_param20_value

Pool Param 20 Value

The value for parameter 20

dynamic_number_pool_referrer_param21_name

Pool Param 21 Name

The name for parameter 21

dynamic_number_pool_referrer_param21_value

Pool Param 21 Value

The value for parameter 21

dynamic_number_pool_referrer_param22_name

Pool Param 22 Name

The name for parameter 22

dynamic_number_pool_referrer_param22_value

Pool Param 22 Value

The value for parameter 22

dynamic_number_pool_referrer_param23_name

Pool Param 23 Name

The name for parameter 23

dynamic_number_pool_referrer_param23_value

Pool Param 23 Value

The value for parameter 23

dynamic_number_pool_referrer_param24_name

Pool Param 24 Name

The name for parameter 24

dynamic_number_pool_referrer_param24_value

Pool Param 24 Value

The value for parameter 24

dynamic_number_pool_referrer_param25_name

Pool Param 25 Name

The name for parameter 25

dynamic_number_pool_referrer_param25_value

Pool Param 25 Value

The value for parameter 25

dynamic_number_pool_referrer_search_engine

Traffic Source

Search engine used.

dynamic_number_pool_referrer_search_keywords

Keywords

Search keywords used

dynamic_number_pool_referrer_search_type

Search Type

Paid or Organic.

Additional Feature Parameters

Field

Name in Reports

Description

signal_name

Signal Name

The name describing the signal event. (Merged results for the call for Signal Transactions Rollup)

external_data

External Data

Additional data associated with the transaction

recording

Recording

URL to the call recording, if available

calling_phone_number

Caller ID

Caller ID. Formatted as 12 characters like 866-555-1234

repeat_calling_phone_number

Repeat Caller

Whether the call was a repeat call. Repeat call detection is not applied to shared or unavailable caller ids.

real_time_response

Real Time Routing Response

Response information returned to Invoca when using the real-time routing webhook.

Examples

These examples use CURL, and are using the following fake OAuth API token:

OAuth API token

YbcFH

Note: the -k option asks curl to not bother checking the SSL certificate authority chain as that requires extra configuration.

Example 1: Get the next 20 transactions that occurred after transaction id C624DA2C-CF3367C3:

curl -k -H 'Authorization: <token>' 'https://mynetwork.invoca.net/api/2020-10-01/affiliates/transactions/33.csv?limit=20&start_after_transaction_id=C624DA2C-CF3367C3'

Example 2: Get 50 rows from a specific time period with only the transaction_id and duration columns:

curl -k -H 'Authorization: <token>' 'https://mynetwork.invoca.net/api/2020-10-01/affiliates/transactions/33.csv?limit=50&include_columns=transaction_id,duration&from=2015-03-26&to=2015-03-27'

Example 3: Get 50 rows that exclude a few columns such as city and region:

curl -k -H 'Authorization: <token>' 'https://mynetwork.invoca.net/api/2020-10-01/affiliates/transactions/33.csv?limit=50&exclude_columns=city,region&start_after_transaction_id=C624DA2C-CF3367C3'

Example 4: Get All Transactions from a specific time period that are of transaction_type Signal:

curl -k -H 'Authorization: <token>' 'https://mynetwork.invoca.net/api/2020-10-01/affiliates/transactions/33.csv?transaction_type=Signal&from=2015-03-24&to=2015-03-27'

Example 5: Get All Transactions from a specific time period that are of transaction_type Post Call Event:

curl -k -H 'Authorization: <token>' 'https://mynetwork.invoca.net/api/2020-10-01/affiliates/transactions/33.csv?transaction_type=PostCallEvent&from=2015-03-24&to=2015-03-27'

Example 6: Get All Transactions from a specific time period that are of transaction_type Call and Signal:

curl -k -H 'Authorization: <token>' 'https://mynetwork.invoca.net/api/2020-10-01/affiliates/transactions/33.csv?transaction_type[]=Call&transaction_type[]=Signal&from=2015-03-24&to=2015-03-27'

Endpoint:

https://invoca.net/api/2020-10-01/affiliates/transactions/<affiliate_id>.<format>