Transaction Enrichment

Transaction Enrichment

Transaction Enrichment

The FinSight API clarifies transaction descriptions, adds location information, and infers additional transactional metadata to offer a more complete picture of user spending.

Data enrichment is completed by sending transactions to FinSightAPI /v3/cleanup endpoint. An authorization token is required in the headers, and the data to be enriched is required in the request body.

We currently offer synchronous and asynchronous flows. If you’d like to receive the enriched data back in the response, you can use https://findmoney-dev.fingoal.com/v3/cleanup/sync. If you’d prefer to send fewer, larger requests and get the response back in asynchronously via webhook, use https://findmoney-dev.fingoal.com/v3/cleanup. Everything else about the request is the same, just change the endpoint.

Responses are sent on a per-user basis. If you pass a request in with 100 transactions from a single user, you will be sent a single webhook when the request is completed. If you send a request with 100 transactions from 3 separate users, you will be sent 3 webhooks as the requests are completed for each user’s data. Synchronous requests with multiple users will return an array for each user’s transactions.

Quickstart Guide

If you haven’t done so already, follow the FinSight Quickstart guide to sign up for our developer portal, get your credentials, and generate an access token. The access token is specific to your client ID, and will grant 24-hour access to the Data Enrichment endpoint, at which time you must regenerate it. Once you have a valid access token, you’re ready to proceed with cleaning up transactions.

Then just make a call to your preferred endpoint with your token and a valid transaction body - refer to the Data Enrichment Request section in this document for a transaction schema.

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {YOUR_TOKEN}");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({
  "transactions": [
    {
      "uid": "16432789fdsa78",
      "accountid": "1615",
      "amountnum": 12.41,
      "date": "10/11/19",
      "original_description": "T0064 TARGET STORE",
      "transactionid": "988cee06-5d36-11ec-b00b-bc8d8f2303a12733",
			"accountType" : "creditCard",
			"settlement": "debit"
    }
  ]
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://findmoney-dev.fingoal.com/v3/cleanup", requestOptions)
  .then(response => response.json())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Example Data Enrichment Request

Example Async Data Enrichment Response

Example Sync Data Enrichment Response

Webhooks

Enriched Transaction Schema

Common Errors and Issues

List of Available Persona Tags

List of Available Categories

User Tagging

FinSightAPI provides endpoints for fetching user and transaction tags that help characterize spending behavior. The tags are useful for understanding customers' spending habits and preferences.

While transaction tags can be retrieved from the cleanup endpoints and webhooks, user tags and transaction tags are also accessible at two additional dedicated endpoints:

  1. GET /v3/users/:userId
  2. GET /v3/users/:userId/sync

The primary difference between the two is that the /sync route will re-run the tagging process to ensure the most up-to-date representation of tags is returned.

Authentication

These endpoints require authentication using an OAuth 2.0 Client Credentials JWT. Make sure to include the Authorization header with the token in the format Bearer <your_token>.

GET v3/users/:userId , GET v3/users/:userId/sync

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.

Request Parameters

  • userId, the string ID of the user.

Request Headers

  • include_tagged_transactions (optional): Set to true to include tagged transactions in the response. By default, tagged transactions are not included.

Response Schema

Field
Type
Description
Nullable?
user
Object
Contains user information and user tags
user.client_id
String
Client Identifier
user.registrationDate
String (ISO Date)
User’s registration date
Yes
user.subtenantId
String
Subtenant Idenfier
Yes
user.totaltransactions
Number
Total number of user transactions
Yes
uid
String
user identifier
user.tags
String[]
User tags
Yes
tagged_transactions
Transaction[]
Contains all tagged transactions.
transaction.transaction_id
String
Transaction identifier
transaction.simple_description
String
Simplified transaction description
transaction.original_description
String
Original transaction description.
transaction.category
String
Transaction category
transaction.amount
Number
Transaction amount
transaction.date
String (ISO Date)
Transaction date
transaction.transactionTags
String[]
Transaction tags

Example Response

{
  "user": {
    "id": "12345",
    "uniqueId": "my_client_id:my_uid",
    "client_id": "my_client_id",
    "lifetimeSavings": null,
    "registrationDate": null,
    "subtenantId": null,
    "totaltransactions": null,
    "transactionsSinceLastUpdate": null,
    "uid": "my_uid",
    "tags": [
      "Fast Foodie"
    ]
  },
  "transactions": [
    {
      "transaction_id": "my_transaction_id",
      "simple_description": "Chick-fil-A",
      "original_description": " CHICK-FIL-A",
      "category": "Restaurants/Dining",
      "amount": -24.38,
      "date": "2023-03-29T00:00:00.000Z",
      "tags": [
        "Eating Out",
        "Fast Food"
      ]
    }
  ]
}