Envestnet Insights API
Financial Insights APIs provide intelligent, personalized, and actionable insights to your end-users. This product details the APIs offered as part of the insights product.
OpenAPI Specification
openapi: 3.0.0
info:
title: Envestnet Insights API Suite
description: >-
Financial Insights APIs provide intelligent, personalized, and actionable insights to your end-users. This document details the APIs offered as part of the insights product.
contact:
email: [email protected]
version: 1.1.0-oas3
servers:
- url: /
paths:
'/insights/configs/customerSubscriptions':
get:
tags:
- Customer
summary: Envestnet Provide details of all the insights available to the customer.
description: >-
This API returns only those Insights which the customer has subscribed to, among all the insights provided by Yodlee. If the customer has chosen to use the Insights configuration tool, the same functionality can be achieved through a graphical user interface.
operationId: getCutomerSubscription
responses:
'200':
description: List of insights subscribed by the customer.
content:
application/json:
schema:
$ref: '#/components/schemas/customerSubscriptions'
examples:
objectExample:
$ref: '#/components/examples/getCustomerSubscriptionExample'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: >-
Y020 : Invalid token in authorization header<br>Y023 : Token has
expired<br>
Y011 : Invalid cobrand or incorrectly configured cobrand
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
patch:
tags:
- Customer
summary: Envestnet Update details of one or more customer subscribed insights.
description: >-
This API can be used to make an insight available to their users at any entity level (Account or View). By setting isSubscribed to true or false at an entity level within each insight, the customer can decide what functionality to make available to their end-users/consumers.<br /><br />Note-
<ul>
<li>This is a PATCH API. Only pass the Attributes in the API request body, which you want to update</li>
<li>This API supports updating multiple Insight's details in a single API call</li>
<li>'insightName' is a mandatory field in the Request body to identify which Insight's details are getting updated</li>
<li>If you pass an attribute that is not editable, you will see an error.</li>
</ul>
operationId: updateCustomerSubscription
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/customerSubscriptions'
examples:
objectExample:
$ref: '#/components/examples/updateCustomerSubscriptionExample'
responses:
'204':
description: Insight for Cobrand Updated.
'400':
description: >-
<br> Y806 : Invalid Input
<br> Y800 : Invalid value for insightName
<br> Y800 : Invalid value for insightTitle; special characters ><\\"'%{}|^~[] are not
supported
<br> Y801: Invalid length for insightTitle; min 3 and max 100 characters including
spaces are allowed.
<br> Y800 : Invalid value for frequency; Supported values are {Frequencies}
<br> Y800 : Invalid value for duration; Supported values are {Durations}
<br> Y800 : Invalid value for type BASETYPE; Only CREDIT, DEBIT are supported
<br> Y800 : Invalid value for {thresholdName} in {insightName} insight Min =
{min} and Max = {max}
<br> Y800 : {InsightName} cannot be subscribed without benchmark enabled for
the customer
<br> Y800 : Invalid value for isSubscribed. {InsightName} cannot be subscribed
without benchmark enabled for the customer
<br> Y802 : Modifying isBenchmarkEnabled is not allowed
<br> Y802 : For insight {InsightName}, passing isBenchmarkEnabled is not
allowed
<br> Y800 : Invalid value for isBenchmarkEnabled Supported values are true,
false"
<br> Y800 : Invalid value for duration. Supported values of duration for
MID_MONTHLY frequency are {Frequencies}
<br> Y802 : For insight {InsightName}, modifying applicableEntity is not allowed
<br> Y802 : For insight {InsightName}, modifying triggerType is not allowed
<br> Y802 : For insight {InsightName}, modifying containers is not allowed
<br> Y802 : For insight {InsightName}, modifying description is not allowed
<br> Y802 : For insight {InsightName}, modifying frequency is not allowed
<br> Y802 : For insight {InsightName}, modifying isSubscribed is not allowed
<br> Y802 : For insight {InsightName}, modifying duration is not allowed
<br> Y800 : Invalid value for isSubscribed; Supported values are true, false
<br> Y825 : Update not allowed without a valid request body
<br> Y803 : Invalid request; Either a valid insightTitle or customerConfiguration is
required.
<br> Y802 : Specifying frequency attribute for {InsightName} insight is not
allowed
<br> Y802 : Specifying duration attribute for {InsightName} insight is not allowed
<br> Y802 : For {InsightName} insight passing threshold is not allowed
<br> Y812 : Required field/value - insightName missing in the request
<br> Y802 : Modifying InsightType attribute is not allowed
<br> Y813 :entityType should be provided
<br> Y813 : Invalid request. The entire object within threshold should be provided
<br> Y803 :At least one additional attribute is required in addition to entityType.
<br> Y800: Invalid value for customerConfiguration; customerConfiguration is
either missing, duplicated, or has insufficient/ incorrect attributes.
<br> Y800: Invalid value for entityType. Supported entityType for {InsightName}
insight are - {Entities}
<br> Y802 : For {InsightName} insight, <String> inside the threshold is not
allowed
<br> Y802 : For {InsightName} insight, {Invalid String} inside the threshold is
either repeated or not allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: >-
Y020 : Invalid token in authorization header<br>Y023 : Token has
expired<br>
Y011 : Invalid cobrand or incorrectly configured cobrand
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'/insights/configs/userSubscriptions':
get:
tags:
- User
summary: Envestnet Provides user-level preferences for each insight.
description: >-
This API returns the details of all the Insights which are subscribed by the customer. If any of the insight has been turned off by setting isSubscribed = false at the customerSubscription level, those insights will not be shown in the userSubscription API.<br /><br />Each Insight details contain attributes such as Insight Frequency, Threshold, etc. By default, all the configurations set by the customer will be inherited by the user. Using a separate PATCH API, consumers can override customer preferences and set their own preferences - wherever applicable.<br /><br />In addition to setting prepoferences at an insight entity level, the consumer will also be able to set preferences at an entity ID level. E.g. LOW_BALANCE_WARNING insight can have a BALANCE threshold of $1,000 set by the customer. However, the user can set a different threshold for each of the accounts the user has aggregated.<br /><br />The customerConfiguration object for each insight mirrors the preferences set by the customer for each insight at the customerSubscription level.
operationId: getUserSubscriptions
parameters:
- name: insightName
in: query
description: Insight name
required: false
style: form
explode: true
schema:
type: string
example: LOW_BALANCE_WARNING
- name: entityId
in: query
description: Comma separated list of entity Ids it could be a account id or view id
required: false
style: form
explode: true
schema:
type: string
example: '1001,5e7885993cd8e328288522f7'
responses:
'200':
description: A list of subscribed Insight details.
content:
application/json:
schema:
$ref: '#/components/schemas/UserSubscriptions'
examples:
objectExample:
$ref: '#/components/examples/getUserSubscriptionExample'
'400':
description: >-
Bad request. ErrorCode and ErrorMessages below:<br> <br>Y800 :
Invalid value for entityId <br>Y824 : The maximum number of
entityId permitted is 100 <br>Y800 : Invalid value for insightName
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: >-
Y020 : Invalid token in authorization header<br>Y023 : Token has
expired<br>
Y011 : Invalid cobrand or incorrectly configured cobrand
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
patch:
tags:
- User
summary: Envestnet Update user-level preferences for each insight.
description: >-
This API can be used to modify user-level preferences for each insight. <br /><br />Each Insight details contain attributes such as Insight Frequency, Threshold, etc. By default, all the configurations set by the customer will be inherited by the user. Using a separate PATCH API, users can override custom preferences and set their own preferences - wherever applicable.<br /><br />In addition to setting preferences at an insight entity level, the consumer will also be able to set preferences at an entity ID level. E.g. LOW_BALANCE_WARNING insight - the user can set a different threshold for each of the accounts the user has aggregated.<br /><br />Note -
<ul>
<li>As this API is a PATCH API, therefore caller must not pass all the available attributes in request JSON. Only pass the Attributes which need to be updated, in the API request body</li>
<li>A single PATCH request can update multiple insights in a single request</li>
</ul>
operationId: updateUserSubscription
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserSubscriptions'
examples:
objectExample:
$ref: '#/components/examples/updateUserSubscriptionExample'
responses:
'204':
description: Insight for User Updated.
'400':
description: >-
Bad request. ErrorCode and ErrorMessages below:<br> Y806 : Invalid input
<br> Y800 : Invalid value for insightName
<br> Y800 : Invalid value for input param in {InsightName} insight
<br> Y800 : Invalid value for frequency; Supported values are {Frequencies}
<br> Y800 : Invalid value for duration; Supported values are {Durations}
<br> Y800 : Invalid value for threshold data in {InsightName} insight
<br> Y800 : Invalid value for type BASETYPE; Only CREDIT, DEBIT are supported
<br> Y800 : Invalid value for {thresholdName} in {insightName} insight Min = {min}
and Max = {max}
<br> Y813 : Invalid request. The entire object within threshold should be provided
<br> Y800 : {InsightName} cannot be subscribed without benchmark enabled for
the customer
<br> Y800 : Invalid value for isSubscribed. {InsightName} cannot be subscribed
without benchmark enabled for the customer
<br> Y802 : Modifying isBenchmarkEnabled is not allowed
<br> Y802 : For insight {InsightName}, passing isBenchmarkEnabled is not allowed
<br> Y800 : Invalid value for isBenchmarkEnabled Supported values are true, false"
<br> Y800 : Invalid value for duration. Supported values of duration for
MID_MONTHLY frequency are {Frequencies}
<br> Y802 : Modifying insightTitle using this API is not allowed
<br> Y802 : For insight {InsightName}, modifying applicableEntity is not allowed
<br> Y802 : For insight {InsightName}, modifying triggerType is not allowed
<br> Y802 : For insight {InsightName}, modifying containers is not allowed
<br> Y802 : For insight {InsightName}, modifying description is not allowed
<br> Y802 : Duplicate entityId entries within userConfiguration is not allowed
<br> Y802 : Specifying frequency attribute for {InsightName} insight is not allowed
<br> Y802 : Specifying duration attribute for {InsightName} insight is not allowed
<br> Y802 : For insight {InsightName}, modifying frequency is not allowed
<br> Y802 : For insight {InsightName}, modifying duration is not allowed
<br> Y825 : Update not allowed without a valid request body
<br> Y802 : For {InsightName} insight passing threshold is not allowed
<br> Y812 : Required field/value - insightName missing in the request
<br> Y800 : Invalid value for userConfiguration; entityId should be provided.
<br> Y802 : Modifying InsightType attribute is not allowed
<br> Y813: entityType should be provided
<br> Y813 : Invalid request. The entire object within threshold should be provided
<br> Y803: At least one additional attribute is required in addition to entityType.
<br> Y800 : Invalid value for userConfiguration; userConfiguration is either missing,
duplicated, or has insufficient/ incorrect attributes
<br> Y802 : For insight {InsightName}, configurations at an entityId level are not
allowed
<br> Y800: Invalid value for entityType. Supported entityType for {InsightName}
insight are - {Entities}
<br> Y800 : Invalid value for entityId; This id is either invalid or not supported for
this insight.
<br> Y802 : Duplicate entityId entries is not allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: >-
Y020 : Invalid token in authorization header<br>Y023 : Token has
expired<br>
Y011 : Invalid cobrand or incorrectly configured cobrand
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
delete:
tags:
- User
summary: Envestnet Delete an existing entity-level insight configuration
description: >-
The DELETE API lets users delete one or more of the existing entityId level configurations for an insight. This can be account level or view level. By deleting all entity ID level configuration, user's insight evaluation defaults to the values specified by the customer for an insight.
operationId: deleteUserSubscriptions
parameters:
- name: insightName
in: query
description: Comma separated list of Insight name
required: true
style: form
explode: true
schema:
type: string
example: LARGE_PURCHAGE
- name: entityId
in: query
description: Comma separated list of entity ids
style: form
explode: true
schema:
type: string
example: 123absce
- name: entityType
in: query
description: Comma separated list of entity
required: false
style: form
explode: true
schema:
type: string
example: 'account,view'
responses:
'204':
description: User subscription deleted sucessfully.
'400':
description: >-
Bad request. ErrorCode and ErrorMessages below:<br> <br>Y800 : Invalid value for insightName
<br>Y805 : Multiple entities not supported <br> Y802: Delete operation for disabled insights is not
allowed <br> Y822: Deletion cannot be requested for entity IDs that
are not currently part of the consumer API for the requested insight
<br> Y822: Deletion cannot be requested for entityNames that are not
currently part of the consumer API for the requested insight
<br> Y802: Duplicate values is not allowed
<br> Y802: Combining multiple values for insightName and other
filters is not allowed <br> Y802: Deleting configurations for all
insights using a single API call is not allowed <br> Y802: Combining
"entity" and other filters is not allowed
<br>Y802 : Delete operation on insights without any custom consumer subscription is not allowed
<br>Y800: invalid value for entityId, id is either invalid or not supported for this insight.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: >-
Y020 : Invalid token in authorization header<br>Y023 : Token has
expired<br>
Y011 : Invalid cobrand or incorrectly configured cobrand
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'/insights/feed':
get:
tags:
- User
summary: 'Envestnet Fetch all the insights generated for a user.'
description: >-
The API allows you to fetch all or a subset of
the insights generated for a specific user. The insights are returned in
the descending order of the insight generation time. By default, the API
returns all the insights generated in the last 31 days.
operationId: getUserFeed
parameters:
- name: insightName
in: query
description: Insight name
required: false
style: form
explode: true
schema:
type: string
example: LOW_BALANCE_WARNING
- name: fromDate
in: query
required: false
description: fromDate
schema:
type: string
example: '2020-04-26T12:00:00Z'
- name: toDate
in: query
required: false
description: toDate
schema:
type: string
example: '2020-05-25T12:00:00Z'
- name: entityId
in: query
description: Comma separated list of entity Ids, it could be a view Id or account Id
required: false
style: form
explode: true
schema:
type: string
example: '10001,5e7885993cd8e328288522f7'
- name: skip
in: query
description: skip (Min 0)
required: false
style: form
explode: true
schema:
type: integer
example: '100'
- name: top
in: query
description: top (Max 50)
required: false
style: form
explode: true
schema:
type: integer
example: '10'
- name: entityType
in: query
description: Comma separated list of entity
required: false
style: form
explode: true
schema:
type: string
example: 'ACCOUNT'
- name: triggerType
in: query
description: triggerType of an insight defines how an Insight was triggered in the system. <br><br>Currently following triggerType are supported - <ul> <li><b>SCHDEULE</b> - Insight evaluation and subsequent generation triggered based on a pre-defined schedule.</li> <li><b>REFRESH</b> - Insight evaluation and subsequent generation triggered when a user's account gets successfully refreshed.</li> <li><b>EVENT</b> - Insight evaluation and subsequent generation triggered based on a system-defined event happening.</li> </ul>
required: false
style: form
explode: true
schema:
type: string
example: 'SCHEDULE'
- name: insightType
in: query
description: Identifies whether the insight is generated at an entity-level - per account or per view (OTHER), or if it considers all entities for the user - e.g. all accounts (AGGREGATE).<br><br>
required: false
style: form
explode: true
schema:
type: string
example: 'AGGREGATE'
responses:
'200':
description: A list of subscribed Insight details.
content:
application/json:
schema:
$ref: '#/components/schemas/feeds'
examples:
objectExample:
$ref: '#/components/examples/getFeedExample'
'400':
description: >-
Bad request. ErrorCode and ErrorMessages below:<br> <br>Y800:
Invalid value for insightName; Insight name requested not found <br>Y800:
Invalid value for entityId <br>Y805: Multiple entities not supported<br>Y800:
Invalid value for fromDate/toDate. Both fromDate and toDate needs to
be of the same format - yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ <br>Y802:
Value for fromDate or toDate beyond the last 1 year is not allowed
<br>Y813: Both fromDate and toDate parameter should be provided
<br>Y802: Difference greater than 31 days between fromDate and
toDate is not allowed <br>Y802: Combining insightName and entityId filters
for AGGREGATE insights is not allowed <br>Y802: Duplicate values for
entity id are not allowed <br>Y800: Invalid value for skip
<br>Y800: Invalid value for top
<br>Y800: Invalid value for triggerType; allowed values are REFRESH, EVENT, SCHEDULE
<br>Y800: Invalid value for entityType; allowed values are ACCOUNT, VIEW
<br>Y800: Invalid value for insightType; allowed values are OTHER, AGGREGATE
<br>Y802: Duplicate values for entityType are not allowed
<br>Y802: Duplicate values for insightType are not allowed
<br>Y802: Duplicate values for triggerType are not allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: >-
Y020 : Invalid token in authorization header<br>Y023 : Token has
expired<br>
Y011 : Invalid cobrand or incorrectly configured cobrand
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/insights/feedExtracts:
get:
tags:
- User
summary: 'Envestnet Fetch all the insights generated for a user.'
description: >-
The API allows you to fetch all or a subset of
the insights generated for a specific user. The insights are returned in
the descending order of the insight generation time. By default, the API
returns all the insights generated in the last 31 days.
operationId: getUserFeedWebHook
parameters:
- name: insightName
in: query
description: Insight name
required: false
style: form
explode: true
schema:
type: string
example: LOW_BALANCE_WARNING
- name: fromDate
in: query
required: false
description: fromDate
schema:
type: string
example: '2020-04-26T12:00:00Z'
- name: toDate
in: query
required: false
description: toDate
schema:
type: string
example: '2020-05-25T12:00:00Z'
- name: entityId
in: query
description: Comma separated list of entity Ids, it could be a view Id or account Id
required: false
style: form
explode: true
schema:
type: string
example: '10001,5e7885993cd8e328288522f7'
- name: skip
in: query
description: skip (Min 0)
required: false
style: form
explode: true
schema:
type: integer
example: '100'
- name: top
in: query
description: top (Max 50)
required: false
style: form
explode: true
schema:
type: integer
example: '10'
- name: entityType
in: query
description: Comma separated list of entity
required: false
style: form
explode: true
schema:
type: string
example: 'ACCOUNT'
- name: triggerType
in: query
description: triggerType of an insight defines how an Insight was triggered in the system. <br><br>Currently following triggerType are supported - <ul> <li><b>SCHDEULE</b> - Insight evaluation and subsequent generation triggered based on a pre-defined schedule.</li> <li><b>REFRESH</b> - Insight evaluation and subsequent generation triggered when a user's account gets successfully refreshed.</li> <li><b>EVENT</b> - Insight evaluation and subsequent generation triggered based on a system-defined event happening.</li> </ul>
required: false
style: form
explode: true
schema:
type: string
example: 'SCHEDULE'
- name: insightType
in: query
description: Identifies whether the insight is generated at an entity-level - per account or per view (OTHER), or if it considers all entities for the user - e.g. all accounts (AGGREGATE).<br><br>
required: false
style: form
explode: true
schema:
type: string
example: 'AGGREGATE'
- name: loginName
in: query
description: Name of the User.
required: true
style: form
explode: true
schema:
type: string
example: 'insightsUser'
responses:
'200':
description: A list of subscribed Insight details.
content:
application/json:
schema:
$ref: '#/components/schemas/feeds'
examples:
objectExample:
$ref: '#/components/examples/getFeedExample'
'400':
description: >-
Bad request. ErrorCode and ErrorMessages below:<br> <br>Y803:
loginName required.<br>Y800: Invalid value for loginName<br>Y800:
Invalid value for insightName; Insight name requested not found <br>Y800:
Invalid value for entityId <br>Y805: Multiple entities not supported<br>Y800:
Invalid value for fromDate/toDate. Both fromDate and toDate needs to
be of the same format - yyyy-MM-dd or yyyy-MM-ddTHH:mm:ssZ <br>Y802:
Value for fromDate or toDate beyond the last 1 year is not allowed
<br>Y813: Both fromDate and toDate parameter should be provided
<br>Y802: Difference greater than 31 days between fromDate and
toDate is not allowed <br>Y802: Combining insightName and entityId filters
for AGGREGATE insights is not allowed <br>Y802: Duplicate values for
entity id are not allowed <br>Y800: Invalid value for skip
<br>Y800: Invalid value for top
<br>Y800: Invalid value for triggerType; allowed values are REFRESH, EVENT, SCHEDULE
<br>Y800: Invalid value for entityType; allowed values are ACCOUNT, VIEW
<br>Y800: Invalid value for insightType; allowed values are OTHER, AGGREGATE
<br>Y802: Duplicate values for entityType are not allowed
<br>Y802: Duplicate values for insightType are not allowed
<br>Y802: Duplicate values for triggerType are not allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: >-
Y020 : Invalid token in authorization header<br>Y023 : Token has
expired<br>
Y011 : Invalid cobrand or incorrectly configured cobrand
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'/insights/feed/count':
get:
tags:
- User
summary: 'Envestnet Fetch the count of generated insight for a user.'
description: >-
This API provides the count of the insights generated for the user. By default, the API provides the count of the insights generated in last 31 days.
operationId: getUserFeedCount
parameters:
- name: insightName
in: query
description: Insight name
required: false
style: form
explode: true
schema:
type: string
example: LOW_BALANCE_WARNING
- name: fromDate
in: query
required: false
description: fromDate
schema:
type: string
example: '2020-04-26T12:00:00Z'
- name: toDate
in: query
required: false
description: toDate
schema:
type: string
example: '2020-05-25T12:00:00Z'
- name: entityId
in: query
description: Comma separated list of entity Ids, it could be a view Id or account Id
required: false
style: form
explode: true
schema:
type: string
example: '10001,5e7885993cd8e328288522f7'
- name: entityType
in: query
description: Comma separated list of entity
required: false
style: form
explode: true
schema:
type: string
example: 'ACCOUNT'
- name: triggerType
in: query
description: triggerType of an insight defines how an Insight was triggered in the system. <br><br>Currently following triggerType are supported - <ul> <li><b>SCHDEULE</b> - Insight evaluation and subsequent generation triggered based on a pre-defined schedule.</li> <li><b>REFRESH</b> - Insight evaluation and subsequent generation triggered when a user's account gets successfully refreshed.</li> <li><b>EVENT</b> - Insight evaluation and subsequent generation triggered based on a system-defined event happening.</li> </ul>
required: false
style: form
explode: true
schema:
type: string
example: 'SCHEDULE'
- name: insightType
in: query
description: Identifies whether the insight is generated at an entity-level - per account or per view (OTHER), or if it considers all entities for the user - e.g. all accounts (AGGREGATE).<br><br>
required: false
style: form
explode: true
schema:
type: string
example: 'AGGREGATE'
responses:
'200':
description: A list of subscribed Insight details.
content:
application/json:
schema:
$ref: '#/components/schemas/feedsCount'
examples:
objectExample:
$ref: '#/components/examples/getFeedCountExample'
'400':
description: >-
# --- truncated at 32 KB (154 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/envestnet/refs/heads/main/openapi/envestnet-insights-openapi-original.yml