Spade Universal Enrichment API

openapi: 3.2.0
info:
  title: Spade Card Enrichment Universal Enrichment API
  description: Documentation for Spade's card transaction enrichment API and related endpoints. We offer sandbox and production environments on both the east coast and west coast to enable ultra low latency enrichment for realtime applications. Each environment requires different API keys. To inquire about API keys, please contact your Spade representative or reach out to <hello@spade.com>.
  version: 2.7.3
servers:
- url: https://east.sandbox.spade.com
  description: East coast sandbox environment
- url: https://east.api.spade.com
  description: East coast production environment
- url: https://west.sandbox.spade.com
  description: West coast sandbox environment
- url: https://west.api.spade.com
  description: West coast production environment
- url: https://sandbox.v2.spadeapi.com
  description: East coast sandbox environment (deprecated)
- url: https://v2.spadeapi.com
  description: East coast production environment (deprecated)
- url: https://sandbox.west.v2.spadeapi.com
  description: West coast sandbox environment (deprecated)
- url: https://west.v2.spadeapi.com
  description: West coast production environment (deprecated)
security:
- ApiKeyAuth: []
tags:
- name: Universal Enrichment
paths:
  /batches/transactions/universal/enrich:
    post:
      tags:
      - Universal Enrichment
      summary: Enrich a batch of universal transactions
      description: 'Submit a batch of universal transactions for enrichment.

        This endpoint will return a `batchId` which can be used in the `/batches/{batchId}` and `/batches/{batchId}/results`

        endpoints to check the status of the batch job and retrieve the results.


        You can pass `?synchronous=true` to enrich smaller sets of transactions synchronously. See the [Microbatch enrichment guide](https://docs.spade.com/reference/microbatch-enrichment-guide) for details.


        Note that we impose a rate limit on the number of batch requests made in a rolling 12 hour window. Please reach out to

        sales@spade.com with any questions.

        '
      operationId: batchesUniversalEnrich
      parameters:
      - $ref: '#/components/parameters/SynchronousBatchParam'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/BatchUniversalEnrichmentRequest'
              - type: object
                required:
                - transactions
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/BatchSubmissionResponse'
                - type: object
                  properties:
                    results:
                      type: array
                      items:
                        $ref: '#/components/schemas/BatchUniversalEnrichmentResponse'
                  title: Universal Enrichment Microbatch Results
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      callbacks:
        batchStatusCallback:
          '{$request.body#/callbackUrl}':
            post:
              description: 'If you set a `callbackUrl` in the body parameters of the request to the `/batches` endpoint, Spade will send a `POST` request to that `callbackUrl` when the batch job finishes. The `requestBody` of the callback request will contain the body parameters specified below. We also include a webhook token in the X-Webhook-Token header. Use this token to verify that the callback is from Spade. Contact your Spade representative if you do not have this token. If the reported status is `completed`, you can use the [/batches/{batchId}/results](https://docs.spade.com/api-reference/transfer-enrichment/get-the-results-of-a-batch-transfer-enrichment-job) endpoint to retrieve the results of the batch job.

                '
              requestBody:
                content:
                  application/json:
                    schema:
                      allOf:
                      - $ref: '#/components/schemas/BatchCallbackApiRequest'
                      - type: object
                        required:
                        - batchId
                        - status
              parameters:
              - in: header
                name: X-Webhook-Token
                schema:
                  type: string
                required: true
                description: A token that can be used to verify the callback is from Spade. This will match the token provided to you by the Spade team.
              responses:
                '200':
                  description: Your server returns this code if it accepts the callback
                '500':
                  description: Your server encountered an unexpected error
              method: post
              type: path
            path: '{$request.body#/callbackUrl}'
    options:
      tags:
      - Universal Enrichment
      summary: Get metadata for the batch universal enrichment endpoint
      description: 'Returns metadata about this endpoint, including the current `synchronousMax` — the cap on items per request when `?synchronous=true`. Can be used to fetch the current cap dynamically.

        '
      operationId: batchesUniversalEnrichOptions
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchEndpointOptionsResponse'
  /transactions/universal/enrich:
    post:
      tags:
      - Universal Enrichment
      summary: Enrich a universal transaction
      description: 'Enrich any type of transaction such as an aggregator transaction, card transaction, ACH withdrawal, ACH deposit, or wire transfer.


        Note that universal enrichment is currently in *beta*, please reach out to sales@spade.com to request access.'
      operationId: universalEnrich
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UniversalEnrichmentRequest'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UniversalEnrichmentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /batches/{universalEnrichmentBatchId}/results:
    parameters:
    - name: universalEnrichmentBatchId
      in: path
      description: ID of the batch universal enrichment job
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Universal Enrichment
      summary: Get the results of a batch universal enrichment job
      description: 'Get the results of a batch universal enrichment job.

        '
      operationId: batchesUniversalEnrichGetResults
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/BatchUniversalEnrichmentResponse'
                title: Universal Enrichment Batch Results
        '202':
          description: Batch job is not yet complete. Results aren't currently available.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchGetStatusApiResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/BatchJobNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    Counterparty:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          format: uuid
          examples:
          - 704bbd58-fb12-4bdb-9aae-2786704ea92a
          description: A unique identifier for this counterparty, regardless of specific location.
        name:
          type:
          - string
          - 'null'
          maxLength: 64
          examples:
          - Amazon
          description: Counterparty name.
        legalName:
          type:
          - string
          - 'null'
          maxLength: 128
          examples:
          - Amazon Inc.
          description: Counterparty legal name. This is a premium Spade field available depending on your product package.
        industry:
          description: Array with increasingly specific category information.
          type: array
          items:
            $ref: '#/components/schemas/IndustryCategoryLevel'
        matchScore:
          description: 'The matchScore predicts how well a transaction matches a Counterparty in our records. If no Counterparty was found, the matchScore is set to null. Otherwise, scores range between 50.00 and 100.00. We filter out results below this range to make sure that only high quality matches are returned. Generally, the higher the matchScore is the better the match between a transaction and a Counterparty. When multiple Counterparties match a transaction, matches are returned in decreasing order of matchScore. This is a premium Spade field available depending on your product package.

            '
          type:
          - number
          - 'null'
          examples:
          - 93.5
        location:
          type: array
          description: 'An array of locations matched to the transaction (and associated with this counterparty). Can currently contain only one location. This is a premium Spade field available depending on your product package.

            '
          items:
            $ref: '#/components/schemas/ResponseLocation'
        logo:
          type:
          - string
          - 'null'
          maxLength: 128
          format: url
          examples:
          - https://static.v2.spadeapi.com/logos/de33f8973bc934c5b368a5b27155db02/light.png
          description: Counterparty logo. This is a premium Spade field available depending on your product package.
        phoneNumber:
          type:
          - string
          - 'null'
          maxLength: 24
          examples:
          - '+18664862360'
          description: Counterparty phone number. This is a premium Spade field available depending on your product package.
        website:
          type:
          - string
          - 'null'
          maxLength: 256
          format: url
          examples:
          - https://www.amazon.com
          description: Counterparty website. This is a premium Spade field available depending on your product package.
        possibleCounterpartyAlternate:
          type:
          - object
          - 'null'
          properties:
            id:
              type: string
              format: uuid
              examples:
              - 49fd51a1-5a19-3e5d-8d28-eb056ecf8939
              description: 'The ID of the alternate counterparty.

                '
            similarity:
              type: number
              examples:
              - 80
              description: 'The similarity score indicates how closely this alternate counterparty matches the main counterparty. The score is a value between 0.0 and 100.0, where 100.0 is an exact match.

                '
          description: 'The possible alternate counterparty object represents a counterparty that may be matched to this transaction in other enrichment requests.

            Premium Spade Field available depending on your product package.

            '
    CustomAttributesResponseField:
      type: object
      description: A dictionary containing the custom attributes that were included in the enrichment request (if any).
      additionalProperties:
        type: string
      examples:
      - custom_attribute_1: value_1
        custom_attribute_2: value_2
    BatchUniversalEnrichmentResponse:
      allOf:
      - $ref: '#/components/schemas/UniversalEnrichmentResponse'
      - type: object
        properties:
          statusCode:
            type: integer
            examples:
            - 200
            description: The HTTP status code for this element of the response array.
          errors:
            type: object
            description: 'This field is only present if the status code is not 200.

              An object containing error descriptions for this element of the response array.

              '
            examples:
            - userId:
              - This field is required.
    TriggeredActionResponse:
      type: object
      description: A triggered action returned in the enrichment response.
      properties:
        id:
          type: string
          maxLength: 512
          description: Your unique identifier for the matched trigger (as provided during registration).
          examples:
          - trigger-12345
        type:
          type: string
          description: The type of trigger that matched — `merchant_trigger` for merchant-based triggers, `category_trigger` for category-based triggers.
          enum:
          - merchant_trigger
          - category_trigger
          example: merchant_trigger
          examples:
          - merchant_trigger
        action:
          type: object
          description: 'The custom action data you provided during registration for this trigger.


            For `BLOCK` and `ALLOW_ONLY` action types, an `authRecommendation` field is automatically added:

            - `BLOCK` triggers: `authRecommendation` is set to `"BLOCK"`.

            - `ALLOW_ONLY` triggers that match: `authRecommendation` is set to `"ALLOW"`.

            - `ALLOW_ONLY` triggers that do not match (inverse semantics): `authRecommendation` is set to `"BLOCK"`.

            '
          additionalProperties: true
          properties:
            authRecommendation:
              type: string
              description: Authorization recommendation injected for `BLOCK` and `ALLOW_ONLY` action types. Not present for other action types.
              enum:
              - ALLOW
              - BLOCK
          examples:
          - type: REWARD
            rewardPercent: 5
            offerId: offer-abc123
          - type: BLOCK
            reason: Gambling merchant
            authRecommendation: BLOCK
          - type: ALLOW_ONLY
            category: approved-vendors
            authRecommendation: ALLOW
        scope:
          type: string
          description: The scope at which this trigger was registered (account, program, user, or card).
          enum:
          - account
          - program
          - user
          - card
          example: account
          examples:
          - account
        source:
          type:
          - string
          - 'null'
          description: 'Indicates whether the action was triggered by the matched counterparty or third party.


            This field will be set to `null` when an `ALLOW_ONLY` action trigger was set up whose condition the current transaction did not meet. The `authRecommendation` in this case will be `BLOCK`.

            '
          enum:
          - counterparty
          - third_party
          - null
          example: counterparty
          examples:
          - counterparty
        categoryId:
          type: string
          description: The Spade category ID that matched this trigger. Only present when `type` is `category_trigger`.
          examples:
          - b4b0d249-b402-49ac-b744-5027d4574fc5
        categoryName:
          type: string
          description: The name of the Spade category that matched this trigger. Only present when `type` is `category_trigger`.
          examples:
          - Travel
    ThirdParty:
      type: object
      properties:
        id:
          type: string
          format: uuid
          examples:
          - ac48cef2-0d7f-4159-865e-e92b152262bc
        name:
          type: string
          maxLength: 64
          examples:
          - Paypal
        type:
          type: string
          enum:
          - bnpl
          - delivery_service
          - marketplace
          - payment_processor
          - platform
          examples:
          - payment_processor
        logo:
          type:
          - string
          - 'null'
          maxLength: 128
          format: url
          examples:
          - https://static.v2.spadeapi.com/logos/9063bc0f0a3f4b1fbf644f9862e17002/light.png
          description: Third party logo.
        website:
          type:
          - string
          - 'null'
          maxLength: 256
          format: url
          examples:
          - https://www.paypal.com/
          description: Third party website.
    EnrichmentResponse:
      type: object
      properties:
        enrichmentId:
          type: string
          format: uuid
          description: Our ID representing the enrichment, not to be confused with your provided `transactionId`.
        transactionInfo:
          type: object
          properties:
            type:
              type: string
              description: The main type of the transaction. For card transactions, the type is always "spending".
              enum:
              - account_verification
              - atm
              - debt
              - fee
              - income
              - other_money_movement
              - reimbursement
              - spending
              examples:
              - spending
            subType:
              type:
              - string
              - 'null'
              description: The more specific type of the transaction, if applicable. For card transactions, the `subType` is always `null`.
              enum:
              - alimony_or_child_support
              - atm
              - bnpl
              - business
              - cash_advance
              - deposit
              - disbursements
              - earned_income
              - government_benefits
              - insurance
              - investment
              - nsf
              - other
              - overdraft
              - payment
              - payout
              - rental
              - retirement
              - tax_refund
              - transfer
              - withdrawal
              examples:
              - null
            display:
              type:
              - object
              - 'null'
              description: 'An object containing display information for the transaction. The fields in this object are pulled from other parts of the enrichment and surfaced here for convenience.

                '
              properties:
                name:
                  type:
                  - string
                  maxLength: 64
                  description: The best name for display.
                  examples:
                  - Amazon
                categoryName:
                  type:
                  - string
                  - 'null'
                  maxLength: 64
                  description: The best category name for display.
                  examples:
                  - Online Marketplace
                graphic:
                  type:
                  - string
                  - 'null'
                  maxLength: 128
                  description: 'The best graphic for display. Depending on the data available, this will be either a) the counterparty logo, b) the third party logo, or c) the category icon.

                    '
                  format: url
                  examples:
                  - https://static.v2.spadeapi.com/logos/de33f8973bc934c5b368a5b27155db02/light.png
                  - https://static.v2.spadeapi.com/categories/b4b0d249b40249acb7445027d4574fc5/light.png
                graphicSource:
                  type:
                  - string
                  - 'null'
                  maxLength: 16
                  enum:
                  - counterparty
                  - third_party
                  - category
                  description: 'The field from which the `graphic` was sourced. This will be either `counterparty`, `third_party`, or `category`.

                    '
                  examples:
                  - counterparty
            thirdParties:
              type: array
              description: An array of third parties involved in the transaction, when applicable. Entities such as Toast, Square, Uber Eats, Doordash, etc. will appear here.
              items:
                $ref: '#/components/schemas/ThirdParty'
            spendingInfo:
              type:
              - object
              - 'null'
              description: Additional information about transactions whose `type` is "spending". This field is `null` for other types of transactions.
              properties:
                channel:
                  type: object
                  properties:
                    value:
                      type:
                      - string
                      - 'null'
                      enum:
                      - digital
                      - physical
                      - null
                      description: Spending channel value of digital or physical, null if we are unable to determine.
            transferInfo:
              type:
              - object
              - 'null'
              description: Additional information about transfers. This field is `null` for card transactions.
              properties:
                direction:
                  type:
                  - string
                  maxLength: 12
                  enum:
                  - outgoing
                  - incoming
                  description: The transfer direction.
                  examples:
                  - outgoing
                transferMethod:
                  type:
                  - string
                  maxLength: 12
                  enum:
                  - ach
                  - cash
                  - check
                  - intrabank
                  - rtp
                  - unknown
                  - wire
                  description: The transfer method.
                  examples:
                  - ach
                transferType:
                  type:
                  - string
                  maxLength: 12
                  enum:
                  - external
                  - internal
                  - unknown
                  description: The transfer type. "external" indicates that money is being sent to an external counterparty. "internal" indicates that money is being moved between accounts owned by the same entity.
                  examples:
                  - external
                isAdjustmentOrRefund:
                  type:
                  - boolean
                  description: Whether the transfer is an adjustment or refund.
                  examples:
                  - false
            atmInfo:
              type:
              - object
              - 'null'
              description: Additional information about ATM transactions. This field is `null` for other types of transactions.
              examples:
              - null
              properties:
                sponsorName:
                  type:
                  - string
                  maxLength: 64
                  description: The name of the sponsor of the ATM involved in the transaction.
                  examples:
                  - Fiserv
                ownerName:
                  type:
                  - string
                  maxLength: 64
                  description: The name of the owner of the ATM involved in the transaction.
                  examples:
                  - Wells Fargo
            isAccountVerification:
              type:
              - boolean
              - 'null'
              description: Whether the transfer is an account verification. Currently only available for transfers.
              examples:
              - false
            isPeerToPeer:
              type:
              - boolean
              - 'null'
              description: Whether the transaction is a peer-to-peer transaction. Currently only available for transfers.
              examples:
              - false
            isDigitalWallet:
              type:
              - boolean
              - 'null'
              description: Whether the transaction involves a digital wallet. Currently only available for transfers.
              examples:
              - false
            transactionId:
              type: string
              maxLength: 512
              description: Your ID representing this transaction. This ID exactly matches the transactionId you provided in your enrichment request.
              examples:
              - transaction_id_123456789
            recurrenceInfo:
              type:
              - object
              - 'null'
              description: A recurring transaction is a repeated payment pattern to a counterparty, based on periodicty and amount. Premium Spade Signal available depending on your product package.
              properties:
                intervalType:
                  type:
                  - string
                  - 'null'
                  maxLength: 12
                  enum:
                  - weekly
                  - biweekly
                  - semi_monthly
                  - monthly
                  - quarterly
                  - annually
                  description: Recurrence cadence.
                intervalDays:
                  type:
                  - integer
                  - 'null'
                  description: Number of days between recurrences.
                  examples:
                  - 30
                nextPaymentExpected:
                  type:
                  - string
                  - 'null'
                  maxLength: 10
                  format: date
                  description: Next expected payment date.
                  examples:
                  - '2024-08-07'
                recentRecurrences:
                  type:
                  - array
                  - 'null'
                  description: Array of recent recurrence objects, null if no recurrence exists.
                  items:
                    type: array
                    properties:
                      amount:
                        type: number
                        description: Amount of the recurrence.
                        examples:
                        - 130
                      enrichmentId:
                        type: string
                        description: Our ID representing the enrichment, not to be confused with your provided `transactionId`.
                        examples:
                        - c1d4064b-9364-43d3-8ee3-500898cda1aa
                      occurredAt:
                        type: string
                        format: date-time
                        description: Date and time the transaction occurred. Formatted as an ISO 8601 date time.
                        examples:
                        - '2024-06-06T14:25:11+00:00'
                      transactionId:
                        type: string
                        description: Customer-provided identifier for the transaction.
                        examples:
                        - d6c4dc4e-e0da-4782-b581-95916523d87a
            riskInsights:
              type:
              - object
              - 'null'
              description: Risk insights provide visibility into the potential risk of a transaction and the merchants involved. Premium Spade Signal available depending on your product package.
              properties:
                irregularWebPresenceDetected:
                  type:
                  - boolean
                  - 'null'
                  description: Has engaged in deceptive online practices or has irregular website structure or content.
                  examples:
                  - false
                negativeOnlineSentiment:
                  type:
                  - boolean
                  - 'null'
                  description: Negative online consumer feedback associated with the counterparty.
                  examples:
                  - false
                highRiskEntity:
                  type:
                  - boolean
                  - 'null'
                  description: The counterparty is known to engage in fraudulent practices.
                  examples:
                  - false
                riskyIndustry:
                  type:
                  - boolean
                  - 'null'
                  description: Industry is correlated with increased disputes (based on Spade industries).
                  examples:
                  - false
                cardAcceptanceHistory:
                  type:
                  - string
                  - 'null'
                  enum:
                  - extensive
                  - established
                  - stable
                  - limited
                  - very_limited
                  - 'null'
                  description: Counterparties with lower levels of card acceptance history have a higher likelihood of chargebacks or fraudulent activity.
                  examples:
                  - extensive
        counterparty:
          type: array
          description: An array of counterparties matched to the transaction, ordered by descending match score.
          items:
            $ref: '#/components/schemas/Counterparty'
        mobileAppInfo:
          $ref: '#/components/schemas/MobileAppInfo'
        customAttributes:
          $ref: '#/components/schemas/CustomAttributesResponseField'
        actions:
          type:
          - array
          - 'null'
          description: 'An array of triggered actions, or `null` if no triggers matched.

            This field is only present if your integration has the actions feature enabled.


            When a transaction matches one or more registered triggers, this array contains the action details

            including your custom `action` data. Multiple matches are possible when triggers are registered

            at different scopes (account, program, user, card).

            '
          items:
            $ref: '#/components/schemas/TriggeredActionResponse'
          examples:
          - - id: trigger-12345
              type: merchant_trigger
              action:
                type: REWARD
                rewardPercent: 5
              scope: account
              source: counterparty
    BatchGetStatusApiResponse:
      type: object
      properties:
        batchId:
          type: string
          format: uuid
          description: Unique identifier for the batch job
        status:
          type: string
          enum:
          - pending
          - running
          - completed
          - failed
          description: Current status of the batch job
    BatchUniversalEnrichmentRequestItem:
      allOf:
      - $ref: '#/components/schemas/UniversalEnrichmentRequest'
      - type: object
        required:
        - transactionId
        properties:
          transactionId:
            type: string
            maxLength: 512
            description: Your ID representing this transaction. Required for batch requests.
            examples:
            - transaction_id_123456789
    ResponseLocation:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          format: uuid
          examples:
          - fdf79470-3deb-4638-956a-6859e473b9d8
          description: A unique identifier for this location.
        address:
          type:
          - string
          - 'null'
          maxLength: 64
          examples:
          - 1234 W 5th Ave Suite 100
          description: Street number, name, and any secondary address information.
        addressLine1:
          type:
          - string
          - 'null'
          maxLength: 64
          examples:
          - 1234 W 5th Ave
          description: Street numbe

# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spade/refs/heads/main/openapi/spade-universal-enrichment-api-openapi.yml