Spade Card Enrichment API

openapi: 3.2.0
info:
  title: Spade Card 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: Card Enrichment
  description: Enrich card transactions
paths:
  /batches/transactions/cards/enrich/parse:
    post:
      tags:
      - Card Enrichment
      summary: Enrich a batch of card transactions with DE43 data
      description: 'Submit a batch of card transactions for enrichment where de43 data in the request body takes precedence over the other fields in the request body.

        Just like the `/transactions/cards/enrich/parse` endpoint, the transactions can omit `city` and `merchantName` fields if the `de43` field is present.

        This endpoint returns 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: batchesTransactionsCardsEnrichParse
      parameters:
      - $ref: '#/components/parameters/SynchronousBatchParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchCardParseEnrichmentRequest'
        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/BatchCardEnrichmentResponse'
                  title: Card 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:
      - Card Enrichment
      summary: Get metadata for the batch card parse 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: batchesTransactionsCardsEnrichParseOptions
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchEndpointOptionsResponse'
  /batches/transactions/cards/enrich:
    post:
      tags:
      - Card Enrichment
      summary: Enrich a batch of card transactions
      description: 'Submit a batch of 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: batchesTransactionsCardsEnrich
      parameters:
      - $ref: '#/components/parameters/SynchronousBatchParam'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/BatchCardEnrichmentRequest'
              - 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/BatchCardEnrichmentResponse'
                  title: Card 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:
      - Card Enrichment
      summary: Get metadata for the batch card 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: batchesTransactionsCardsEnrichOptions
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchEndpointOptionsResponse'
  /transactions/enrich:
    post:
      tags:
      - Card Enrichment
      summary: Enrich a card transaction
      description: Enrich a card transaction. Please use `/transactions/cards/enrich` instead. This endpoint now aliases to `/transactions/cards/enrich`.
      operationId: cardEnrichDeprecated
      deprecated: true
  /transactions/enrich/parse:
    post:
      tags:
      - Card Enrichment
      summary: Enrich a card transaction with an unparsed de43
      description: Enrich a card transaction. Please use `/transactions/cards/enrich/parse` instead. This endpoint now aliases to `/transactions/cards/enrich/parse`.
      operationId: cardEnrichParseDeprecated
      deprecated: true
  /transactions/cards/enrich/parse:
    post:
      tags:
      - Card Enrichment
      summary: Enrich a card transaction with an unparsed de43
      description: 'Enrich a card transaction where parsed de43 data takes precedence over the other fields in the request body.

        This otherwise endpoint is identical to `/transactions/cards/enrich` except that `city` and `merchantName` are now

        optional, but only when `de43` is included. Note: Because DE43 format is not consistent between sources, we recommend parsing

        your own data and using `/transactions/cards/enrich/` if possible.


        Note that some response fields may not be included in your product package, please reach out to sales@spade.com with any questions.

        '
      operationId: cardEnrichParse
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/CardEnrichmentRequest'
              - type: object
                properties:
                  de43:
                    type: string
                    maxLength: 100
                    description: A well formatted de43 message. If parsable the parsed data (merchantName, city, state) will take precedence over the corresponding fields in the request body. The parser expects an unedited de43, please do not remove special characters or spaces. Our parser currently only supports US transactions.
                    examples:
                    - WALMART.COM            BENTONVILLE  ARUS
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardEnrichmentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /transactions/cards/enrich:
    post:
      tags:
      - Card Enrichment
      summary: Enrich a card transaction
      description: 'When working with this endpoint, note that several of the input fields are optional (region, acquirerId, etc.). However, we *strongly* recommend including all of the fields that you have available. Some optional fields can substantially improve performance.


        Take care to ensure you are using unaltered and correct data in each field. Some fields go by multiple names, so if you have any questions regarding integration please feel free to reach out.


        Note that some response fields may not be included in your product package, please reach out with any questions.'
      operationId: cardEnrich
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/CardEnrichmentRequest'
              - type: object
                required:
                - merchantName
                properties:
                  location:
                    type: object
                    required:
                    - city
                    - country
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardEnrichmentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /batches/{cardEnrichmentBatchId}/results:
    parameters:
    - name: cardEnrichmentBatchId
      in: path
      description: ID of the batch card enrichment job
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Card Enrichment
      summary: Get the results of a batch card enrichment job
      description: 'Get the results of a batch card enrichment job.

        '
      operationId: batchesCardEnrichGetResults
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/BatchCardEnrichmentResponse'
                title: Card 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'
  /batches/{cardEnrichmentBatchId}:
    parameters:
    - name: cardEnrichmentBatchId
      in: path
      description: ID of the batch card enrichment job
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Card Enrichment
      summary: Get the status of a batch card enrichment job
      description: 'Get the status of a batch job.

        '
      operationId: batchesCardEnrichGetStatus
      responses:
        '200':
          description: Successful operation
          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:
    CommonRequestLocation:
      type: object
      properties:
        address:
          type: string
          maxLength: 256
          examples:
          - 1234 W 5th Ave Suite 100
        city:
          type: string
          maxLength: 256
          examples:
          - New York
          description: 'The city as it appears in the transaction data; in some cases this can be a phone number or website, which are also valid inputs.

            '
        region:
          type: string
          maxLength: 256
          examples:
          - NY
          description: 'Two letter code for state, province, territory, etc. For US states, ANSI codes may be provided instead (e.g. "15" for Hawaii). While standard two-letter or ANSI codes are preferred when available, full region names may also be provided (e.g. "Hawaii"). *For an enhanced response, we \*strongly\* recommend including this field.*

            '
        country:
          type: string
          maxLength: 256
          examples:
          - USA
          description: Three letter country code.
        postalCode:
          type: string
          maxLength: 32
          examples:
          - '10001'
          description: A US zip code or other international postal code. In the case where a US zip code is provided and the state is missing, the state will be inferred from the zip code.
        latitude:
          type:
          - number
          - 'null'
          examples:
          - 45
          description: Additional latitude data related to the transaction being enriched.
        longitude:
          type:
          - number
          - 'null'
          examples:
          - 120
          description: Additional longitude data related to the transaction being enriched.
    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
    BatchCardEnrichmentResponse:
      allOf:
      - $ref: '#/components/schemas/CardEnrichmentResponse'
      - 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:
            - currencyCode:
              - This field is required.
              categoryCode:
              - 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:
     

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