Spade Category Personalization API

openapi: 3.2.0
info:
  title: Spade Category Personalization 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 .
  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: Category Personalization
  description: Create custom categories and personalize enrichments
paths:
  /categories:
    get:
      description: 'Fetch categories from Spade''s database.


        This endpoint returns a list containing Spade''s default categories, plus any custom integration-level categories you''ve created.


        To learn more about category personalization, please read the Category Personalization Guide.'
      tags:
      - Category Personalization
      summary: Get all default and custom integration-level categories
      operationId: categoriesGet
      parameters:
      - in: query
        name: include
        schema:
          type: string
          examples:
          - default
          - custom
          - default,custom
        description: An optional comma-separated string specifying which category types to include. Valid values include 'default', 'custom', 'default,custom'.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                description: An array of categories. Spade categories are returned first, followed by custom categories.
                items:
                  $ref: '#/components/schemas/MerchantCategory'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      description: 'Create a custom integration-level category.


        This category will be available to all users of your integration.


        To learn more about category personalization, please read the Category Personalization Guide.'
      tags:
      - Category Personalization
      summary: Create a custom integration-level category
      operationId: categoriesPost
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommonPostCategoriesRequest'
        required: true
      responses:
        '201':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                description: The newly created category.
                $ref: '#/components/schemas/CustomCategory'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      description: 'Delete all custom integration-level categories.


        To learn more about category personalization, please read the Category Personalization Guide.'
      tags:
      - Category Personalization
      summary: Delete all custom integration-level categories
      operationId: categoriesDelete
      responses:
        '204':
          description: Successful operation
        '403':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /categories/{id}:
    parameters:
    - in: path
      name: id
      schema:
        type: string
      description: The `id` of the relevant category.
      required: true
    delete:
      description: 'Delete a custom integration-level category.


        To learn more about category personalization, please read the Category Personalization Guide.'
      tags:
      - Category Personalization
      summary: Delete a custom integration-level category
      operationId: categoriesDetailDelete
      responses:
        '204':
          description: Successful operation
        '403':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /counterparty-category-personalizations:
    get:
      description: 'Fetch counterparty category personalizations from Spade''s database.


        This endpoint returns a list containing all integration-level counterparty category personalizations for your integration.


        To learn more about category personalization, please read the Category Personalization Guide.'
      tags:
      - Category Personalization
      summary: Get all integration-level counterparty category personalizations
      operationId: counterpartyCategoryPersonalizationsGet
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                description: An array of counterparty category personalizations.
                items:
                  $ref: '#/components/schemas/CounterpartyCategoryPersonalization'
        '403':
          description: Unauthorized
        '500':
          description: Unexpected Error
    put:
      description: 'Create an integration-level counterparty category personalization.


        This personalization will apply to all enrichments that take place at the given `counterpartyId` for your integration.


        To learn more about category personalization, please read the Category Personalization Guide.'
      tags:
      - Category Personalization
      summary: Create an integration-level counterparty category personalization
      operationId: counterpartyCategoryPersonalizationsPut
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CounterpartyCategoryPersonalization'
        required: true
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CounterpartyCategoryPersonalization'
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CounterpartyCategoryPersonalization'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      description: 'Delete all integration-level counterparty category personalizations.


        To learn more about category personalization, please read the Category Personalization Guide.'
      tags:
      - Category Personalization
      summary: Delete all integration-level counterparty category personalizations
      operationId: counterpartyCategoryPersonalizationsDelete
      responses:
        '204':
          description: Successful operation
        '403':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /counterparty-category-personalizations/{counterpartyId}:
    parameters:
    - in: path
      name: counterpartyId
      schema:
        type: string
      description: The `counterpartyId` of the relevant counterparty category personalization.
      required: true
    delete:
      description: 'Delete a counterparty category personalization.


        To learn more about category personalization, please read the Category Personalization Guide.'
      tags:
      - Category Personalization
      summary: Delete a counterparty category personalization
      operationId: counterpartyCategoryPersonalizationsDetailDelete
      responses:
        '204':
          description: Successful operation
        '403':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /users/{userId}/categories:
    parameters:
    - in: path
      name: userId
      schema:
        type: string
      description: The `userId` of the relevant user.
      required: true
    get:
      description: 'Fetch custom user-level categories from Spade''s database.


        This endpoint returns a list containing all custom categories that the user with the given `userId` has created.


        To learn more about user category personalization, please read the User Category Personalization Guide.'
      tags:
      - Category Personalization
      summary: Get categories
      operationId: userCategoriesGet
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                description: An array of categories. Spade categories are returned first, followed by custom categories.
                items:
                  $ref: '#/components/schemas/CustomCategory'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      description: 'Create a custom user-level category.


        To learn more about user category personalization, please read the User Category Personalization Guide.'
      tags:
      - Category Personalization
      summary: Create a custom user-level category
      operationId: userCategoriesPost
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommonPostCategoriesRequest'
        required: true
      responses:
        '201':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                description: The newly created category.
                $ref: '#/components/schemas/CustomCategory'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      description: 'Delete all custom user-level categories.


        To learn more about user category personalization, please read the User Category Personalization Guide.'
      tags:
      - Category Personalization
      summary: Delete all custom user-level categories
      operationId: userCategoriesDelete
      responses:
        '204':
          description: Successful operation
        '403':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /users/{userId}/categories/{id}:
    parameters:
    - in: path
      name: userId
      schema:
        type: string
      description: The `userId` of the relevant user.
      required: true
    - in: path
      name: id
      schema:
        type: string
      description: The `id` of the relevant category.
      required: true
    delete:
      description: 'Delete a custom user-level category.


        To learn more about user category personalization, please read the User Category Personalization Guide.'
      tags:
      - Category Personalization
      summary: Delete a custom user-level category
      operationId: userCategoriesDetailDelete
      responses:
        '204':
          description: Successful operation
        '403':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /users/{userId}/counterparty-category-personalizations:
    parameters:
    - in: path
      name: userId
      schema:
        type: string
      description: The `userId` of the relevant user.
      required: true
    get:
      description: 'Fetch user-level counterparty category personalizations from Spade''s database.


        This endpoint returns a list containing all user-level counterparty category personalizations for the user with the given `userId`.


        To learn more about user category personalization, please read the User Category Personalization Guide.'
      tags:
      - Category Personalization
      summary: Get all user-level counterparty category personalizations
      operationId: userCounterpartyCategoryPersonalizationsGet
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                description: An array of counterparty category personalizations.
                items:
                  allOf:
                  - $ref: '#/components/schemas/CounterpartyCategoryPersonalization'
                  - type: object
                    description: The newly created counterparty category personalization.
                    properties:
                      userId:
                        type: string
                        description: The ID of the newly created counterparty category personalization.
                        examples:
                        - user1234
        '403':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      description: 'Create a user-level counterparty category personalization.


        This personalization will apply to all enrichments that take place at the given `counterpartyId` for the user with the given `userId`.


        To learn more about user category personalization, please read the User Category Personalization Guide.'
      tags:
      - Category Personalization
      summary: Create a user-level counterparty category personalization
      operationId: userCounterpartyCategoryPersonalizationsPut
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CounterpartyCategoryPersonalization'
        required: true
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CounterpartyCategoryPersonalization'
                - type: object
                  description: The newly created counterparty category personalization.
                  properties:
                    userId:
                      type: string
                      description: The ID of the newly created counterparty category personalization.
                      examples:
                      - user1234
        '201':
          description: Created
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CounterpartyCategoryPersonalization'
                - type: object
                  description: The newly created counterparty category personalization.
                  properties:
                    userId:
                      type: string
                      description: The ID of the newly created counterparty category personalization.
                      examples:
                      - user1234
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      description: 'Delete all user-level counterparty category personalizations.


        To learn more about user category personalization, please read the User Category Personalization Guide.'
      tags:
      - Category Personalization
      summary: Delete all user-level counterparty category personalizations
      operationId: userCounterpartyCategoryPersonalizationsDelete
      responses:
        '204':
          description: Successful operation
        '403':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /users/{userId}/counterparty-category-personalizations/{counterpartyId}:
    parameters:
    - in: path
      name: userId
      schema:
        type: string
      description: The `userId` of the relevant user.
      required: true
    - in: path
      name: counterpartyId
      schema:
        type: string
      description: The `counterpartyId` of the relevant counterparty category personalization.
      required: true
    delete:
      description: 'Delete a user-level counterparty category personalization.


        To learn more about user category personalization, please read the User Category Personalization Guide.'
      tags:
      - Category Personalization
      summary: Delete a user-level counterparty category personalization
      operationId: userCounterpartyCategoryPersonalizationsDetailDelete
      responses:
        '204':
          description: Successful operation
        '403':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    CommonPostCategoriesRequest:
      type: object
      description: Schema for creating a custom category.
      required:
      - name
      - parentId
      properties:
        name:
          type: string
          description: The name of the category (must be unique per integration / user).
          examples:
          - Kitchen Remodel
        parentId:
          type: string
          description: The ID of the new category's parent. Can be a Spade category ID (e.g. "011-000-000-000") or a custom category ID (e.g. "e4cf5379-583f-44ed-b625-366044e666e6").
          examples:
          - 011-000-000-000
    MerchantCategory:
      type: object
      properties:
        id:
          type:
          - string
          examples:
          - 011-010-000-000
          description: 'A unique identifier for this category. This identifier will show up in enrichments as `counterparty[i].industry[-1].id`, where `i` is the index of this merchant in the counterparty list. Note that each counterparty''s `industry` is a list containing its full category hierarchy (including parent categories); thus, this category will be the last one in the `industry` list.

            '
        name:
          type:
          - string
          examples:
          - Online Marketplace
          description: The category's name
        icon:
          type:
          - string
          - 'null'
          format: url
          examples:
          - https://static.v2.spadeapi.com/categories/b4b0d249b40249acb7445027d4574fc5/light.png
          description: The category's icon
        fullCategoryHierarchy:
          description: Array with increasingly specific category information.
          type: array
          items:
            $ref: '#/components/schemas/IndustryCategoryLevel'
          examples:
          - - id: 011-000-000-000
              name: Retail
              icon: https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png
            - id: 011-010-000-000
              name: Online Marketplace
              icon: https://static.v2.spadeapi.com/categories/b4b0d249b40249acb7445027d4574fc5/light.png
    CounterpartyCategoryPersonalization:
      type: object
      description: Schema for creating a counterparty category personalization.
      required:
      - counterpartyId
      - categoryId
      properties:
        counterpartyId:
          type: string
          description: The ID of the counterparty.
          examples:
          - d730906b-f1a8-49f1-9939-f27390170a6d
        categoryId:
          type: string
          description: The ID of the category. Can be a Spade category ID (e.g. "011-000-000-000") or a custom category ID (e.g. "e4cf5379-583f-44ed-b625-366044e666e6").
          examples:
          - 011-000-000-000
    CustomCategory:
      type: object
      properties:
        id:
          type:
          - string
          examples:
          - 4d5419f1-bcde-40f5-9168-7f8989b9c55f
          description: A unique identifier for this category.
        name:
          type:
          - string
          examples:
          - Kitchen Remodel
          description: The category's name
        icon:
          type:
          - string
          - 'null'
          format: url
          examples:
          - https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png
          description: The category's icon, potentially inherited from the parent category.
        fullCategoryHierarchy:
          description: Array with increasingly specific category information.
          type: array
          items:
            $ref: '#/components/schemas/IndustryCategoryLevel'
          examples:
          - - id: 011-000-000-000
              name: Retail
              icon: https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png
            - id: 4d5419f1-bcde-40f5-9168-7f8989b9c55f
              name: Kitchen Remodel
              icon: https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png
    IndustryCategoryLevel:
      description: A node in a tree representing a hierarchical category system
      type: object
      properties:
        id:
          type: string
          maxLength: 15
          examples:
          - 011-000-000-000
        name:
          type: string
          maxLength: 64
          examples:
          - Retail
        icon:
          type:
          - string
          - 'null'
          maxLength: 128
          format: url
          examples:
          - https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png
          description: Category icon.
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              details:
                type: string
                examples:
                - Incorrect authentication credentials.
    BadRequest:
      description: Invalid input
      content:
        application/json:
          schema:
            type: object
            properties:
              invalidField:
                type: array
                items:
                  type: string
                  examples:
                  - This field is required.
    InternalServerError:
      description: Unexpected Error
      content:
        application/json:
          schema:
            type: object
            properties:
              details:
                type: string
                examples:
                - Internal server error.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-Api-Key
      in: header