How to access Invoca call data programmatically (via Transactions API)

[stevestormoen]

The transactional data from your Invoca account — such as phone calls, signals, or sales — can be exported automatically using the Invoca Transactions API. Exporting this data is useful for situations such as developing your own in-house reports, or connecting to an external system such as your financial or CRM platform.

The Transactions API is an advanced feature, requiring coding experience or developer resources. Developer documentation for the Transactions API is available here, along with these authentication steps to access the Invoca APIs. 
 

Note:
To learn more about pushing transaction data to other systems, as opposed to polling that data, please see our guide Basic Knowledge: Invoca webhooks. 

Frequently asked questions

How frequently should the Transactions API be polled?

The Transactions API is designed to be polled at any interval over 5 minutes. You should store the last transaction ID you have downloaded in order to pass it as the ‘start_after_transaction_id’ with the next request. If your polling interval is longer, or transaction volume is high enough, not all rows will be returned in one request — however, you can set up your polling interval to keep calling the API until you have downloaded all transactions. 


How do I know I have downloaded all transactions?

When the number of transactions that the API returns is less than the row limit you have established in your API calls. You can use the “limit” query parameter in your API calls to determine how many transactions you would like the API to return on each call. If you do not specify the limit in your API call, it will default to 1,000 transactions. The maximum number of transactions that can be returned in a single call is 4,000.


How often does the Transactions API update?

Once a phone call processed by Invoca has completed, the transaction record is written and is immediately available via the Transactions API. This also holds true for Invoca reports viewed in the platform UI.


Why do transaction corrections occur and how are they returned when querying the Transactions API?

Corrections to a transaction can occur for a variety of reasons, some of the most common include: 

• Additional data being appended to a completed call or updated Signal values
• Notes being added to a call transaction
• Changes to pay-in or payout amounts for affiliate-driven calls

Corrections will also appear different in your Transactions API responses than they will in the Transactions Report in your Invoca account. Calls to your Transactions API will return several rows for a corrected call (1 for the original call and 1 for each correction that has been made to it), but the Transactions Report will show only 1 call transaction that has been updated with the corrected values.

If an existing transaction is corrected, the correction will appear as a new transaction that refers to the original through the ‘corrects_transaction_id’ field. When you receive a correction, replace the original transaction’s attributes with the new attributes from the correction. When query parameters are used to call the Transactions API, such as the ‘from=’ and ‘to=’ date query parameters, call corrections will be included (if they have occurred). 


When a correction has taken place, how do I know which transaction has the most up-to-date information?

The most recent transaction returned has the aggregate corrected data set. When you receive a correction, replace the original transaction’s attributes with the new attributes from the correction.
 

Note:
Duration-related parameters are cleared out on previous transactions to prevent incorrect aggregation of call durations.

How many different types of transactions do I need to account for?

Depending on the version of Transactions API used in your Invoca account, you’ll see different types in your Transactions API. The Transactions API may return the following transaction types:

• Call: a phone call received in your Invoca account
• Signal (old version only): a transaction generated by a Signal being applied to a call
• Sale (old version only): a transaction generated by a reported conversion (used for performance-driven use cases)
• Post-call event (new version only): any event that adds data to a call that has already been completed, via API or via Signal file upload.

If your Invoca account uses an older version of the Transactions API, each Signal and Sale transaction will appear as separate transaction rows from the original Call transaction, providing additional insights into what took place on the call. These Signal and Sale transactions may be linked to the original call via the ‘complete_call_id’ parameter. 

If you have a newer version of the Transactions API, all Signals and Sale data will be included together with the call or post-call event that initiated your transaction in the same row. For example, if you receive a phone call in your Invoca account which captures two keypress-type Signals immediately, your Transactions API will report one “call” transaction, with the data for those two keypress Signals included. 

After that same call, if your Signal AI recognizes three more AI Signals occurred during your call, your Transactions API will report a correction transaction updating the previous call record to add values for all three AI Signals. Later if a Signal File Upload is performed targeting that same call and adding four additional signals, your Transactions API will report a new "post-call event" transaction with the four Signals included. This transaction may be linked to the original call via the 'complete_call_id' parameter.


How can I identify all the transactions that make up a specific call?

The ‘complete_call_id’ parameter returned by the Transactions API (labeled the ‘Call Record ID’ in the Invoca platform reporting UI) is a globally unique identifier (GUID) that links all the transactions related to a specific call together. This is helpful when building a complete call record in another integrated system.

Additionally, if your Invoca account uses a newer version of the Transactions API, Invoca will roll up all Signals known at the time that the call ends into the call transaction, and all post-call events reported with the same "partner_unique_id" into a single post-call event transaction.


What timezone logic is used to return call data in the Transactions API?

Platforms are setup for a specific timezone and any API oAuth token pulled from the platform is setup to return results in that same timezone. Therefore, make sure your user settings match the platform timezone when attempting to compare or reconcile call totals between the Transactions API and Invoca platform reporting UI.

If a platform’s timezone is changed, any preexisting API oAuth tokens will still use the original platform’s timezone. A new API oAuth token will need to be generated to use the Transactions API with updated timezone preferences. 
 

Tip:
The ‘start_time_network_timezone’ parameter will always return the most current timezone preference for a platform.

How are custom data and signals returned in the Transactions API?

By default, your Transactions API does not return custom data or Signals. However, you can add that data to your queries using two methods: using the “include_columns” feature of your Transactions API, or accessing your data with nested fields. 

“include_columns”:

• Returns Custom data as a name value pair parameter of [custom data API name]: [custom data value]. If you need to reference the name of your custom data fields, login to your Invoca account and click on the gear icon, then select Custom Data. The parameter names of your custom data fields are listed in the “Partner (API) Name” column.
• Returns Signal data as a name value pair parameter of [signal name]: [signal value].
• Read more about how to add this data to your responses at our developers’ portal.

Nested fields:

• Accessible only by JSON and XML-format queries.
• Calls using the parameter “custom_data”, a nested hash which contains the partner name of each custom data field along with its value, data type, and the source of that data.
• Read more about how to add this data to your responses at our developers’ portal. 

If you query the Transactions API with ‘transaction_type’ = call, no Signal or Post-call event transaction rows will be returned. 
 

Related:
• Transactions API developer documentation
• Understanding your Transactions Details Report: Column definitions 
• What is a Transaction in your Invoca reports?