Publisher / Affiliate

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/2016-08-22/affiliates/transactions/33.csv
xml Returns an XML document with an array of Transaction elements. https://mynetwork.invoca.net/api/2016-08-22/affiliates/transactions/33.xml
json Returns a JSON array of transaction objects. https://mynetwork.invoca.net/api/2016-08-22/affiliates/transactions/33.json

Authentication

The API uses OAuth Authentication to authenticate that access is allowed. Pass the OAuth Token like any other query parameter, however, 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.
to= Ending date in user’s time zone, in format YYYY-MM-DD. Example: 2011-06-07. Inclusive.
limit= Max number of transactions to return at a time. Defaults to 1000. Limited to at most 4000.
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.
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. 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.

Example:

Send request 1:

https://yourcompany.invoca.net/api/2016-08-22/affiliates/transactions/706.csv?limit=500&oauth_token=<YOUR_OAUTH_TOKEN>&from=2015-03-26&to=2015-03-27

returns 500 rows, grab the last transaction_id (in this example 500) and send request 2:

https://yourcompany.invoca.net/api/2016-08-22/affiliates/transactions/706.csv?limit=500&oauth_token=<YOUR_OAUTH_TOKEN>U&from=2015-03-26&to=2015-03-27&start_after_transaction_id=500

then repeat as necessary to get all call records within date range.

Response

The data returned has the following fields:

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
call_result_description_detail Call Result Status of the transaction
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.
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

Optional Parameters

The following fields are optional based on your account type:

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

Example

For example, if you have this OAuth API token:

OAuth API token
YbcFHZ38FNfptfZMB0RZ6dk9dOJCaCfU

Here is an example using curl to get the next 20 transactions that occurred after transaction id C624DA2C-CF3367C3:

curl -k "https://mynetwork.invoca.net/affiliates/transactions/33.csv?limit=20&start_after_transaction_id=C624DA2C-CF3367C3&oauth_token=YbcFHZ38FNfptfZMB0RZ6dk9dOJCaCfU"

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

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

curl -k 'https://mynetwork.invoca.net/api/2016-08-22/affiliates/transactions/33.csv?transaction_type=Signal&from=2015-03-24&to=2015-03-27&oauth_token=YbcFH'

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

curl -k 'https://mynetwork.invoca.net/api/2016-08-22/affiliates/transactions/33.csv?transaction_type=PostCallEvent&from=2015-03-24&to=2015-03-27&oauth_token=YbcFH'

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

curl -k 'https://mynetwork.invoca.net/api/2016-08-22/affiliates/transactions/33.csv?transaction_type[]=Call&transaction_type[]=Signal&from=2015-03-24&to=2015-03-27&oauth_token=YbcFH'

Endpoint:

https://invoca.net/api/2016-08-22/affiliates/transactions/