FinGoal Enrichment API
The Insights API's transaction enrichment endpoints enable developers to clean and enhance their transaction data. This process includes standardizing merchant names, categorizing transactions, and adding additional metadata. It also supports transaction-level tagging. Transactions submitted to the enrichment endpoints contribute to the Insights API's user tagging capabilities. The Insights API offers both synchronous and asynchronous flows. The synchronous flow is a direct request-response model intended for testing and development purposes only. All production requests should use the asynchronous historical and streaming transaction enrichment endpoints. View Full List of FinGoal Categories View Full List of FinGoal Tags ## Enrichment Quickstart This quickstart requires a JWT, which can be generated following the top-level authentication quickstart. Ensure you have a valid JWT before proceeding. ### 1. Prepare the Request Body The request body should be a JSON object with a single parameter, `transactions`, which must be an array. Each transaction must include the following fields: - `uid`: A unique user identifier. - `amountnum`: The transaction amount. - `date`: The transaction date. - `original_description`: The original transaction description. - `transactionid`: The unique transaction identifier. - `accountType`: The account type. - `settlement`: The settlement type. ```json { "transactions": [ { "uid": "16432789fdsa78", "accountid": "1615", "amountnum": 12.41, "date": "2024-05-11", "original_description": "T0064 TARGET STORE", "transactionid": "988cee06-5d36-11ec-b00b-bc8d8f2303a12733", "accountType" : "creditCard", "settlement": "debit" } ] } ``` ### 2. Make a POST Request Make a POST request to the Insights API cleanup endpoint using the prepared JSON object. Include the JWT in the `Authorization` header. ```js const headers = new Headers(); headers.append("Authorization", "Bearer {YOUR_TOKEN}"); headers.append("Content-Type", "application/json"); const body = JSON.stringify({ "transactions": [ { "uid": "16432789fdsa78", "accountid": "1615", "amountnum": 12.41, "date": "2024-05-11", "original_description": "T0064 TARGET STORE", "transactionid": "988cee06-5d36-11ec-b00b-bc8d8f2303a12733", "accountType" : "creditCard", "settlement": "debit" } ] }); const requestOptions = { method: 'POST', redirect: 'follow' headers, body, }; try { const response = await fetch("https://findmoney-dev.fingoal.com/v3/cleanup", requestOptions); const data = response.json(); console.log(data); } catch(error) { console.log('ERROR:', error); } ``` The JavaScript code above uses the `fetch` API to request transaction enrichment. If the request succeeds, it logs the response body. If an error occurs, it logs the error. ### 3. Extract the Batch Request ID from a Successful Response If the request is successful, the response body will contain a JSON object with a single parameter, `status`. The `status` object has the following structure: - `transactions_received`: Whether or not the transactions were successfully enqueued for enrichment. - `transactions_validated`: Whether or not the transactions were successfully validated. - `processing`: Whether or not the transactions are currently being processed. - `num_transactions_processing`: The number of transactions that are currently being processed. - `batch_request_id`: The unique identifier for the batch request. ```json { "status": { "transactions_received": true, "transactions_validated": true, "processing": true, "num_transactions_processing": 1, "batch_request_id": "988cee06-5d36-11ec-b00b-bc8d8f2303a12733" } } ``` The `batch_request_id` is a unique identifier for the batch request. You will use this identifier to retrieve the enriched transactions. ### 4. Listen for the Enrichment Completion Event To receive a webhook notification for a completed enrichment batch, you must submit a webhook URL. Use the FinGoal support email (support@fingoal.com) to submit a webhook URL for registry. Once the URL is registered, you will automatically receive all future enrichment completion webhooks. Webhook notifications are sent as HTTP POST requests to the registered URL. The webhook URL must be publicly accessible and support HTTPS connections. The Insights API cannot send webhooks to a non-HTTPS URL. The webhook payload contains a JSON object with the following structure: - `batch_request_id`: The unique identifier for the batch request. The `batch_request_id` corresponds to the `batch_request_id` returned in the initial enrichment request. ```json { "batch_request_id": "988cee06-5d36-11ec-b00b-bc8d8f2303a12733" } ``` #### Verifying the Enrichment Webhook Every enrichment complete webhook includes an `X-Webhook-Verification` header. The header contains a SHA-256 HMAC signature of the webhook payload. To verify the webhook, you must generate a SHA-256 HMAC signature using the webhook payload and your Insights API secret key. If the generated signature matches the signature in the `X-Webhook-Verification` header, the webhook is valid. If not, the webhook should be discarded. The following snippet demonstrates how to verify the webhook signature using Node.js with the `crypto` and `express` libraries. ```js const crypto = require('crypto'); const express = require('express'); const app = express(); app.use(express.json()); app.post('/webhook-receiver', (req, res) => { const { headers, body } = req; const { 'x-webhook-verification': signature } = headers; if (!signature) { res.status(400).send('Reject the webhook if no verification header is present.'); return; } const secret = 'YOUR_CLIENT_SECRET'; const payload = JSON.stringify(body); const hmac = crypto.createHmac('sha256', secret); const digest = hmac.update(payload).digest('hex'); if (digest === signature) { res.status(200).send('The webhook is verified. It is safe to process the payload.'); } else { res.status(400).send('The Webhook verification is incorrect for the payload. Reject the webhook.'); } }); ``` ### 5. Retrieve the Enriched Transactions With the `batch_request_id`, submit a GET request to the Insights API enrichment retrieval endpoint. Include the JWT in the `Authorization` header. ```js const headers = new Headers(); headers.append("Authorization", "Bearer {YOUR_TOKEN}"); const requestOptions = { method: 'GET', redirect: 'follow', headers, }; try { const response = await fetch("https://findmoney-dev.fingoal.com/v3/cleanup/{batch_request_id}", requestOptions); const data = response.json(); console.log(data); } catch(error) { console.log('ERROR:', error); } ``` The JavaScript code above uses the `fetch` API to request the enriched transactions. If the request succeeds, it logs the response body. If an error occurs, it logs the error. ### Successful Response If the request is successful, the response body will contain a JSON object a single parameter, `enrichedTransactions`. The `enrichedTransactions` array will contain all available transaction-level enrichment for the data in this batch. ### Best Practices - Group transactions by `uid` for optimal performance. - Provide as much information as possible in the request body to improve enrichment quality. - Use unique `uid` and `transactionid` values for each user and transaction. These identifiers may need to be cross-referenced with your system's data in the future. - Avoid using personally identifiable information (PII) in the `uid` or `transactionid` fields. We recommend using a UUID or similar anonymous identifier instead.
Documentation
Specifications
Other Resources
openapi: 3.1.0
info:
title: Insights Enrichment 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: Enrichment
description: "The Insights API's transaction enrichment endpoints enable developers to clean and enhance their transaction data. This process includes standardizing merchant names, categorizing transactions, and adding additional metadata. It also supports transaction-level tagging. Transactions submitted to the enrichment endpoints contribute to the Insights API's user tagging capabilities. \n\nThe Insights API offers both synchronous and asynchronous flows. The synchronous flow is a direct request-response model intended for testing and development purposes only. All production requests should use the asynchronous historical and streaming transaction enrichment endpoints.\n\n<a href=\"https://docs.google.com/spreadsheets/d/1XL649eKzMZ21WGWdcUE4cvKbKb6oXzfdBv5Ob8qPpbM/edit?usp=sharing\" target=\"blank\">View Full List of FinGoal Categories</a>\n\n<a href=\"https://fingoal.com/tags-list\" target=\"blank\">View Full List of FinGoal Tags</a>\n\n\n## Enrichment Quickstart\nThis quickstart requires a JWT, which can be generated following the top-level authentication quickstart. Ensure you have a valid JWT before proceeding.\n\n### 1. Prepare the Request Body\nThe request body should be a JSON object with a single parameter, `transactions`, which must be an array. Each transaction must include the following fields:\n- `uid`: A unique user identifier.\n- `amountnum`: The transaction amount.\n- `date`: The transaction date.\n- `original_description`: The original transaction description.\n- `transactionid`: The unique transaction identifier.\n- `accountType`: The account type.\n- `settlement`: The settlement type.\n\n```json\n{\n \"transactions\": [\n {\n \"uid\": \"16432789fdsa78\",\n \"accountid\": \"1615\",\n \"amountnum\": 12.41,\n \"date\": \"2024-05-11\",\n \"original_description\": \"T0064 TARGET STORE\",\n \"transactionid\": \"988cee06-5d36-11ec-b00b-bc8d8f2303a12733\",\n \"accountType\" : \"creditCard\",\n \"settlement\": \"debit\"\n }\n ]\n}\n```\n### 2. Make a POST Request\nMake a POST request to the Insights API cleanup endpoint using the prepared JSON object. Include the JWT in the `Authorization` header.\n```js\n const headers = new Headers();\n headers.append(\"Authorization\", \"Bearer {YOUR_TOKEN}\");\n headers.append(\"Content-Type\", \"application/json\");\n\n const body = JSON.stringify({\n \"transactions\": [\n {\n \"uid\": \"16432789fdsa78\",\n \"accountid\": \"1615\",\n \"amountnum\": 12.41,\n \"date\": \"2024-05-11\",\n \"original_description\": \"T0064 TARGET STORE\",\n \"transactionid\": \"988cee06-5d36-11ec-b00b-bc8d8f2303a12733\",\n \"accountType\" : \"creditCard\",\n \"settlement\": \"debit\"\n }\n ]\n });\n\n const requestOptions = {\n method: 'POST',\n redirect: 'follow'\n headers,\n body,\n };\n\n try {\n const response = await fetch(\"https://findmoney-dev.fingoal.com/v3/cleanup\", requestOptions);\n const data = response.json();\n console.log(data);\n } catch(error) {\n console.log('ERROR:', error);\n }\n```\nThe JavaScript code above uses the `fetch` API to request transaction enrichment. If the request succeeds, it logs the response body. If an error occurs, it logs the error.\n### 3. Extract the Batch Request ID from a Successful Response\nIf the request is successful, the response body will contain a JSON object with a single parameter, `status`. The `status` object has the following structure:\n- `transactions_received`: Whether or not the transactions were successfully enqueued for enrichment.\n- `transactions_validated`: Whether or not the transactions were successfully validated.\n- `processing`: Whether or not the transactions are currently being processed.\n- `num_transactions_processing`: The number of transactions that are currently being processed.\n- `batch_request_id`: The unique identifier for the batch request.\n\n```json\n{\n \"status\": {\n \"transactions_received\": true,\n \"transactions_validated\": true,\n \"processing\": true,\n \"num_transactions_processing\": 1,\n \"batch_request_id\": \"988cee06-5d36-11ec-b00b-bc8d8f2303a12733\"\n }\n}\n```\nThe `batch_request_id` is a unique identifier for the batch request. You will use this identifier to retrieve the enriched transactions. \n### 4. Listen for the Enrichment Completion Event \nTo receive a webhook notification for a completed enrichment batch, you must submit a webhook URL. Use the FinGoal support email (support@fingoal.com) to submit a webhook URL for registry. Once the URL is registered, you will automatically receive all future enrichment completion webhooks. \n\nWebhook notifications are sent as HTTP POST requests to the registered URL. The webhook URL must be publicly accessible and support HTTPS connections. The Insights API cannot send webhooks to a non-HTTPS URL. \n\nThe webhook payload contains a JSON object with the following structure: \n- `batch_request_id`: The unique identifier for the batch request.\n\nThe `batch_request_id` corresponds to the `batch_request_id` returned in the initial enrichment request. \n```json\n{\n \"batch_request_id\": \"988cee06-5d36-11ec-b00b-bc8d8f2303a12733\"\n}\n```\n#### Verifying the Enrichment Webhook \nEvery enrichment complete webhook includes an `X-Webhook-Verification` header. The header contains a SHA-256 HMAC signature of the webhook payload. To verify the webhook, you must generate a SHA-256 HMAC signature using the webhook payload and your Insights API secret key. If the generated signature matches the signature in the `X-Webhook-Verification` header, the webhook is valid. If not, the webhook should be discarded. \n\nThe following snippet demonstrates how to verify the webhook signature using Node.js with the `crypto` and `express` libraries.\n```js\nconst crypto = require('crypto');\nconst express = require('express');\nconst app = express();\n\napp.use(express.json());\napp.post('/webhook-receiver', (req, res) => {\n const { headers, body } = req;\n const { 'x-webhook-verification': signature } = headers;\n if (!signature) {\n res.status(400).send('Reject the webhook if no verification header is present.');\n return;\n }\n\n const secret = 'YOUR_CLIENT_SECRET';\n const payload = JSON.stringify(body);\n const hmac = crypto.createHmac('sha256', secret);\n const digest = hmac.update(payload).digest('hex');\n\n if (digest === signature) {\n res.status(200).send('The webhook is verified. It is safe to process the payload.'); \n } else {\n res.status(400).send('The Webhook verification is incorrect for the payload. Reject the webhook.');\n }\n});\n```\n\n### 5. Retrieve the Enriched Transactions\nWith the `batch_request_id`, submit a GET request to the Insights API enrichment retrieval endpoint. Include the JWT in the `Authorization` header. \n```js\n const headers = new Headers();\n headers.append(\"Authorization\", \"Bearer {YOUR_TOKEN}\");\n\n const requestOptions = {\n method: 'GET',\n redirect: 'follow',\n headers,\n };\n\n try {\n const response = await fetch(\"https://findmoney-dev.fingoal.com/v3/cleanup/{batch_request_id}\", requestOptions);\n const data = response.json();\n console.log(data);\n } catch(error) {\n console.log('ERROR:', error);\n }\n```\nThe JavaScript code above uses the `fetch` API to request the enriched transactions. If the request succeeds, it logs the response body. If an error occurs, it logs the error.\n### Successful Response\nIf the request is successful, the response body will contain a JSON object a single parameter, `enrichedTransactions`. The `enrichedTransactions` array will contain all available transaction-level enrichment for the data in this batch. \n\n### Best Practices \n- Group transactions by `uid` for optimal performance. \n- Provide as much information as possible in the request body to improve enrichment quality.\n- Use unique `uid` and `transactionid` values for each user and transaction. These identifiers may need to be cross-referenced with your system's data in the future.\n- Avoid using personally identifiable information (PII) in the `uid` or `transactionid` fields. We recommend using a UUID or similar anonymous identifier instead. \n"
paths:
/cleanup/sync:
post:
tags:
- Enrichment
summary: Test Transaction Enrichment
description: "The test transaction enrichment endpoint provides immediate enrichment on transaction data. This endpoint is ideal for testing API functionality and previewing enrichment results. \n\n**This endpoint is not intended for production use.** Use the historical and streaming endpoints for production-level enrichment.\n\n\nFor optimal performance, adhere to the following limits: \n - Submit no more than 4 unique users per request. Users are distinguished by the `uid` field in each transaction. \n - Submit no more than 16 transactions per user per request if sending multiple users. Send no more than 128 if sending a single user.\n"
operationId: syncCleanupTransactions
security:
- Authentication:
- enrichment
requestBody:
description: Transactions
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CleanupPostRequest'
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
enrichedTransactions:
type: object
properties:
enriched:
type: array
items:
type: object
properties:
accountid:
description: The ID of the account associated with the transaction
type: string
amountnum:
description: The transaction's USD amount
type: number
category:
description: The most applicable categorization for the transaction
type: string
categoryId:
description: The numeric ID of the transaction's category
type: number
categoryLabel:
description: A cascading hierarchy of the transaction's categories, from high-level to detail-level categorization. This field is deprecated and not recommended for use, as it may not reflect more correct information available in other 'category' fields.
type: array
deprecated: true
items:
type: string
client_id:
type: string
description: Your FinGoal client ID
container:
description: A high-level categorization of the account type. Eg, 'bank'
type: string
date:
description: The date on which the transaction took place
type: string
format: date-time
detailCategoryId:
description: The numeric ID of the transaction's detail category
type: number
guid:
description: The transaction's globally unique FinSight API issued ID
type: string
highLevelCategoryId:
description: The numeric ID of the transaction's high level category
type: number
isPhysical:
description: Whether the transaction was made at a physical location, or online
type: boolean
isRecurring:
deprecated: true
description: This field is deprecated. Denotes whether the transaction is set to recur on a fixed interval
type: boolean
merchantAddress1:
description: The street address of the merchant associated with the transaction
type: string
merchantCity:
description: The name of the city where the merchant is located
type: string
merchantCountry:
description: The name of the country where the merchant is located
type: string
merchantLatitude:
description: The latitude of the merchant
type: string
merchantLogoURL:
description: The URL resource for the merchant's logo
type: string
merchantLongitude:
description: The longitude of the merchant
type: string
merchantName:
description: The name of the merchant associated with the transaction
type: string
merchantPhoneNumber:
description: The phone number of the merchant associated with the transaction
type: string
merchantState:
description: The name of the state where the merchant is located
type: string
merchantType:
description: The merchant's type
type: string
merchantZip:
type: string
description: The ZIP code where the merchant is located
original_description:
description: The transaction description as received. This will not change
type: string
receiptDate:
description: The date on which FinSight API first received the transaction
type: string
format: date-time
requestId:
description: A unique ID for the request the transaction came in with, for debugging purposes
type: string
simple_description:
description: An easy-to-understand, plain-language transaction description
type: string
deprecated: true
simpleDescription:
description: An easy-to-understand, plain-language transaction description
type: string
sourceId:
description: The source of the transaction
type: string
subType:
description: A more detailed classification that provides further information on the type of transaction.
type: string
tenant_id:
description: The ID of the tenant associated with this transaction, if one was included.
type: string
transactionid:
description: The ID of the transaction as it was originally submitted
type: string
transactionTags:
description: The FinSight API issued tags for the transaction
type: array
items:
type: string
type:
description: An attribute describing the nature of the intent behind the transaction.
type: string
uid:
description: The ID of the user associated with the transaction, as originally submitted
type: string
failed:
type: array
items:
type: object
properties:
amountnum:
description: The transaction's USD amount
type: number
settlement:
description: The settlement type of the transaction (e.g., 'debit' or 'credit')
type: string
original_description:
description: The transaction description as received. This will not change
type: string
transactionid:
description: The ID of the transaction as it was originally submitted
type: string
date:
description: The date on which the transaction took place
type: string
format: date-time
accountType:
description: The type of account (e.g., 'checking')
type: string
uid:
description: The ID of the user associated with the transaction, as originally submitted
type: string
error_message:
type: string
description: A message describing why the transaction failed to enrich.
'400':
description: Bad request. An array of errors in the data will be returned. Fields not allowed or incorrectly formatted will be noted.
'401':
description: Unauthorized
/cleanup:
post:
tags:
- Enrichment
summary: Historical Transaction Enrichment
description: "The historical transaction enrichment endpoint is designed for enriching a large number of transactions. It is optimized to handle substantial payloads and efficiently process large backlogs of data.\n\nThis endpoint is asynchronous. A webhook will be sent to the provided URL when a batch of transactions has been enriched.\n \nTo maximize throughput for this endpoint, follow these guidelines: \n - Group transactions by `uid` and include all transactions for a single `uid` in the same payload.\n - Limit each request to approximately 1,000 transactions. The payload can include multiple uids. \n"
operationId: asyncCleanupTransactions
security:
- Authentication:
- enrichment
requestBody:
description: Transactions
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CleanupPostRequest'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/CleanupPost200Response'
'400':
description: Bad request. An array of errors in the data will be returned. Fields not allowed or incorrectly formatted will be noted.
'401':
description: Unauthorized
callbacks:
enrichment_result:
https://YOUR_CALLBACK_URI:
post:
security: []
summary: Enrichment Webhook
parameters:
- name: X-Webhook-Verification
in: header
required: true
schema:
type: string
description: A SHA-256 HMAC signature of the webhook payload that can be used to verify the authenticity of the webhook.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EnrichmentNotificationPostRequest'
/cleanup/streaming:
post:
tags:
- Enrichment
summary: Streaming Transaction Enrichment
description: "FinGoal's streaming transaction enrichment endpoint is designed for enriching daily user transactions or other smaller transaction batches. \n\nUnlike the historical transaction enrichment endpoint, the streaming transaction enrichment endpoint does not require any user segmentation. Requests that include many users (by uid) will not deteriorate the endpoint's performance.\n\nThis endpoint is asynchronous. A webhook will be sent to the provided URL when a batch of transactions has been enriched. For larger transaction sets, such as historical data, user the historical enrichment endpoint.\n\nTo maximize throughput for this endpoint, follow these guidelines: \n - Group transactions by \"uid\" and include all transactions for a single user in the same payload.\n - Limit each request to a total of approximately 1,000 transactions. \n - Transactions can be distributed among any number of users as long as the total number of transactions does not exceed 1,000.\n"
operationId: streamingCleanupTransactions
security:
- Authentication:
- enrichment
requestBody:
description: Transactions
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CleanupPostRequest'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/CleanupPost200Response'
'400':
description: Bad request. An array of errors in the data will be returned. Fields not allowed or incorrectly formatted will be noted.
'401':
description: Unauthorized
callbacks:
enrichment_result:
https://YOUR_CALLBACK_URI:
post:
security: []
summary: Enrichment Complete Notification
parameters:
- name: X-Webhook-Verification
in: header
required: true
schema:
type: string
description: A SHA-256 HMAC signature of the webhook payload that can be used to verify the authenticity of the webhook.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EnrichmentNotificationPostRequest'
/cleanup/base:
post:
tags:
- Enrichment
summary: Base Transaction Enrichment
description: "FinGoal's base transaction enrichment endpoint is a new and improved model for enriching daily user, historical, or one off user transactions. It accepts additional `accountTypes` that previous enrichment endpoints did not, including `businessChecking`, `businessSavings`, `businessCreditCard`, `businessLoan`, `loan`, `investments`.\n\nRequests that include many users (by uid) will not deteriorate the endpoint's performance and it has much higher throughput than previous enrichment endpoints. \n\nThis endpoint is asynchronous. A webhook will be sent to the provided URL when a batch of transactions has been enriched.\n\nTo maximize throughput for this endpoint, follow these guidelines: \n - Limit each request to a total of approximately 1,000 transactions. \n - Transactions can be distributed among any number of users as long as the total number of transactions does not exceed 1,000.\n"
operationId: baseCleanupTransactions
security:
- Authentication:
- enrichment
requestBody:
description: Transactions
required: true
content:
application/json:
schema:
type: object
required:
- transactions
properties:
transactions:
type: array
items:
type: object
required:
- accountType
- amountnum
- date
- original_description
- transactionid
- settlement
- uid
properties:
accountType:
type: string
description: 'The type of account associated with the transaction.
'
enum:
- checking
- savings
- creditCard
- businessChecking
- businessSavings
- businessCreditCard
- businessLoan
- loan
- investments
example: checking
amountnum:
type: number
maxLength: 11
description: The transaction amount in USD. Negative amounts are automatically converted to positive amounts. Use the 'settlement' field to indicate whether the transaction was a 'debit' or 'credit'. The string representation of amount must be fewer than 11 characters.
example: 19.99
date:
description: The date of the transaction. Must be in the format 'YYYY-MM-DD'.
type: string
f
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fingoal/refs/heads/main/openapi/fingoal-enrichment-api-openapi.yml