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.

​Summary of Changes

​Endpoint Mapping

​Field Mapping

Summary of Changes

Endpoint Mapping

Field Mapping