Download our postman collection here.

The 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:

1. Request a FinGoal developer account.
2. Obtain API access credentials.
3. Generate an Insights API authentication token.
4. Submit transactions to the Insights API.
5. Register for Webhooks.
6. Request Enrichment.

To use the Insights API, you need authentication credentials. These credentials can be obtained by requesting a FinGoal developer account. FinGoal developer support will send you development environment credentials within 24 hours. These credentials are required for the quickstart.

All 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.

1. Prepare the Request Body

The request body is a JSON object with the following structure:

{
    "client_id": "{YOUR_CLIENT_ID}",
    "client_secret": "{YOUR_CLIENT_SECRET}"
} 

2. Make a POST Request

Make a POST request to the Insights API authentication endpoint using the prepared JSON object.

const body = {
  "client_id": "{YOUR_CLIENT_ID}",
  "client_secret": "{YOUR_CLIENT_SECRET}"
}

const requestOptions = {
  method: 'POST',
  body: body,
};

try {
    const response = await fetch("https://findmoney-dev.fingoal.com/v3/authentication", requestOptions);
  const data = response.json();
    const { access_token } = data;
    console.log({ access_token });
} catch(error) {
    console.log('AUTHENTICATION_ERROR:', error);
}

The 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.

Successful Response

If the request is successful, the response body will contain a JSON object with the following structure:

• access_token: The JWT token used to authenticate requests to the Insights API.
• scope: The permissions that the token has.
• expires_in: The number of seconds until the token expires (always 86400 seconds, or 24 hours).
• token_type: The type of token. This value is always Bearer.

  {
    "access_token": "eyJh...",
    "scope": "read:transactions write:transactions ...",
    "expires_in": 86400,
    "token_type": "Bearer"
  }
  

  Best Practices

• Store the access_token securely. Do not expose it in client-side code.
• Use the expires_in value to determine when to refresh the token.
• Regenerate a new token only after the current token has expired.

To authenticate your requests to the Insights API, you must include the JWT token in the Authorization header. The header should have the following structure:

{
  "Authorization": "Bearer {YOUR_ACCESS_TOKEN}"
}

This 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.

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

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.

{
  "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.

  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.

{
  "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.

{
  "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.

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.

  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.

markdown/tagging.md

The Insights API's Savings Recommendations endpoints enable developers to provide users with personalized savings recommendations based on their transaction data. The recommendations are generated by analyzing the user's transaction history and identifying opportunities to save money. The API provides insights into potential savings opportunities, such as switching to a different credit card, opening a new savings account, or refinancing a loan.

The Savings Recommendations API requires developers to register a webhook endpoint to receive updates when new recommendations are available. Transactions submitted to the Savings Recommendations API do not contribute to the Insights API's user tagging capabilities.

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 with a single parameter, transactions. The format of these transactions depends on which transaction schema you are using. The savings recommendations API supports mx, plaid, and fingoal transaction schemas. Here is an example of a simple fingoal schema payload:

{
    "transactions": [
        {
            "uid": "example_user_id",
            "amountnum": 10.99,
            "date": "2022-10-01",
            "simple_description": "Target",
            "original_description": "TARGET #234 purchase ****1234 20221001",
            "transactionid": "sample_transaction_id"
        }
    ]
}

2. Make a POST Request

Make a POST request to the Savings Recommendations API endpoint using the prepared JSON object. Include the JWT in the Authorization header. Set the type header to the transaction schema you are using.

const headers = new Headers();
headers.append("Authorization", "Bearer {ACCESS_TOKEN}"
headers.append("type", "mx"); 

const requestOptions = {
  method: 'POST',
  headers: headers,
  body: body,
  redirect: 'follow'
}

try { 
    const response = await fetch("/v3/transactions", requestOptions);
    const data = response.json();
    console.log({ data });
} catch(error) {
    console.log({ error });
}

The JavaScript code above uses the fetch API to submit transactions to the Savings Recommendations API. If the request succeeds, it logs the response data. If an error occurs, it logs the error. The response includes metadata about the submitted transactions.

3. Listen for the New Recommendations Event

To receive a webhook notification for a new recommendation event, 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 new recommendations events.

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 for savings recommednations is a JSON object with a single parameter, finsights. The finsights parameter is an array of objects, each representing a single savings recommendation. Each recommendation object has the following fields:

• finsight_id: A unique identifier for the recommendation.
• uniqueId: A unique identifier for the recommendation that includes your client ID and transaction ID.
• user_id: The user ID associated with the recommendation.
• transaction_id: The transaction ID associated with the recommendation.
• insight_ctaurl: A URL for the call-to-action that can be used as an HREF for the recommendation text.
• finsight_image: A URL for an image relevant to the savings recommendation.
• insight_text: User-facing copy that describes the savings recommendation.
• recommendation: A title for the savings recommendation.
• amountFound: The estimated amount the user can expect to save if they were to follow the advice.
• category: The category of the savings recommendation.

  {
    "finsights": [
        {
            "finsight_id": "uuidv4",
            "uniqueId": "your_client_id:your_transaction_id",
            "user_id": "your_uid", 
            "transaction_id": "your_transaction_id",
            "insight_ctaurl": "http://example.com",
            "finsight_image": "https://example.com/example.jpg",
            "insight_text": "Get Target Red Card to save on your Target shopping!",
            "recommendation": "Target Red Card",
            "amountFound": 10.00,
            "category": "Shopping"
        } 
    ]
  }
  

  Best Practices

• Submit transactions in batches to reduce the number of API calls.
• Use unique uid and transactionid values for each user and transaction. Because the savings recommendations exclude fields from the orginal transaction data, it may be necessary to associate the savings recommendations back to the original transaction data in your system.
• Store the finsight_id and uniqueId values to track the recommendations in your system.
• Do not submit duplicate transaction IDs to the Savings Recommendations API. Duplicate transaction IDs will be ignored.

Usage Notes

• The Savings Recommendations API does not generate duplicate recommendations for the same user. If a user has already received a recommendation for a specific transaction, the API will not generate a new recommendation for that transaction.
• The API may take up to 24 hours to generate new recommendations for a given transaction.
• The API may generate multiple recommendations for a single transaction. Ensure your application can handle multiple recommendations for a single transaction.