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.

Once enrichment is complete, a webhook will be sent for each batch of data. 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.

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.

Make a call to https://findmoney-dev.fingoal.com/v3/cleanup 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

Request Fields

Location
Field
Format
Notes
Headers
required
Authorization
string
Authorization: Bearer {your_token}
required
Content-Type
string
Value should be application/json
Body
required
transactionid
string
GUID assigned to this transaction. Must be unique for this user.
required
amountnum
number
Dollar amount assigned to the transaction
required
original_description
string
Description for the transaction
required
uid
string
User id
required
accountType
string
options: creditCard, checking, savings
required
settlement
string
credit (as in refund) or debit
optional
accountid
string
User account associated with the transaction
optional
date
string
date the transaction occurred
optional
city
string
city where the transaction occurred
optional
zip_code
string
zip code where the transaction occurred

Example

curl --location --request POST 'https://findmoney-dev.fingoal.com/v3/cleanup' \
--header 'Authorization: Bearer {YOUR_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "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"
	  }]
}'

Example Data Enrichment Response

Although enriched transactions are returned by webhook, the enrichment API will send a synchronous response that indicates that the transaction data has been successfully submitted:

{
    "status": {
        "transactions_received": true,
        "transactions_validated": true,
        "processing": true,
        "num_transactions_processing": 250
    }
}

Webhooks

While the Data Enrichment API can process large payloads of transaction data, large batches take too long for data to be exchanged over a conventional HTTP request-response flow. As a result, all data from the data enrichment API is returned to the client over webhooks.

When you set up a client ID and a client secret in the developer dashboard, you can also set up a callback URI. The Data Enrichment API will target your callback URI endpoint with a POST request that contains the enriched data.

Webhook POST body Schema

Field Name
Field Type
enrichedTransactions
EnrichedTransaction[]

The body of the webhook has one field, enrichedTransactions, which contains enriched versions of the transactions sent to the enrichment API. Note that each request you make to enrichment can be broken up into multiple webhook payloads, so each individual webhook will contain only a portion of the enriched data, rather than every enriched records.

If necessary, you may use the uid and transactionid fields on the returned transaction objects to associate them with the originating transaction in your own data store.

Example Webhook Body

{
	"enrichedTransactions": [{
		"type":"PURCHASE",
		"subType":"PURCHASE",
		"merchantCountry":"US",
		"container":"bank",
		"merchantLogoURL":"https://assets.brandfetch.io/41d9e18b197d42c.svg",
		"is_physical":true,
		"is_recurring":false,
		"categoryLabel": [
			"Transportation",
			" Gas Stations"
		],
		"sourceId":"2bd359ec-659d-4416-985d-7fc29bb18a4f",
		"merchantName":"Gas Station",
		"highLevelCategoryId":10000003,
		"categoryId":8,
		"merchantType":"OTHERS",
		"simpleDescription":"Gas Station",
		"detailCategoryId":1266,
		"category":"Gasoline/Fuel",
		"amountnum":512,
		"date":"2018-09-18T00:00:00.000Z",
		"transactionid":"2bd359ec-659d-4416-985d-7fc29bb18a4f",
		"receiptDate":"2022-10-04T19:08:01.120Z",
		"original_description":"Gas Station",
		"uid":"your_users_id",
		"client_id":"your_client_id",
	}]
}

Enriched Transaction Schema

Enriched Transaction Data

Field Name
Type
Additional Notes
amountnum
number
category
string
categoryId
number
categoryLabel
string[]
client_id
string
Will be equivalent to the client_id used to generate the auth token.
container
string
date
string
detailCategoryId
number
highLevelCategoryId
number
is_physical
boolean
is_recurring
boolean
merchantAddress1
string
merchantCity
string
merchantCountry
string
merchantLatitude
string
merchantLogoURL
string
merchantLongitude
string
merchantName
string
merchantPhoneNumber
string
merchantState
string
merchantType
string
merchantZip
string
requestId
string
simpleDescription
string
sourceId
string
subType
string
transactionid
string
Will be equivalent to the transactionid used on the original record.
type
string
uid
string
Will be equivalent to the user ID used when submitting the transaction.
{
	"transactions": [{
    "amountnum": 12.41,
    "category": "General Merchandise",
    "categoryId": 44,
    "categoryLabel": [
        "Retail",
        "Department Stores"
    ],
    "client_id": "yourClientId",
    "container": "creditCard",
    "date": "2019-10-11"
    "detailCategoryId": 1306,
    "highLevelCategoryId": 10000010,
    "is_physical": true,
    "is_recurring": false,
    "merchantAddress1": "2800 pearl street",
    "merchantCity": "Boulder",
    "merchantCountry": "US",
    "merchantLatitude": "40.02174",
    "merchantLogoURL": "https://assets.brandfetch.io/34127434d4534cb.svg",
    "merchantLongitude": "-105.25631",
    "merchantName": "Target",
    "merchantPhoneNumber": "3034493400",
    "merchantState": "CO",
    "merchantType": "OTHERS",
    "merchantZip": "80301",
    "requestId": "eba963ac-8a62-4df7-a064-dfa617e21347",
    "simpleDescription": "Target",
    "sourceId": "988cee06-5d36-11ec-b00b-bc8d8f2303a12733",
    "subType": "PURCHASE",
    "transactionid": "988cee06-5d36-11ec-b00b-bc8d8f2303a12733",
    "type": "PURCHASE",
    "uid": "16432789fdsa78"
  }]
}

Category Reference

Category Logos.csv3.3KB

Category
Category Logo URL
Advertising
ATM/Cash Withdrawals
Automotive Expenses
Business Miscellaneous
Cable/Satellite Services
Charitable Giving
Checks
Child/Dependent Expenses
Clothing/Shoes
Consulting
Credit Card Payments
Deposits
Dues and Subscriptions
Education
Electronics
Entertainment
Expense Reimbursement
Gasoline/Fuel
General Merchandise
Gifts
Groceries
Healthcare/Medical
Hobbies
Home Improvement
Home Maintenance
Insurance
Interest
Investment Income
Loans
Mortgages
Office Maintenance
Office Supplies
Online Services
Other Bills
Other Expenses
Other Income
Paychecks/Salary
Personal Care
Pets/Pet Care
Postage and Shipping
Printing
Refunds/Adjustments
Rent
Restaurants/Dining
Retirement Contributions
Retirement Income
Rewards
Sales
Savings
Securities Trades
Service Charges/Fees
Services
Taxes
Telephone Services
Transfers
Travel
Utilities
Wages Paid

Common Errors and Issues

Code
Error
Issue
401
UnauthorizedError: secret or public key must be provided
No authorization token/bad authorization was passed in. Please check your credentials and retry your request.
400
Bad Request
An array of errors in the data will be returned. Fields not allowed or incorrectly formatted will be noted.