> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spade.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get categories

> 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](https://docs.spade.com/reference/user-category-personalization-guide).



## OpenAPI

````yaml /api-reference/spec.yml get /users/{userId}/categories
openapi: 3.1.0
info:
  title: Spade 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
  - name: Transfer Enrichment
    description: Enrich transfers
  - name: Category Personalization
    description: Create custom categories and personalize enrichments
  - name: Feedback and Reporting
    description: Provide feedback on card events or report enrichment errors
  - name: Merchant Search
    description: Search for Spade merchants
  - name: Merchant Action Triggers
    description: >-
      Register merchant action triggers and receive triggered actions in
      enrichment responses
  - name: Category Action Triggers
    description: >-
      Register category action triggers and receive triggered actions in
      enrichment responses
paths:
  /users/{userId}/categories:
    parameters:
      - in: path
        name: userId
        schema:
          type: string
        description: The `userId` of the relevant user.
        required: true
    get:
      tags:
        - Category Personalization
      summary: Get categories
      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](https://docs.spade.com/reference/user-category-personalization-guide).
      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'
components:
  schemas:
    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.
    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

````