Insights API (3.1.2)

Download OpenAPI specification:Download

Overview

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.

Request a FinGoal Developer Account

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.

Quickstart

Generate a JWT Authentication Token

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.

Include the JWT Token in Requests

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.

Enrichment

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.

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.
{
  "transactions": [
    {
      "uid": "16432789fdsa78",
      "accountid": "1615",
      "amountnum": 12.41,
      "date": "5/11/24",
      "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": "5/11/24",
        "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.

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.

Test Transaction Enrichment

The test transaction enrichment endpoint provides immediate enrichment on transaction data. This endpoint is ideal for testing API functionality and previewing enrichment results.

This endpoint is not intended for production use. Use the historical and streaming endpoints for production-level enrichment.

For optimal performance, adhere to the following limits:

  • Submit no more than 4 unique users per request. Users are distinguished by the uid field in each transaction.
  • Submit no more than 16 transactions per user per request if sending multiple users. Send no more than 128 if sending a single user.
SecurityAuthentication
Request
Request Body schema: application/json
required

Transactions

required
Array of objects
Responses
200

Success

400

Bad request. An array of errors in the data will be returned. Fields not allowed or incorrectly formatted will be noted.

401

Unauthorized

post/cleanup/sync
Request samples
application/json
{
  • "transactions": [
    ]
}
Response samples
application/json
{
  • "enrichedTransactions": [
    ]
}

Historical Transaction Enrichment

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.

This endpoint is asynchronous. A webhook will be sent to the provided URL when a batch of transactions has been enriched.

To maximize throughput for this endpoint, follow these guidelines:

  • Group transactions by uid and include all transactions for a single uid in the same payload.
  • Limit each request to approximately 1,000 transactions. The payload can include multiple uids.
SecurityAuthentication
Request
Request Body schema: application/json
required

Transactions

required
Array of objects
Responses
200

Success

400

Bad request. An array of errors in the data will be returned. Fields not allowed or incorrectly formatted will be noted.

401

Unauthorized

Callbacks
postEnrichment Webhook
post/cleanup
Request samples
application/json
{
  • "transactions": [
    ]
}
Response samples
application/json
{
  • "status": {
    }
}
Callback payload samples
POST: Enrichment Webhook
application/json
{
  • "batch_request_id": "5f4b1b9b-4b7d-4b7d-4b7d-4b7d4b7d4b7d"
}

Streaming Transaction Enrichment

FinGoal's streaming transaction enrichment endpoint is designed for enriching daily user transactions or other smaller transaction batches.

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

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

To maximize throughput for this endpoint, follow these guidelines:

  • Group transactions by "uid" and include all transactions for a single user in the same payload.
  • Limit each request to a total of approximately 1,000 transactions.
  • Transactions can be distributed among any number of users as long as the total number of transactions does not exceed 1,000.
SecurityAuthentication
Request
Request Body schema: application/json
required

Transactions

required
Array of objects
Responses
200

Success

400

Bad request. An array of errors in the data will be returned. Fields not allowed or incorrectly formatted will be noted.

401

Unauthorized

Callbacks
postEnrichment Complete Notification
post/cleanup/streaming
Request samples
application/json
{
  • "transactions": [
    ]
}
Response samples
application/json
{
  • "status": {
    }
}
Callback payload samples
POST: Enrichment Complete Notification
application/json
{
  • "batch_request_id": "5f4b1b9b-4b7d-4b7d-4b7d-4b7d4b7d4b7d"
}

Retrieve Enrichment by Batch Request ID

Developers may use this endpoint in conjunction with the asynchronous cleanup endpoints to retrieve the results of a transaction cleanup operation by its batch operation ID. The operation ID can be extracted from the webhook that the async cleanup endpoint sends when enrichment is complete.

SecurityAuthentication
Request
path Parameters
batch_request_id
required
string

The Batch Request ID of the enrichment request.

Responses
200

Success

401

Unauthorized

404

No transactions found for the given request id.

get/cleanup/{batch_request_id}
Request samples
Response samples
application/json
{
  • "enrichedTransactions": [
    ],
  • "failedTransactions": [
    ]
}

User Tagging

markdown/tagging.md

Get a User

This endpoint runs on data sent to the Transaction Enrichment endpoints. It can take up to 30 minutes for user tagging results to appear following transaction upload.

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.

SecurityAuthentication
Request
path Parameters
userId
required
string

The ID for the user you want to retrieve.

header Parameters
include_tagged_transactions
string

Set to true to include all of the user's tagged transactions in the response. By default, tagged transactions are not included.

Responses
200

Success

401

Unauthorized

404

User ID could not be found

get/users/{userId}
Request samples
Response samples
application/json
{
  • "user": {
    },
  • "transactions": [
    ]
}

Trigger a User Tag Update

This endpoint runs on data sent to the Transaction Enrichment endpoints. It can take up to 30 minutes for user tagging results to appear following transaction upload.

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.

SecurityAuthentication
Request
path Parameters
userId
required
string

The ID for the user you want to retrieve.

header Parameters
include_tagged_transactions
string

Set to true to include all of the user's tagged transactions in the response. By default, tagged transactions are not included.

Responses
200

Success

401

Unauthorized

404

User ID could not be found

get/users/{userId}/sync
Request samples
Response samples
application/json
{
  • "user": {
    },
  • "transactions": [
    ]
}

Savings Recommendations

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.

Savings Recommendations 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 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.

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.

Upload Transactions

Post transaction data from your preferred aggregator.

SecurityAuthentication
Request
header Parameters
subtenant-id
string

A valid subtenant ID, if desired.

type
string

The type of transactions you are submitting to the API. Defaults to fingoal if not included.

Enum: "fingoal" "plaid" "mx"
Request Body schema: application/json
required

Transactions

One of:
required
Array of objects
Responses
200

Success

400

The request failed validation.

401

Unauthorized

Callbacks
postFinSights are returned for a subset of your transaction data.
post/transactions
Request samples
application/json
{
  • "transactions": [
    ]
}
Response samples
application/json
{
  • "message": "string"
}
Callback payload samples
POST: FinSights are returned for a subset of your transaction data.
application/json
{
  • "category": "string",
  • "finsight_image": "http://example.com",
  • "insight_ctaurl": "http://example.com",
  • "insight_text": "string",
  • "transaction_id": "string",
  • "uniqueId": "string",
  • "user_id": "string",
  • "amountFound": "string",
  • "finsightDate": "2019-08-24",
  • "recommendation": "string",
  • "retries": 0,
  • "webhookSent": true,
  • "webhookUri": "http://example.com",
  • "lastAttempt": "2019-08-24"
}

Get a Specific Savings Recommendation

Get a specific Call to Action, associated with a specific transaction record

SecurityAuthentication
Request
path Parameters
finsightId
required
string

The ID of the Savings recommendation you want to retrieve. This should match the ID of the transaction that you sent in.

Responses
200

The Savings Recommendation was successfully returned.

401

Unauthorized

404

The requested Savings Recommendation could not be found.

get/finsights/{finsightId}
Request samples
Response samples
application/json
{
  • "category": "string",
  • "finsight_image": "http://example.com",
  • "insight_ctaurl": "http://example.com",
  • "insight_text": "string",
  • "transaction_id": "string",
  • "uniqueId": "string",
  • "user_id": "string",
  • "amountFound": "string",
  • "finsightDate": "2019-08-24",
  • "recommendation": "string",
  • "retries": 0,
  • "webhookSent": true,
  • "webhookUri": "http://example.com",
  • "lastAttempt": "2019-08-24"
}

Get Many Savings Recommendations

View all the savings recommendations your client have received.

SecurityAuthentication
Request
query Parameters
startAt
string

UNIX timestamp of the oldest FinSight you wish to view.

endAt
string

UNIX timestamp of the newest FinSight you wish to view.

Responses
200

Savings Recommendations successfully returned.

400

One or both of the 'startAt' and 'endAt' in the query were unexpected. The UNIX dates may be malformed, or the interval between them could not be defined.

401

Unauthorized.

get/finsights
Request samples
Response samples
application/json
{
  • "finsights": [
    ]
}