openapi: 3.2.0
info:
  title: Insights Webhooks 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: Webhooks
  description: 'Webhook payload schemas for all webhook types. Configure which webhooks you receive using the Webhook Configurations endpoints.


    **Available Webhook Types:**

    - `ENRICHMENT_DATA`: Data-rich Transaction Enrichment (full payload with enriched transactions)

    - `ENRICHMENT_NOTIFICATION`: Notification-only Transaction Enrichment (batch_request_id for fetching results)

    - `USER_TAGS_DATA`: Data-rich User Tags (full payload with created/deleted/modified tags)

    - `USER_TAGS_NOTIFICATION`: Notification-only User Tags (guid for fetching results)

    - `INSIGHTS`: Financial insights and recommendations

    '
paths: {}
webhooks:
  enrichmentData:
    post:
      tags:
      - Webhooks
      summary: Enrichment Data-Rich Webhook
      description: 'Data-rich Transaction Enrichment webhook. When transaction enrichment completes, you will receive a POST request containing the full enriched transaction data directly in the payload.


        This webhook type (`ENRICHMENT_DATA`) sends the complete enrichment results, including all enriched transactions and any failed transactions.


        Use this webhook type when you want to receive enrichment results directly without needing to fetch them from a separate endpoint.

        '
      operationId: enrichmentDataWebhook
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                enrichedTransactions:
                  $ref: '#/components/schemas/WebhookConfigurationsTestPostENRICHMENT_DATA'
                failedTransactions:
                  $ref: '#/components/schemas/WebhookConfigurationsTestPostENRICHMENT_DATA'
                tenant_id:
                  type: string
                  description: The ID of the tenant associated with this webhook, if from a tenant environment.
                  example: TEN-123456
      parameters:
      - name: X-Webhook-Verification
        in: header
        schema:
          type: string
        description: A SHA-256 HMAC signature of the webhook payload that can be used to verify the authenticity of the webhook.
      responses:
        '200':
          description: Success
        '201':
          description: Success
  enrichmentNotification:
    post:
      tags:
      - Webhooks
      summary: Enrichment Notification Webhook
      description: 'Non-data-rich Transaction Enrichment webhook. When transaction enrichment completes, you will receive a POST request containing a `batch_request_id` that you can use to fetch the enriched results.


        This webhook type (`ENRICHMENT_NOTIFICATION`) sends only a notification with identifiers. You must fetch the actual enrichment data from `/cleanup/{batch_request_id}` endpoint using the provided `batch_request_id`.


        Use this webhook type when you prefer smaller webhook payloads and want to fetch results on-demand.

        '
      operationId: enrichmentNotificationWebhook
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichmentNotificationPostRequest'
      parameters:
      - name: X-Webhook-Verification
        in: header
        schema:
          type: string
        description: A SHA-256 HMAC signature of the webhook payload that can be used to verify the authenticity of the webhook.
      responses:
        '200':
          description: Success
        '201':
          description: Success
  userTagsData:
    post:
      tags:
      - Webhooks
      summary: User Tags Data-Rich Webhook
      description: 'Data-rich User Tags webhook. When user tag processing completes, you will receive a POST request with a JSON payload containing the full user tags data directly in the payload.


        This webhook type (`USER_TAGS_DATA`) sends the complete user tags results, including all created, deleted, and modified tags with their scores.


        Use this webhook type when you want to receive user tag changes directly without needing to fetch them from a separate endpoint.

        '
      operationId: userTagsDataWebhook
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookConfigurationsTestPostUSER_TAGS_DATA'
      parameters:
      - name: X-Webhook-Verification
        in: header
        schema:
          type: string
        description: A SHA-256 HMAC signature of the webhook payload that can be used to verify the authenticity of the webhook.
      responses:
        '200':
          description: Success
        '201':
          description: Success
  userTagsNotification:
    post:
      tags:
      - Webhooks
      summary: User Tags Notification Webhook
      description: 'Non-data-rich User Tags webhook. When user tag processing completes, you will receive a POST request containing a `guid` that you can use to fetch the user tags.


        This webhook type (`USER_TAGS_NOTIFICATION`) sends only a notification with identifiers. You must fetch the actual tag data from the `/users/tags/{guid}` endpoint using the provided `guid`.


        Use this webhook type when you prefer smaller webhook payloads and want to fetch results on-demand.

        '
      operationId: userTagsNotificationWebhook
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                guid:
                  type: string
                  example: 3961c39e-e1c6-45ec-acd0-9a7793dabe02
                tenant_id:
                  type: string
                  description: The ID of the tenant for the users included in this update, if they are from a tenant environment.
      parameters:
      - name: X-Webhook-Verification
        in: header
        schema:
          type: string
        description: A SHA-256 HMAC signature of the webhook payload that can be used to verify the authenticity of the webhook.
      responses:
        '200':
          description: Success
        '201':
          description: Success
components:
  schemas:
    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
    EnrichmentNotificationPostRequest:
      type: object
      properties:
        batch_request_id:
          type: string
          description: The ID of the request that this webhook is associated with.
          format: uuid
          example: 5f4b1b9b-4b7d-4b7d-4b7d-4b7d4b7d4b7d
        client_id:
          type:
          - string
          - 'null'
          description: The ID of the client that this webhook is associated with.
          example: client-123
        tenant_id:
          type:
          - string
          - 'null'
          description: The ID of the tenant that this webhook is associated with, if the webhook is from a tenant environment.
          example: TNT-5f4b1b9b-4b7d-4b7d-4b7d-4b7d4b7d4b7d
    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
                items:
                  type: integer
              type:
                description: An attribute describing the nature of the intent behind the transaction.
                type: string
              uid:
                description: The ID of the user associated with the transaction, as originally submitted
                type: string
              website:
                description: The merchant's website URL
                type:
                - string
                - 'null'
                example: https://links.fingoal.com/dollar-general
              zip_code:
                description: The ZIP code associated with the transaction
                type:
                - string
                - 'null'
                example: '65401'
        failedTransactions:
          type: array
          items:
            type: object
            properties:
              transactionid:
                description: The ID of the transaction as received.
                type: string
              amountnum:
                description: The transaction's USD amount as received.
                type: number
              original_description:
                description: The transaction description as received.
                type: string
              uid:
                description: The ID of the user associated with the transaction, as received.
                type: string
              date:
                description: The date on which the transaction took place as received.
                type: string
                format: date-time
              settlement:
                description: The transaction's settlement type as received.
                type: string
              accountType:
                description: The type of account associated with the transaction as received.
                type: string
  securitySchemes:
    Authentication:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://findmoney.fingoal.com/v3/authentication
          scopes:
            enrichment: Grants access to the transaction enrichment APIs.