openapi: 3.1.0
info:
title: Insights Enrichment User Tagging API
description: "# Overview\n[Download our postman collection here.](https://fingoal.dev/FinGoal%20Enrichment.postman_collection.json)\n\nThe Insights API provides developers with tools to enhance their transaction, account, and user data with deep enrichment. Although the information returned by the Insights API can be utilized in various ways and implementations may differ, the initial steps for using the API are consistent: \n1. Request a FinGoal developer account.\n2. Obtain API access credentials.\n3. Generate an Insights API authentication token. \n4. Submit transactions to the Insights API. \n5. Register for Webhooks.\n6. Request Enrichment.\n\n## Important Resources\n- [Complete Insights API Tag Registry](https://fingoal.com/tags-list)\n- [Complete Insights API Categorization Spreadsheet](https://docs.google.com/spreadsheets/d/1jnmw1LriclC3bO-oC7f7EkhmfCL7gw2LQLX8zay1vXw/edit?gid=0#gid=0)\n\n## Request a FinGoal Developer Account\nTo use the Insights API, you need authentication credentials. These credentials can be obtained by <a href=\"https://fingoal.com/request-developer-account\" target=\"_blank\"> requesting a FinGoal developer account</a>. FinGoal developer support will send you development environment credentials within 24 hours. These credentials are required for the quickstart. \n# Quickstart\n## Generate a JWT Authentication Token\nAll Insights API endpoints require an `Authorization` header with a `Bearer` token. This token is a JSON Web Token (JWT) generated by the Insights API authentication endpoint. To generate this token, you will need the `client_id` and `client_secret` provided when you requested a FinGoal developer account. \n\n### 1. Prepare the Request Body\nThe request body is a JSON object with the following structure:\n```json\n{\n\t\"client_id\": \"{YOUR_CLIENT_ID}\",\n\t\"client_secret\": \"{YOUR_CLIENT_SECRET}\"\n} \n```\n### 2. Make a POST Request\nMake a POST request to the Insights API authentication endpoint using the prepared JSON object.\n```js\nconst body = {\n \"client_id\": \"{YOUR_CLIENT_ID}\",\n \"client_secret\": \"{YOUR_CLIENT_SECRET}\"\n}\n\nconst requestOptions = {\n method: 'POST',\n body: body,\n};\n\ntry {\n\tconst response = await fetch(\"https://findmoney-dev.fingoal.com/v3/authentication\", requestOptions);\n const data = response.json();\n\tconst { access_token } = data;\n\tconsole.log({ access_token });\n} catch(error) {\n\tconsole.log('AUTHENTICATION_ERROR:', error);\n}\n```\nThe JavaScript code above uses the `fetch` API to request an access token. If the request succeeds, it extracts the access_token from the response body. If an error occurs, it logs the error. \n\n### Successful Response\nIf the request is successful, the response body will contain a JSON object with the following structure:\n- `access_token`: The JWT token used to authenticate requests to the Insights API.\n- `scope`: The permissions that the token has.\n- `expires_in`: The number of seconds until the token expires (always 86400 seconds, or 24 hours). \n- `token_type`: The type of token. This value is always `Bearer`.\n```json\n{\n \"access_token\": \"eyJh...\",\n \"scope\": \"read:transactions write:transactions ...\",\n \"expires_in\": 86400,\n \"token_type\": \"Bearer\"\n}\n```\n### Best Practices \n- Store the `access_token` securely. Do not expose it in client-side code.\n- Use the `expires_in` value to determine when to refresh the token.\n- Regenerate a new token only after the current token has expired.\n\n## Include the JWT Token in Requests\nTo authenticate your requests to the Insights API, you must include the JWT token in the `Authorization` header. The header should have the following structure:\n```json\n{\n \"Authorization\": \"Bearer {YOUR_ACCESS_TOKEN}\"\n}\n```\nThis header will successfully authenticate any request to the Insights API. You can now proceed to the enrichment, tagging, or savings recommendations quickstarts to integrate the Insights API into your application.\n\n## Tenancy \nInsights API supports the concept of tenancy. A `tenant` refers to a grouping of customer data (users, transactions, tags, accounts, etc.) that may be accessible to multiple clients. By default, a new client’s connection to the InsightsAPI does not use tenancy; however, they may enable tenancy at any time.\n\nCurrently, Insights API does not allow you to create custom tenants. The FinGoal customer support team needs to coordinate with both the client & tenant parties to set up a new connection. If a client’s request for access to a tenant is approved, FinGoal will send the client an identifier for the tenant, and authorize them to access that tenant’s resources. \n\nTo interact with the Insights API on behalf of a tenant, include a tenant_id in your Insights API token request: \n\n```js\nconst response = await fetch(\"{INSIGHTS_API_BASE_URL}/v3/authentication\", {\n\t\tmethod: \"POST\",\n\t\tdata: {\n\t\t\t\tclient_id: \"{MY_CLIENT_ID}\",\n\t\t\t\tclient_secret: \"{MY_CLIENT_SECRET}\",\n\t\t\t\ttenant_id: \"{TENANT_ID_FROM_FINGOAL}\"\n\t\t}\n});\n```\n\nBy including the `tenant_id` in your token scopes, the generated token allows you to: \n\n- Write data to the tenant’s environment.\n- Read data from the tenant’s environment.\n\n<aside>\nIf you do not include a tenant ID, your token will only allow you to access data you have created without a specific tenant association. \n</aside>\n\nAs soon as you are successfully added to a tenant’s data silo, you will begin receiving webhook updates for all activity in that silo. Note that this may include new enrichment data that is added to the environment by clients other than yourself. Refer to the webhook documentation for more information on the content of Insights API webhooks."
version: 3.1.3
servers:
- url: https://findmoney-dev.fingoal.com/v3
description: Insights API Development
- url: https://findmoney.fingoal.com/v3
description: Insights API Production
security:
- Authentication: []
tags:
- name: User Tagging
description: markdown/tagging.md
paths:
/users/{userId}:
get:
parameters:
- name: userId
in: path
required: true
description: The ID for the user you want to retrieve.
schema:
type: string
- name: include_tagged_transactions
in: header
required: false
deprecated: true
schema:
type: string
description: This field has been deprecated. Tagged transactions are received automatically from the enrichment API. Set to true to include all of the user's tagged transactions in the response. By default, tagged transactions are not included.
tags:
- User Tagging
summary: Get a User
description: '<strong style="color:red;">This endpoint runs on data sent to the Transaction Enrichment endpoints. Tagging is run in batches twice daily and thus not available immediately after posting transactions. Also, in order to receive user tags, transaction dates must be within the past 90 days.</strong>
<br/>
<br />
Fetches user and transaction tags for a specified user ID. Both endpoints return the same schema. Use the sync keyword to trigger a manual update on the transaction and user tags for a single user.
'
operationId: getOneUser
security:
- Authentication:
- read
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- user
properties:
user:
type: object
required:
- uid
properties:
client_id:
type: string
description: Your client ID.
id:
type: string
description: The user ID.
uid:
type: string
description: The user's ID.
uniqueId:
type: string
description: The user's unique ID in the format of `client_id:uid`.
lifetimeSavings:
type: number
description: The user's lifetime savings, if known.
registrationDate:
type: string
format: date-time
description: The date on which the user was registered with FinSight API.
subtenantId:
type: string
description: The user's subtenant ID.
tags:
description: The FinSight API tags that were applied to the user.
type: array
items:
type: string
totaltransactions:
type: number
description: The total number of transactions the user has in FinSight API.
transactionsSinceLastUpdate:
type: number
description: The number of transactions since the last time insights were run for the user.
transactions:
type: array
items:
type: object
properties:
transaction_id:
type: string
description: The ID of the transaction.
simple_description:
type: string
description: A human-readable, simplified description for the transaction.
original_description:
type: string
description: The originally-submitted description of the transaction.
category:
type: string
description: The category of the transaction.
amount:
type: number
description: The transaction's amount in USD.
date:
type: string
format: date-time
description: The date of the transaction.
tags:
type: array
items:
type: string
description: The tags that were applied to the transaction.
'401':
description: Unauthorized
'404':
description: User ID could not be found
/users/{userId}/sync:
get:
parameters:
- name: userId
in: path
required: true
description: The ID for the user you want to retrieve.
schema:
type: string
- name: include_tagged_transactions
in: header
required: false
deprecated: true
schema:
type: string
description: This field has been deprecated. Tagged transactions are received automatically from the enrichment API. Set to true to include all of the user's tagged transactions in the response. By default, tagged transactions are not included.
tags:
- User Tagging
summary: Trigger a User Tag Update
description: '<strong style="color:red;">This endpoint runs on data sent to the Transaction Enrichment endpoints. Tagging is run in batches twice daily and thus not available immediately after posting transactions. Also, in order to receive user tags, transaction dates must be within the past 90 days.</strong>
<br/>
<br />
Fetches user and transaction tags for a specified user ID. Both endpoints return the same schema. Use the sync keyword to trigger a manual update on the transaction and user tags for a single user.
'
operationId: getOneUserSync
security:
- Authentication:
- enrichment
- calls_to_action
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/UsersUserIdGet200Response'
'401':
description: Unauthorized
'404':
description: User ID could not be found
/users/tags/{guid}:
get:
parameters:
- name: guid
in: path
required: true
description: The guid for the updates you want to retrieve.
schema:
type: string
tags:
- User Tagging
summary: Retrieve Updated Tags
description: "If you subscribe to the user tag status updates, you can retrieve them from this endpoint with the `guid` you received from the status update webhook. The tag updates will stay live at this endpoint for 24 hours. \n"
operationId: getUserTagUpdates
security:
- Authentication:
- read
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookConfigurationsTestPostUSER_TAGS_DATA'
'401':
description: Unauthorized
'404':
description: User ID could not be found
components:
schemas:
WebhookConfigurationsTestPostUSER_TAGS_DATA:
type: object
properties:
tenant_id:
type: string
description: The ID of the tenant for the users included in this update, if they are from a tenant environment.
userTags:
type: object
properties:
created:
description: A list of the new user tags that were generated for this user since the last user tagging update. A full list of the user tags can be accessed [here](https://fingoal.com/tags-list).
type: array
items:
type: object
properties:
user_id:
description: The user who received this tag. Corresponds to whatever 'uid' you initially uploaded to the enrichment.
type: string
example: '409088'
user_tag_id:
description: The ID of the tag that has been applied.
type: integer
example: 61
tag_name:
description: The name of the tag that has been applied.
type: string
example: Home Improvement Loan
deleted:
description: A list of the user tags that were removed from this user since the last user tagging update.
type: array
items:
type: object
properties:
user_id:
description: The user who received this tag. Corresponds to whatever 'uid' you initially uploaded to the enrichment.
type: string
example: '409088'
user_tag_id:
description: The ID of the tag that has been removed.
type: integer
example: 46
tag_name:
description: The name of the tag that has been removed.
type: string
example: Movie Goer
modified:
description: For incremental (that is, scored) user tags. Contains all scoring changes for any incremental user tags that have received a score change since the last update.
type: array
items:
type: object
properties:
user_id:
description: The user who received this tag. Corresponds to whatever 'uid' you initially uploaded to the enrichment.
type: string
example: '409088'
user_tag_id:
description: The ID of the tag that has been updated.
type: integer
example: 46
tag_name:
description: The name of the tag that has been updated.
type: string
example: Movie Goer
previous_value:
description: The last value for this tag's score, prior to this update.
type: integer
example: 50
new_value:
description: The new value for this tag's score.
type: integer
example: 75
delta:
description: The amount by which this tag's score has changed. Can be negative or positive. Will be the difference between the new_value and previous_value fields.
type: integer
example: 25
securitySchemes:
Authentication:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://findmoney.fingoal.com/v3/authentication
scopes:
enrichment: Grants access to the transaction enrichment APIs.