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.