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
                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.