FinGoal Webhooks API

openapi: 3.2.0
info:
  title: Insights Webhooks API
  description: '# Overview

    Download our postman collection here.'
  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.
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
    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
    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
  securitySchemes:
    Authentication:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://findmoney.fingoal.com/v3/authentication
          scopes:
            enrichment: Grants access to the transaction enrichment APIs.