Migrate From Beats To Insights API

If you’re looking to upgrade to the Insights API on the Platform API, this guide helps you migrate from the Beats API to the Insights API.

Summary of Changes

The following are the main differences between the two APIs:

• The Insights API offers endpoints that have the same functionality as all 3 endpoints in the Beats API, but also contains endpoints to help check and list relevant accounts, categories, transactions, merchants, and scheduled payments. See our API reference for a list of all fields and endpoints.
• The object returned in the Insights API is insight or insights, instead of beat or beats.
• The endpoint paths use insight or insights, instead of beat or beats. Refer to Endpoint Mapping to see the new paths.
• Refer to Field Mapping to see which fields have stayed the same and changed.
• In the Insights API, there isn't a way to return the primary_account_guid or primary_transaction_guid.

Endpoint Mapping

The Insights API offers the same endpoints as the Beats API, and more.

This section shows how each endpoint in the old Beats API maps to the new Insights API.

Endpoint	Beats API Endpoint Path	Insights API Endpoint Path
List insights (formerly called beats) for a user	GET /beats	GET /users/{user_guid}/insights
Read an insight	GET /beats/{beat_guid}	GET /users/{user_guid}/insights/{insight_guid}
Update an insight	PUT /beats/{beat_guid}	PUT /users/{user_guid}/insights/{insight_guid}

Field Mapping

See our API reference for a list of fields in the Insights API.

The following fields have the same functionality in both APIs:

• created_at
• description
• guid
• has_been_displayed
• is_dismissed
• template
• title
• updated_at
• user_guid

This table shows you which fields changed and require you to update your logic.

Getting the same functionality out of a field may require you to also use some new endpoints.

Beats Fields	Similar Functionality in Insights API
account_guids	Check the has_associated_accounts field. If true, use the List All Accounts Associated with Insight endpoint.
digest	Use guid as an identifier.
displayed_at	Use active_at.
is_relevant	Use one of the following fields to check if there are any relevant resources: has_associated_accounts has_associated_merchants has_associated_scheduled_payments has_associated_transactions Then you can use one of the following endpoints: List All Accounts Associated With An Insight List All Merchants Associated With An Insight List All Scheduled Payments Associated With An Insight List All Transactions Associated With An Insight
primary_account_guid	You can't get a primary account GUID. You can use the has_associated_accounts field to check if there are any accounts associated with that insight, then call the List All Accounts Associated With An Insight endpoint, though this may return multiple accounts.
primary_transaction_guid	You can't get a primary transaction GUID. You can use the has_associated_transactions field to check if there are any transactions associated with that insight, then call the List All Transactions Associated With An Insight endpoint, though this may return multiple transactions.
transaction_guids	First, read an insight. If has_associated_transactions is true, then use the List All Transactions Associated With An Insight endpoint.