openapi: 3.1.0
info:
title: Insights Enrichment Webhook Configurations API
description: "# Overview\n[Download our postman collection here.](https://fingoal.dev/FinGoal%20Enrichment.postman_collection.json)\n\nThe 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: \n1. Request a FinGoal developer account.\n2. Obtain API access credentials.\n3. Generate an Insights API authentication token. \n4. Submit transactions to the Insights API. \n5. Register for Webhooks.\n6. Request Enrichment.\n\n## Important Resources\n- [Complete Insights API Tag Registry](https://fingoal.com/tags-list)\n- [Complete Insights API Categorization Spreadsheet](https://docs.google.com/spreadsheets/d/1jnmw1LriclC3bO-oC7f7EkhmfCL7gw2LQLX8zay1vXw/edit?gid=0#gid=0)\n\n## Request a FinGoal Developer Account\nTo use the Insights API, you need authentication credentials. These credentials can be obtained by <a href=\"https://fingoal.com/request-developer-account\" target=\"_blank\"> requesting a FinGoal developer account</a>. FinGoal developer support will send you development environment credentials within 24 hours. These credentials are required for the quickstart. \n# Quickstart\n## Generate a JWT Authentication Token\nAll 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. \n\n### 1. Prepare the Request Body\nThe request body is a JSON object with the following structure:\n```json\n{\n\t\"client_id\": \"{YOUR_CLIENT_ID}\",\n\t\"client_secret\": \"{YOUR_CLIENT_SECRET}\"\n} \n```\n### 2. Make a POST Request\nMake a POST request to the Insights API authentication endpoint using the prepared JSON object.\n```js\nconst body = {\n \"client_id\": \"{YOUR_CLIENT_ID}\",\n \"client_secret\": \"{YOUR_CLIENT_SECRET}\"\n}\n\nconst requestOptions = {\n method: 'POST',\n body: body,\n};\n\ntry {\n\tconst response = await fetch(\"https://findmoney-dev.fingoal.com/v3/authentication\", requestOptions);\n const data = response.json();\n\tconst { access_token } = data;\n\tconsole.log({ access_token });\n} catch(error) {\n\tconsole.log('AUTHENTICATION_ERROR:', error);\n}\n```\nThe 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. \n\n### Successful Response\nIf the request is successful, the response body will contain a JSON object with the following structure:\n- `access_token`: The JWT token used to authenticate requests to the Insights API.\n- `scope`: The permissions that the token has.\n- `expires_in`: The number of seconds until the token expires (always 86400 seconds, or 24 hours). \n- `token_type`: The type of token. This value is always `Bearer`.\n```json\n{\n \"access_token\": \"eyJh...\",\n \"scope\": \"read:transactions write:transactions ...\",\n \"expires_in\": 86400,\n \"token_type\": \"Bearer\"\n}\n```\n### Best Practices \n- Store the `access_token` securely. Do not expose it in client-side code.\n- Use the `expires_in` value to determine when to refresh the token.\n- Regenerate a new token only after the current token has expired.\n\n## Include the JWT Token in Requests\nTo authenticate your requests to the Insights API, you must include the JWT token in the `Authorization` header. The header should have the following structure:\n```json\n{\n \"Authorization\": \"Bearer {YOUR_ACCESS_TOKEN}\"\n}\n```\nThis 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.\n\n## Tenancy \nInsights API supports the concept of tenancy. A `tenant` refers to a grouping of customer data (users, transactions, tags, accounts, etc.) that may be accessible to multiple clients. By default, a new client’s connection to the InsightsAPI does not use tenancy; however, they may enable tenancy at any time.\n\nCurrently, Insights API does not allow you to create custom tenants. The FinGoal customer support team needs to coordinate with both the client & tenant parties to set up a new connection. If a client’s request for access to a tenant is approved, FinGoal will send the client an identifier for the tenant, and authorize them to access that tenant’s resources. \n\nTo interact with the Insights API on behalf of a tenant, include a tenant_id in your Insights API token request: \n\n```js\nconst response = await fetch(\"{INSIGHTS_API_BASE_URL}/v3/authentication\", {\n\t\tmethod: \"POST\",\n\t\tdata: {\n\t\t\t\tclient_id: \"{MY_CLIENT_ID}\",\n\t\t\t\tclient_secret: \"{MY_CLIENT_SECRET}\",\n\t\t\t\ttenant_id: \"{TENANT_ID_FROM_FINGOAL}\"\n\t\t}\n});\n```\n\nBy including the `tenant_id` in your token scopes, the generated token allows you to: \n\n- Write data to the tenant’s environment.\n- Read data from the tenant’s environment.\n\n<aside>\nIf you do not include a tenant ID, your token will only allow you to access data you have created without a specific tenant association. \n</aside>\n\nAs soon as you are successfully added to a tenant’s data silo, you will begin receiving webhook updates for all activity in that silo. Note that this may include new enrichment data that is added to the environment by clients other than yourself. Refer to the webhook documentation for more information on the content of Insights API webhooks."
version: 3.1.3
servers:
- url: https://findmoney-dev.fingoal.com/v3
description: Insights API Development
- url: https://findmoney.fingoal.com/v3
description: Insights API Production
security:
- Authentication: []
tags:
- name: Webhook Configurations
description: Manage webhook callback URLs for your client. Supports default and tenant-specific configurations per webhook type.
paths:
/webhook-configurations:
get:
tags:
- Webhook Configurations
summary: List Webhook Configurations
description: 'Retrieve all webhook configurations for your client. Configurations are organized into:
- **default**: Configurations without a tenant_id that apply to your client''s default callback URL
- **tenants**: Tenant-specific configurations organized by tenant_id
'
operationId: listWebhookConfigurations
security:
- Authentication:
- enrichment
responses:
'200':
description: Successfully retrieved webhook configurations.
content:
application/json:
schema:
type: object
properties:
webhook_configurations:
type: object
description: All webhook configurations for your client, organized by scope.
properties:
client:
type: array
description: Default webhook configurations (no tenant_id). These apply when no tenant-specific configuration exists.
items:
$ref: '#/components/schemas/WebhookConfigurationsPut200Response'
by_tenant:
type: object
description: Tenant-specific webhook configurations. Keys are tenant public IDs, values are arrays of configurations for that tenant.
additionalProperties:
type: array
items:
$ref: '#/components/schemas/WebhookConfigurationsPut200Response'
example:
TEN-123456:
- id: 2
client_id: your-client-id
tenant_id: TEN-123456
webhook_type: ENRICHMENT_DATA
callback_url: https://tenant-specific.com/webhooks/enrichment
created_at: '2024-01-15T11:00:00.000Z'
updated_at: '2024-01-15T11:00:00.000Z'
'400':
description: client_id header is required.
'401':
description: Unauthorized.
'403':
description: Missing required `enrichment` scope.
put:
tags:
- Webhook Configurations
summary: Create or Update Webhook Configuration
description: 'Create a new webhook configuration or update an existing one. Your `client_id` and `tenant_id` are automatically inferred from the bearer token on this request. To set up a webhook for a specific tenant, please ensure that the bearer token on this request as a `tenant_id` claim. If your bearer token lacks a `tenant_id`, the webhook will be created for your single-tenant environment.
- If a configuration already exists for the same client/tenant/webhook_type combination, it will be updated.
- If `tenant_id` is provided, your client must have a relationship with that tenant.
- Omit `tenant_id` to set the default callback URL for your client.
'
operationId: upsertWebhookConfiguration
security:
- Authentication:
- enrichment
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- webhook_type
- callback_url
properties:
webhook_type:
$ref: '#/components/schemas/WebhookConfigurationsPutRequest'
callback_url:
type: string
format: uri
description: Valid HTTPS URL for webhook delivery.
example: https://your-server.com/webhooks/enrichment
responses:
'200':
description: Webhook configuration created or updated successfully.
content:
application/json:
schema:
type: object
properties:
webhook_configuration:
$ref: '#/components/schemas/WebhookConfigurationsPut200Response'
'400':
description: 'Bad request. Possible errors:
- `client_id header is required`
- `webhook_type is required`
- `Invalid webhook_type`
- `callback_url is required`
- `callback_url must be a valid URL`
'
'401':
description: Unauthorized.
'403':
description: 'Forbidden. Possible errors:
- Missing `enrichment` scope
- Client does not have a relationship with the specified tenant
'
delete:
tags:
- Webhook Configurations
summary: Delete Webhook Configuration
description: 'Remove a webhook configuration.
- Specify `tenant_id` to delete a tenant-specific configuration.
- Omit `tenant_id` to delete the default configuration.
'
operationId: deleteWebhookConfiguration
security:
- Authentication:
- enrichment
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- webhook_type
properties:
webhook_type:
$ref: '#/components/schemas/WebhookConfigurationsPutRequest'
responses:
'200':
description: Webhook configuration deleted successfully.
content:
application/json:
schema:
type: object
properties:
deleted:
type: boolean
description: Whether the configuration was successfully deleted.
example: true
id:
type: integer
description: The ID of the deleted configuration.
example: 1
'400':
description: 'Bad request. Possible errors:
- `client_id header is required`
- `webhook_type is required`
- `Invalid webhook_type`
'
'401':
description: Unauthorized.
'403':
description: Missing required `enrichment` scope.
'404':
description: Webhook configuration not found.
/webhook-configurations/test:
post:
tags:
- Webhook Configurations
summary: Test Webhook
description: 'Test your webhook endpoint by triggering a sample payload. Useful for verifying your webhook receiver is working correctly.
The test payload varies by webhook type:
- **ENRICHMENT_DATA**: Sample enriched transactions payload
- **ENRICHMENT_NOTIFICATION**: Sample batch notification with batch_request_id
- **USER_TAGS_DATA**: Sample user tags payload with created/deleted/modified arrays
- **USER_TAGS_NOTIFICATION**: Sample notification with guid
- **INSIGHTS**: Sample finsights array
All test webhooks include the `X-Webhook-Verification` header for signature verification testing.
'
operationId: testWebhook
security:
- Authentication:
- enrichment
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- webhook_type
- callback_url
properties:
webhook_type:
$ref: '#/components/schemas/WebhookConfigurationsPutRequest'
callback_url:
type: string
format: uri
description: URL to send the test payload to.
example: https://your-server.com/webhooks/enrichment
responses:
'200':
description: Test webhook result.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: Whether the test webhook was successfully delivered.
example: true
status:
type: integer
description: The HTTP status code returned by the callback URL.
example: 200
message:
type: string
description: A message describing the result of the test.
example: Test webhook sent successfully
'400':
description: 'Bad request. Possible errors:
- `client_id header is required`
- `webhook_type is required`
- `Invalid webhook_type`
- `callback_url is required`
- `callback_url must be a valid URL`
'
'401':
description: Unauthorized.
'403':
description: Missing required `enrichment` scope.
x-webhook-payloads:
ENRICHMENT_DATA:
description: Data-rich Transaction Enrichment webhook payload.
schema:
$ref: '#/components/schemas/WebhookConfigurationsTestPostENRICHMENT_DATA'
ENRICHMENT_NOTIFICATION:
description: Non-data-rich Enrichment notification payload.
schema:
type: object
properties:
batch_request_id:
type: string
format: uuid
description: UUID to fetch enriched data from the `/cleanup/{batch_request_id}` endpoint.
client_id:
type: string
description: Your client identifier.
tenant_id:
type: string
description: Tenant identifier (if tenant-specific).
USER_TAGS_DATA:
description: Data-rich User Tags webhook payload.
schema:
$ref: '#/components/schemas/WebhookConfigurationsTestPostUSER_TAGS_DATA'
USER_TAGS_NOTIFICATION:
description: Non-data-rich User Tags notification payload.
schema:
type: object
properties:
guid:
type: string
format: uuid
description: UUID to fetch tag data from the `/users/tags/{guid}` endpoint.
tenant_id:
type: string
description: Tenant identifier (if tenant-specific).
INSIGHTS:
description: Finsights webhook payload.
schema:
type: object
properties:
finsights:
type: array
items:
type: object
properties:
finsight_id:
type: string
format: uuid
description: Unique identifier for this finsight.
uniqueId:
type: string
description: Unique identifier linking to the source.
transaction_id:
type: string
description: Related transaction identifier.
user_id:
type: string
description: User identifier.
insight_text:
type: string
description: Human-readable insight/advice text.
insight_ctaurl:
type: string
nullable: true
description: Call-to-action URL (if applicable).
finsight_image:
type: string
nullable: true
description: Image URL (if applicable).
recommendation:
type: string
nullable: true
description: Actionable recommendation.
amountFound:
type: number
description: Dollar amount related to the insight.
category:
type: string
description: Transaction category.
amountnum:
type: number
description: Transaction amount.
estimatedSavingsType:
type: string
description: Savings estimation period (e.g., "monthly").
components:
schemas:
WebhookConfigurationsPut200Response:
type: object
properties:
id:
type: integer
description: The unique identifier for this webhook configuration.
example: 1
client_id:
type: string
description: Your client identifier.
example: your-client-id
tenant_id:
type:
- string
- 'null'
description: The tenant public ID for tenant-specific configurations. Null for default configurations.
example: TEN-123456
webhook_type:
$ref: '#/components/schemas/WebhookConfigurationsPutRequest'
callback_url:
type: string
format: uri
description: The HTTPS URL where webhooks will be delivered.
example: https://your-server.com/webhooks/enrichment
created_at:
type: string
format: date-time
description: The timestamp when this configuration was created.
example: '2024-01-15T10:00:00.000Z'
updated_at:
type: string
format: date-time
description: The timestamp when this configuration was last updated.
example: '2024-01-15T10:00:00.000Z'
WebhookConfigurationsTestPostUSER_TAGS_DATA:
type: object
properties:
tenant_id:
type: string
description: The ID of the tenant for the users included in this update, if they are from a tenant environment.
userTags:
type: object
properties:
created:
description: A list of the new user tags that were generated for this user since the last user tagging update. A full list of the user tags can be accessed [here](https://fingoal.com/tags-list).
type: array
items:
type: object
properties:
user_id:
description: The user who received this tag. Corresponds to whatever 'uid' you initially uploaded to the enrichment.
type: string
example: '409088'
user_tag_id:
description: The ID of the tag that has been applied.
type: integer
example: 61
tag_name:
description: The name of the tag that has been applied.
type: string
example: Home Improvement Loan
deleted:
description: A list of the user tags that were removed from this user since the last user tagging update.
type: array
items:
type: object
properties:
user_id:
description: The user who received this tag. Corresponds to whatever 'uid' you initially uploaded to the enrichment.
type: string
example: '409088'
user_tag_id:
description: The ID of the tag that has been removed.
type: integer
example: 46
tag_name:
description: The name of the tag that has been removed.
type: string
example: Movie Goer
modified:
description: For incremental (that is, scored) user tags. Contains all scoring changes for any incremental user tags that have received a score change since the last update.
type: array
items:
type: object
properties:
user_id:
description: The user who received this tag. Corresponds to whatever 'uid' you initially uploaded to the enrichment.
type: string
example: '409088'
user_tag_id:
description: The ID of the tag that has been updated.
type: integer
example: 46
tag_name:
description: The name of the tag that has been updated.
type: string
example: Movie Goer
previous_value:
description: The last value for this tag's score, prior to this update.
type: integer
example: 50
new_value:
description: The new value for this tag's score.
type: integer
example: 75
delta:
description: The amount by which this tag's score has changed. Can be negative or positive. Will be the difference between the new_value and previous_value fields.
type: integer
example: 25
WebhookConfigurationsPutRequest:
type: string
enum:
- ENRICHMENT_DATA
- ENRICHMENT_NOTIFICATION
- USER_TAGS_DATA
- USER_TAGS_NOTIFICATION
- INSIGHTS
description: 'The type of webhook to configure:
- `ENRICHMENT_DATA`: Data-rich Transaction Enrichment webhooks (full payload)
- `ENRICHMENT_NOTIFICATION`: Non-data-rich Enrichment webhooks (notification only, fetch data from the `/cleanup/{batch_request_id}` endpoint)
- `USER_TAGS_DATA`: Data-rich User Tags webhooks (full payload)
- `USER_TAGS_NOTIFICATION`: Non-data-rich User Tags webhooks (notification only)
- `INSIGHTS`: Finsights/insights webhooks
'
WebhookConfigurationsTestPostENRICHMENT_DATA:
type: object
properties:
enrichedTransactions:
type: array
items:
type: object
properties:
accountid:
description: The ID of the account associated with the transaction
type: string
accountType:
description: The type of account associated with the transaction (e.g., 'checking', 'savings')
type: string
amountnum:
description: The transaction's USD amount
type: number
category:
description: The most applicable categorization for the transaction
type: string
categoryId:
description: The numeric ID of the transaction's category
type: number
categoryLabel:
deprecated: true
description: A cascading hierarchy of the transaction's categories, from high-level to detail-level categorization. This field is deprecated and not recommended for use, as it may not reflect more correct information available in other 'category' fields.
type: array
items:
type: string
address:
description: The address associated with the transaction
type:
- string
- 'null'
example: 123 Main St
city:
description: The city associated with the transaction
type:
- string
- 'null'
example: Urbana
client_id:
type: string
description: Your FinGoal client ID
container:
description: A high-level categorization of the account type. Eg, 'bank'
type:
- string
- 'null'
example: Transaction
date:
description: The date on which the transaction took place
type: string
format: date-time
detailCategoryId:
description: The numeric ID of the transaction's detail category
type: number
guid:
description: The transaction's globally unique FinSight API issued ID
type: string
highLevelCategoryId:
description: The numeric ID of the transaction's high level category
type: number
isPhysical:
description: Whether the transaction was made at a physical location, or online
type:
- boolean
- 'null'
example: true
isRecurring:
deprecated: true
description: This field is deprecated. Denotes whether the transaction is set to recur on a fixed interval
type:
- boolean
- 'null'
example: false
merchantAddress1:
description: The street address of the merchant associated with the transaction
type:
- string
- 'null'
example: 123 Main St
merchantCity:
description: The name of the city where the merchant is located
type:
- string
- 'null'
example: Urbana
merchantCountry:
description: The name of the country where the merchant is located
type:
- string
- 'null'
example: US
merchantLatitude:
description: The latitude of the merchant
type:
- string
- 'null'
example: '38.9517'
merchantLogoURL:
description: The URL resource for the merchant's logo
type: string
merchantLongitude:
description: The longitude of the merchant
type:
- string
- 'null'
example: '-92.3341'
merchantName:
description: The name of the merchant associated with the transaction
type:
- string
- 'null'
example: Dollar General
merchantPhoneNumber:
description: The phone number of the merchant associated with the transaction
type:
- string
- 'null'
example: 555-555-5555
merchantState:
description: The name of the state where the merchant is located
type:
- string
- 'null'
example: MO
merchantType:
description: The merchant's type
type:
- string
- 'null'
example: retail
merchantZip:
description: The ZIP code where the merchant is located
type:
- string
- 'null'
example: '65401'
original_description:
description: The transaction description as received. This will not change
type: string
receiptDate:
description: The date on which FinSight API first received the transaction
type:
- string
- 'null'
format: date-time
example: '2024-05-01T12:00:00Z'
requestId:
description: A unique ID for the request the transaction came in with, for debugging purposes
type:
- string
- 'null'
example: 04f00a35-a8fa-40fd-a2ee-4af7be22ed0a
simple_description:
description: An easy-to-understand, plain-language transaction description
type: string
deprecated: true
simpleDescription:
description: An easy-to-understand, plain-language transaction description
type: string
settlement:
description: The settlement type of the transaction (e.g., 'debit' or 'credit')
type:
- string
- 'null'
example: debit
sourceId:
description: The source of the transaction
type:
- string
- 'null'
example: '1234'
state:
description: The state associated with the transaction
type:
- string
- 'null'
example: MO
subtype:
description: A more detailed classification of the transaction
type:
- string
- 'null'
example: purchase
subType:
description: A more detailed classification that provides further information on the type of transaction.
type:
- string
- 'null'
example: purchase
tenant_id:
description: The ID of the tenant associated with this transaction, if one was included.
type:
- string
- 'null'
example: TNT-4b7d4b7d-4b7d-4b7d-4b7d-4b7d4b7d4b7d
transactionid:
description: The ID of the transaction as it was originally submitted
type: string
transactionTags:
description: The FinSight API issued tags for the transaction
type: array
items:
type: string
transactionTagsId:
description: The numeric IDs corresponding to the transaction tags
type: array
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fingoal/refs/heads/main/openapi/fingoal-webhook-configurations-api-openapi.yml