openapi: 3.1.0
info:
  title: Insights Enrichment 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: Enrichment
  description: "The Insights API's transaction enrichment endpoints enable developers to clean and enhance their transaction data. This process includes standardizing merchant names, categorizing transactions, and adding additional metadata. It also supports transaction-level tagging. Transactions submitted to the enrichment endpoints contribute to the Insights API's user tagging capabilities. \n\nThe Insights API offers both synchronous and asynchronous flows. The synchronous flow is a direct request-response model intended for testing and development purposes only. All production requests should use the asynchronous historical and streaming transaction enrichment endpoints.\n\n<a href=\"https://docs.google.com/spreadsheets/d/1XL649eKzMZ21WGWdcUE4cvKbKb6oXzfdBv5Ob8qPpbM/edit?usp=sharing\" target=\"blank\">View Full List of FinGoal Categories</a>\n\n<a href=\"https://fingoal.com/tags-list\" target=\"blank\">View Full List of FinGoal Tags</a>\n\n\n## Enrichment Quickstart\nThis quickstart requires a JWT, which can be generated following the top-level authentication quickstart. Ensure you have a valid JWT before proceeding.\n\n### 1. Prepare the Request Body\nThe request body should be a JSON object with a single parameter, `transactions`, which must be an array. Each transaction must include the following fields:\n- `uid`: A unique user identifier.\n- `amountnum`: The transaction amount.\n- `date`: The transaction date.\n- `original_description`: The original transaction description.\n- `transactionid`: The unique transaction identifier.\n- `accountType`: The account type.\n- `settlement`: The settlement type.\n\n```json\n{\n  \"transactions\": [\n    {\n      \"uid\": \"16432789fdsa78\",\n      \"accountid\": \"1615\",\n      \"amountnum\": 12.41,\n      \"date\": \"2024-05-11\",\n      \"original_description\": \"T0064 TARGET STORE\",\n      \"transactionid\": \"988cee06-5d36-11ec-b00b-bc8d8f2303a12733\",\n      \"accountType\" : \"creditCard\",\n      \"settlement\": \"debit\"\n    }\n  ]\n}\n```\n### 2. Make a POST Request\nMake a POST request to the Insights API cleanup endpoint using the prepared JSON object. Include the JWT in the `Authorization` header.\n```js\n  const headers = new Headers();\n  headers.append(\"Authorization\", \"Bearer {YOUR_TOKEN}\");\n  headers.append(\"Content-Type\", \"application/json\");\n\n  const body = JSON.stringify({\n    \"transactions\": [\n      {\n        \"uid\": \"16432789fdsa78\",\n        \"accountid\": \"1615\",\n        \"amountnum\": 12.41,\n        \"date\": \"2024-05-11\",\n        \"original_description\": \"T0064 TARGET STORE\",\n        \"transactionid\": \"988cee06-5d36-11ec-b00b-bc8d8f2303a12733\",\n        \"accountType\" : \"creditCard\",\n        \"settlement\": \"debit\"\n      }\n    ]\n  });\n\n  const requestOptions = {\n    method: 'POST',\n    redirect: 'follow'\n    headers,\n    body,\n  };\n\n  try {\n    const response = await fetch(\"https://findmoney-dev.fingoal.com/v3/cleanup\", requestOptions);\n    const data = response.json();\n    console.log(data);\n  } catch(error) {\n    console.log('ERROR:', error);\n  }\n```\nThe JavaScript code above uses the `fetch` API to request transaction enrichment. If the request succeeds, it logs the response body. If an error occurs, it logs the error.\n### 3. Extract the Batch Request ID from a Successful Response\nIf the request is successful, the response body will contain a JSON object with a single parameter, `status`. The `status` object has the following structure:\n- `transactions_received`: Whether or not the transactions were successfully enqueued for enrichment.\n- `transactions_validated`: Whether or not the transactions were successfully validated.\n- `processing`: Whether or not the transactions are currently being processed.\n- `num_transactions_processing`: The number of transactions that are currently being processed.\n- `batch_request_id`: The unique identifier for the batch request.\n\n```json\n{\n  \"status\": {\n    \"transactions_received\": true,\n    \"transactions_validated\": true,\n    \"processing\": true,\n    \"num_transactions_processing\": 1,\n    \"batch_request_id\": \"988cee06-5d36-11ec-b00b-bc8d8f2303a12733\"\n  }\n}\n```\nThe `batch_request_id` is a unique identifier for the batch request. You will use this identifier to retrieve the enriched transactions. \n### 4. Listen for the Enrichment Completion Event \nTo receive a webhook notification for a completed enrichment batch, you must submit a webhook URL. Use the FinGoal support email (support@fingoal.com) to submit a webhook URL for registry. Once the URL is registered, you will automatically receive all future enrichment completion webhooks. \n\nWebhook notifications are sent as HTTP POST requests to the registered URL. The webhook URL must be publicly accessible and support HTTPS connections. The Insights API cannot send webhooks to a non-HTTPS URL. \n\nThe webhook payload contains a JSON object with the following structure: \n- `batch_request_id`: The unique identifier for the batch request.\n\nThe `batch_request_id` corresponds to the `batch_request_id` returned in the initial enrichment request. \n```json\n{\n  \"batch_request_id\": \"988cee06-5d36-11ec-b00b-bc8d8f2303a12733\"\n}\n```\n#### Verifying the Enrichment Webhook \nEvery enrichment complete webhook includes an `X-Webhook-Verification` header. The header contains a SHA-256 HMAC signature of the webhook payload. To verify the webhook, you must generate a SHA-256 HMAC signature using the webhook payload and your Insights API secret key. If the generated signature matches the signature in the `X-Webhook-Verification` header, the webhook is valid. If not, the webhook should be discarded. \n\nThe following snippet demonstrates how to verify the webhook signature using Node.js with the `crypto` and `express` libraries.\n```js\nconst crypto = require('crypto');\nconst express = require('express');\nconst app = express();\n\napp.use(express.json());\napp.post('/webhook-receiver', (req, res) => {\n  const { headers, body } = req;\n  const { 'x-webhook-verification': signature } = headers;\n  if (!signature) {\n    res.status(400).send('Reject the webhook if no verification header is present.');\n    return;\n  }\n\n  const secret = 'YOUR_CLIENT_SECRET';\n  const payload = JSON.stringify(body);\n  const hmac = crypto.createHmac('sha256', secret);\n  const digest = hmac.update(payload).digest('hex');\n\n  if (digest === signature) {\n    res.status(200).send('The webhook is verified. It is safe to process the payload.'); \n  } else {\n    res.status(400).send('The Webhook verification is incorrect for the payload. Reject the webhook.');\n  }\n});\n```\n\n### 5. Retrieve the Enriched Transactions\nWith the `batch_request_id`, submit a GET request to the Insights API enrichment retrieval endpoint. Include the JWT in the `Authorization` header. \n```js\n  const headers = new Headers();\n  headers.append(\"Authorization\", \"Bearer {YOUR_TOKEN}\");\n\n  const requestOptions = {\n    method: 'GET',\n    redirect: 'follow',\n    headers,\n  };\n\n  try {\n    const response = await fetch(\"https://findmoney-dev.fingoal.com/v3/cleanup/{batch_request_id}\", requestOptions);\n    const data = response.json();\n    console.log(data);\n  } catch(error) {\n    console.log('ERROR:', error);\n  }\n```\nThe JavaScript code above uses the `fetch` API to request the enriched transactions. If the request succeeds, it logs the response body. If an error occurs, it logs the error.\n### Successful Response\nIf the request is successful, the response body will contain a JSON object a single parameter, `enrichedTransactions`. The `enrichedTransactions` array will contain all available transaction-level enrichment for the data in this batch. \n\n### Best Practices \n- Group transactions by `uid` for optimal performance. \n- Provide as much information as possible in the request body to improve enrichment quality.\n- Use unique `uid` and `transactionid` values for each user and transaction. These identifiers may need to be cross-referenced with your system's data in the future.\n- Avoid using personally identifiable information (PII) in the `uid` or `transactionid` fields. We recommend using a UUID or similar anonymous identifier instead. \n"
paths:
  /cleanup/sync:
    post:
      tags:
      - Enrichment
      summary: Test Transaction Enrichment
      description: "The test transaction enrichment endpoint provides immediate enrichment on transaction data. This endpoint is ideal for testing API functionality and previewing enrichment results. \n\n**This endpoint is not intended for production use.** Use the historical and streaming endpoints for production-level enrichment.\n\n\nFor optimal performance, adhere to the following limits: \n  - Submit no more than 4 unique users per request. Users are distinguished by the `uid` field in each transaction. \n  - Submit no more than 16 transactions per user per request if sending multiple users. Send no more than 128 if sending a single user.\n"
      operationId: syncCleanupTransactions
      security:
      - Authentication:
        - enrichment
      requestBody:
        description: Transactions
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CleanupPostRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  enrichedTransactions:
                    type: object
                    properties:
                      enriched:
                        type: array
                        items:
                          type: object
                          properties:
                            accountid:
                              description: The ID of the account associated with the transaction
                              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:
                              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
                              deprecated: true
                              items:
                                type: string
                            client_id:
                              type: string
                              description: Your FinGoal client ID
                            container:
                              description: A high-level categorization of the account type. Eg, 'bank'
                              type: string
                            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
                            isRecurring:
                              deprecated: true
                              description: This field is deprecated. Denotes whether the transaction is set to recur on a fixed interval
                              type: boolean
                            merchantAddress1:
                              description: The street address of the merchant associated with the transaction
                              type: string
                            merchantCity:
                              description: The name of the city where the merchant is located
                              type: string
                            merchantCountry:
                              description: The name of the country where the merchant is located
                              type: string
                            merchantLatitude:
                              description: The latitude of the merchant
                              type: string
                            merchantLogoURL:
                              description: The URL resource for the merchant's logo
                              type: string
                            merchantLongitude:
                              description: The longitude of the merchant
                              type: string
                            merchantName:
                              description: The name of the merchant associated with the transaction
                              type: string
                            merchantPhoneNumber:
                              description: The phone number of the merchant associated with the transaction
                              type: string
                            merchantState:
                              description: The name of the state where the merchant is located
                              type: string
                            merchantType:
                              description: The merchant's type
                              type: string
                            merchantZip:
                              type: string
                              description: The ZIP code where the merchant is located
                            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
                              format: date-time
                            requestId:
                              description: A unique ID for the request the transaction came in with, for debugging purposes
                              type: string
                            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
                            sourceId:
                              description: The source of the transaction
                              type: string
                            subType:
                              description: A more detailed classification that provides further information on the type of transaction.
                              type: string
                            tenant_id:
                              description: The ID of the tenant associated with this transaction, if one was included.
                              type: string
                            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
                            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
                      failed:
                        type: array
                        items:
                          type: object
                          properties:
                            amountnum:
                              description: The transaction's USD amount
                              type: number
                            settlement:
                              description: The settlement type of the transaction (e.g., 'debit' or 'credit')
                              type: string
                            original_description:
                              description: The transaction description as received. This will not change
                              type: string
                            transactionid:
                              description: The ID of the transaction as it was originally submitted
                              type: string
                            date:
                              description: The date on which the transaction took place
                              type: string
                              format: date-time
                            accountType:
                              description: The type of account (e.g., 'checking')
                              type: string
                            uid:
                              description: The ID of the user associated with the transaction, as originally submitted
                              type: string
                            error_message:
                              type: string
                              description: A message describing why the transaction failed to enrich.
        '400':
          description: Bad request. An array of errors in the data will be returned. Fields not allowed or incorrectly formatted will be noted.
        '401':
          description: Unauthorized
  /cleanup:
    post:
      tags:
      - Enrichment
      summary: Historical Transaction Enrichment
      description: "The historical transaction enrichment endpoint is designed for enriching a large number of transactions. It is optimized to handle substantial payloads and efficiently process large backlogs of data.\n\nThis endpoint is asynchronous. A webhook will be sent to the provided URL when a batch of transactions has been enriched.\n    \nTo maximize throughput for this endpoint, follow these guidelines: \n  - Group transactions by `uid` and include all transactions for a single `uid` in the same payload.\n  - Limit each request to approximately 1,000 transactions. The payload can include multiple uids. \n"
      operationId: asyncCleanupTransactions
      security:
      - Authentication:
        - enrichment
      requestBody:
        description: Transactions
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CleanupPostRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CleanupPost200Response'
        '400':
          description: Bad request. An array of errors in the data will be returned. Fields not allowed or incorrectly formatted will be noted.
        '401':
          description: Unauthorized
      callbacks:
        enrichment_result:
          https://YOUR_CALLBACK_URI:
            post:
              security: []
              summary: Enrichment Webhook
              parameters:
              - name: X-Webhook-Verification
                in: header
                required: true
                schema:
                  type: string
                description: A SHA-256 HMAC signature of the webhook payload that can be used to verify the authenticity of the webhook.
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/EnrichmentNotificationPostRequest'
  /cleanup/streaming:
    post:
      tags:
      - Enrichment
      summary: Streaming Transaction Enrichment
      description: "FinGoal's streaming transaction enrichment endpoint is designed for enriching daily user transactions or other smaller transaction batches. \n\nUnlike the historical transaction enrichment endpoint, the streaming transaction enrichment endpoint does not require any user segmentation. Requests that include many users (by uid) will not deteriorate the endpoint's performance.\n\nThis endpoint is asynchronous. A webhook will be sent to the provided URL when a batch of transactions has been enriched. For larger transaction sets, such as historical data, user the historical enrichment endpoint.\n\nTo maximize throughput for this endpoint, follow these guidelines: \n  - Group transactions by \"uid\" and include all transactions for a single user in the same payload.\n  - Limit each request to a total of approximately 1,000 transactions. \n  - Transactions can be distributed among any number of users as long as the total number of transactions does not exceed 1,000.\n"
      operationId: streamingCleanupTransactions
      security:
      - Authentication:
        - enrichment
      requestBody:
        description: Transactions
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CleanupPostRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CleanupPost200Response'
        '400':
          description: Bad request. An array of errors in the data will be returned. Fields not allowed or incorrectly formatted will be noted.
        '401':
          description: Unauthorized
      callbacks:
        enrichment_result:
          https://YOUR_CALLBACK_URI:
            post:
              security: []
              summary: Enrichment Complete Notification
              parameters:
              - name: X-Webhook-Verification
                in: header
                required: true
                schema:
                  type: string
                description: A SHA-256 HMAC signature of the webhook payload that can be used to verify the authenticity of the webhook.
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/EnrichmentNotificationPostRequest'
  /cleanup/base:
    post:
      tags:
      - Enrichment
      summary: Base Transaction Enrichment
      description: "FinGoal's base transaction enrichment endpoint is a new and improved model for enriching daily user, historical, or one off user transactions. It accepts additional `accountTypes` that previous enrichment endpoints did not, including `businessChecking`, `businessSavings`, `businessCreditCard`, `businessLoan`, `loan`, `investments`.\n\nRequests that include many users (by uid) will not deteriorate the endpoint's performance and it has much higher throughput than previous enrichment endpoints. \n\nThis endpoint is asynchronous. A webhook will be sent to the provided URL when a batch of transactions has been enriched.\n\nTo maximize throughput for this endpoint, follow these guidelines: \n  - Limit each request to a total of approximately 1,000 transactions. \n  - Transactions can be distributed among any number of users as long as the total number of transactions does not exceed 1,000.\n"
      operationId: baseCleanupTransactions
      security:
      - Authentication:
        - enrichment
      requestBody:
        description: Transactions
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - transactions
              properties:
                transactions:
                  type: array
                  items:
                    type: object
                    required:
                    - accountType
                    - amountnum
                    - date
                    - original_description
                    - transactionid
                    - settlement
                    - uid
                    properties:
                      accountType:
                        type: string
                        description: 'The type of account associated with the transaction.

                          '
                        enum:
                        - checking
                        - savings
                        - creditCard
                        - businessChecking
                        - businessSavings
                        - businessCreditCard
                        - businessLoan
                        - loan
                        - investments
                        example: checking
                      amountnum:
                        type: number
                        maxLength: 11
                        description: The transaction amount in USD. Negative amounts are automatically converted to positive amounts. Use the 'settlement' field to indicate whether the transaction was a 'debit' or 'credit'. The string representation of amount must be fewer than 11 characters.
                        example: 19.99
                      date:
                        description: The date of the transaction. Must be in the format 'YYYY-MM-DD'.
                        type: string
                        format: date
                        example: '2024-05-01'
                      identifiers:
                        description: A JSON representation of alternative user IDs. This field is designed exclusively for users with Banno, Salesforce, or other CRM integrations. Valid identifiers are currently limited to [`sfmc_contact_id`, `banno_end_user_id`].
                        type: object
                        properties:
                          sfmc_contact_id:
                            type: string
                            example: sfmc-1234
                          banno_end_user_id:
                            type: string
                            example: banno-1234
                      original_description:
                        description: 'The transaction''s description. Must be between 3 and 198 characters. Descriptions longer than 198 characters are automatically truncated.

                          '
                        minLength: 1
                        maxLength: 198
                        type: string
                        example: Cottonwood Supermarket & Deli
                      transactionid:
                        description: A unique identifier for the transaction. Do not use PII or other information-rich data in this field. We strongly recommend using UUID or a similar identification system.
                        maxLength: 100
                        type: string
                        example: 178b1f61-dafe-4d47-837b-54ce34dc82b2
                      settlement:
                        description: Indicates whether the transaction was a 'debit' or 'credit' to the account.
                        type: string
                        enum:
                        - debit
                        - credit
                        example: debit
                      uid:
                        description: The ID of the user associated with the transaction. User IDs must be unique. Do not use PII or other information-rich data in this field. We strongly recommend using UUID or a similar identification system.
                        maxLength: 50
                        type: string
                        example: user123
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CleanupPost200Response'
        '400':
          description: Bad request. An array of errors in the data will be returned. Fields not allowed or incorrectly formatted will be noted.
        '401':
          description: Unauthorized
      callbacks:
        enrichment_result:
          https://YOUR_CALLBACK_URI:
            post:
              security: []
              summary: Enrichment Complete Notification
              parameters:
              - name: X-Webhook-Verification
                in: header
                required: true
                schema:
                  type: string
                description: A SHA-256 HMAC signature of the webhook payload that can be used to verify the authenticity of the webhook.
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/EnrichmentNotificationPostRequest'
  /cleanup/{batch_request_id}:
    get:
      tags:
      - Enrichment
      summary: Retrieve Enrichment by Batch Request ID
      description: "Developers may use this endpoint in conjunction with the [asynchronous cleanup endpoints](#operation/asyncCleanupTransactions) to retrieve the results of a transaction cleanup operation by its batch operation ID.\nThe operation ID can be extracted from the webhook that the async cleanup endpoint sends when enrichment is complete.  \n"
      operationId: getEnrichment
      security:
      - Authentication:
        - enrichment
      parameters:
      - name: batch_request_id
        in: path
        description: The Batch Request ID of the enrichment request.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookConfigurationsTestPostENRICHMENT_DATA'
        '401':
          description: Unauthorized
        '404':
          description: No transactions found for the given request id.
components:
  schemas:
    CleanupPostRequest:
      type: object
      required:
      - transactions
      properties:
        transactions:
          type: array
          items:
            type: object
            required:
            - accountType
            - amountnum
            - date
            - original_description
            - transactionid
            - settlement
            - uid
            properties:
              accountType:
                type: string
                description: 'The type of account associated with the transaction.


                  For transactions from loan accounts, use ''savings''.

                  '
                enum:
                - checking
                - savings
                - creditCard
                example: checking
              amountnum:
                type: number
                maxLength: 11
                description: The transaction amount in USD. Negative amounts are automatically converted to positive amounts. Use the 'settlement' field to indicate whether the transaction was a 'debit' or 'credit'. The string representation of amount must be fewer than 11 characters.
                example: 19.99
              date:
                description: The date of the transaction. Must be in the format 'YYYY-MM-DD'.
                type: string
                format: date
                example: '2024-05-01'
              identifiers:
                description: A JSON representation of alternative user IDs. This field is designed exclusively for users with Banno, Salesforce, or other CRM integrations. Valid identifiers are currently limited to [`sfmc_contact_id`, `banno_end_user_id`].
                type: object
                properties:
                  sfmc_contact_id:
                    type: string
                    example: sfmc-1234
                  banno_end_user_id:
                    type: string
                    example: banno-1234
              original_description:
                description: 'The transaction''s description. Must be between 3 and 198 characters. Descriptions longer than 198 characters are automatically truncated.


                  For transactions from loan accounts, prepend `LOANTRANS-` to this field.

                  '
                minLength: 1
                maxLength: 198
                type: string
                example: Cottonwood Supermarket & Deli
              transactionid:
                description: A unique identifier for the transaction. Do not use PII or other information-rich data in this field. We strongly recommend using UUID or a similar identification system.
                maxLength: 100
                type: string
                example: 178b1f61-dafe-4d47-837b-54ce34dc82b2
              settlement:
                description: Indicates whether the transaction was a 'debit' or 'credit' to the account.
                type: string
                enum:
                - debit
                - credit
                example: debit
              uid:
                description: The ID of the user associated with the transaction. User IDs must be unique. Do not use PII or other information-rich data in this field. We strongly recommend using UUID or a similar identification system.
                maxLength: 50
                type: string
                example: user123
              accountid:
                description: The account ID associated with the transaction. This field is optional and will not affect enrichment results. Do not use the actual account number. We strongly recommend using UUID or a similar identification system.
                maxLength: 50
                type: string
                example: account456
    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
    CleanupPost200Response:
      type: object
      properties:
        transactions_received:
          type: boolean
          description: Denotes whether FinSight API has successfully received the transactions.
        transactions_validated:
          type: boolean
          description: Denotes whether or not the transaction payload successfully passed FinSight API validation.
        processing:
          type: boolean
          description: Denotes whether the asynchronous enrichment process has commenced.
        num_transactions_processing:
          type: integer
          description: The number of transactions that have been received.
        batch_request_id:
          type: string
          description: A unique ID associated with the request for debugging.
    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.