GetResponse Categories API

openapi: 3.2.0
info:
  title: GetResponse APIv3 Categories API
  description: '# Limits and throttling


    GetResponse API calls are subject to throttling to ensure a high level of service for all users.'
  contact:
    name: API Support - DevZone
    url: https://app.getresponse.com/feedback.html?devzone=yes
    email: getresponse-devzone@cs.getresponse.com
  version: 3.2026-07-28T07:58:55+00:00
  x-logo:
    url: https://us-ws.gr-cdn.com/images/global/getresponse.png
servers:
- url: https://api.getresponse.com/v3
  description: GetResponse
- url: https://api3.getresponse360.com/v3
  description: GetResponse MAX US
- url: https://api3.getresponse360.pl/v3
  description: GetResponse MAX PL
tags:
- name: Categories
  description: Categories API documentation
paths:
  /shops/{shopId}/categories:
    parameters:
    - $ref: '#/components/parameters/shopId'
    get:
      tags:
      - Categories
      summary: Get the shop categories list
      description: 'Sending a **GET** request to this URL returns a collection of category resources that belong to the given shop.


        You can narrow down the list of resources by passing proper query parameters (the list of which you can find below in the request params section). You can basically search by:

        *name

        * createdOn

        * parentId


        The `name` fields can be a pattern and we''ll try to match this phrase.


        The `parentId` will search for sub-categories of a given parent category.


        You can filter the resource using criteria specified as `query[*]`. You can provide multiple criteria, to use AND logic. You can sort the resource using parameters specified as `sort[*]`. You can specify multiple fields to sort by.'
      operationId: getCategories
      parameters:
      - name: query[name]
        in: query
        description: Search category by name
        required: false
        schema:
          type: string
      - name: query[parentId]
        in: query
        description: Search categories by their parent
        required: false
        schema:
          type: string
      - name: query[externalId]
        in: query
        description: Search categories by external ID
        required: false
        schema:
          type: string
      - name: search[createdAt][from]
        in: query
        description: Show categories starting from this date
        required: false
        schema:
          type: string
          format: date-time
      - name: search[createdAt][to]
        in: query
        description: Show categories starting to this date
        required: false
        schema:
          type: string
          format: date-time
      - name: sort[name]
        in: query
        description: Sort by name
        required: false
        schema:
          $ref: '#/components/schemas/SortOrderEnum'
      - name: sort[createdAt]
        in: query
        description: Sort by date
        required: false
        schema:
          $ref: '#/components/schemas/SortOrderEnum'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/PerPage'
      - $ref: '#/components/parameters/Page'
      responses:
        '200':
          $ref: '#/components/responses/CategoryList'
        '400':
          description: Request validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 400
                    code: 1000
                    codeDescription: General error of validation process, more details should be in context section
                    message: Validation error, see context section for more information
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1000
                    context:
                      validationType: searchFilter[query]
                      fieldName: name
                      originalName: lorem-ipsum
                      errorDescription: Not allowed search field
                    uuid: 77dabfd1-1fa7-4f9f-8d3f-487b4403e3aa
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 401
                    code: 1014
                    codeDescription: Problem during authentication process, check headers!
                    message: Unable to authenticate request. Check credentials or authentication method details
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1014
                    context:
                      authenticationType: auth_token
                    uuid: 62417847-4f12-4c25-9b3a-0b619a187efe
        '429':
          description: The throttling limit has been reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 429
                    code: 1015
                    codeDescription: Too many request to API, quota reached, please wait till next quota window
                    message: You have reached your requests limit for this time window, please wait...
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1015
                    context:
                      currentLimit: 30000
                      timeToReset: 100 seconds
                    uuid: 510c6726-7f65-46b7-a798-ca403133924f
      security:
      - api-key: []
      - oauth2:
        - all
    post:
      tags:
      - Categories
      summary: Create category
      description: 'Create shop category. You can pass the `parentId` parameter to create a sub-category of a given parent. Unlike most **POST** methods, this call is idempotent, that is: sending the same request 10 times will not create 10 new categories. Only one category will be created.'
      operationId: createCategory
      requestBody:
        $ref: '#/components/requestBodies/NewCategory'
      responses:
        '201':
          $ref: '#/components/responses/CategoryDetails'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 404
                    code: 1013
                    codeDescription: The requested resource was not found
                    message: Resource not found
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1013
                    context:
                      contactId: pVyRW
                    uuid: 87b90a96-5ee5-4ca4-8180-ac00adcf62c7
        '400':
          description: Request validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 400
                    code: 1000
                    codeDescription: General error of validation process, more details should be in context section
                    message: Validation error, see context section for more information
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1000
                    context:
                      validationType: searchFilter[query]
                      fieldName: name
                      originalName: lorem-ipsum
                      errorDescription: Not allowed search field
                    uuid: 77dabfd1-1fa7-4f9f-8d3f-487b4403e3aa
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 401
                    code: 1014
                    codeDescription: Problem during authentication process, check headers!
                    message: Unable to authenticate request. Check credentials or authentication method details
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1014
                    context:
                      authenticationType: auth_token
                    uuid: 62417847-4f12-4c25-9b3a-0b619a187efe
        '429':
          description: The throttling limit has been reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 429
                    code: 1015
                    codeDescription: Too many request to API, quota reached, please wait till next quota window
                    message: You have reached your requests limit for this time window, please wait...
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1015
                    context:
                      currentLimit: 30000
                      timeToReset: 100 seconds
                    uuid: 510c6726-7f65-46b7-a798-ca403133924f
      security:
      - api-key: []
      - oauth2:
        - all
  /shops/{shopId}/categories/{categoryId}:
    parameters:
    - $ref: '#/components/parameters/shopId'
    - $ref: '#/components/parameters/categoryId'
    get:
      tags:
      - Categories
      summary: Get a single category by ID
      description: This method returns a category according to the given `categoryId`.
      operationId: getCategory
      parameters:
      - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          $ref: '#/components/responses/CategoryDetails'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 404
                    code: 1013
                    codeDescription: The requested resource was not found
                    message: Resource not found
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1013
                    context:
                      contactId: pVyRW
                    uuid: 87b90a96-5ee5-4ca4-8180-ac00adcf62c7
        '400':
          description: Request validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 400
                    code: 1000
                    codeDescription: General error of validation process, more details should be in context section
                    message: Validation error, see context section for more information
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1000
                    context:
                      validationType: searchFilter[query]
                      fieldName: name
                      originalName: lorem-ipsum
                      errorDescription: Not allowed search field
                    uuid: 77dabfd1-1fa7-4f9f-8d3f-487b4403e3aa
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 401
                    code: 1014
                    codeDescription: Problem during authentication process, check headers!
                    message: Unable to authenticate request. Check credentials or authentication method details
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1014
                    context:
                      authenticationType: auth_token
                    uuid: 62417847-4f12-4c25-9b3a-0b619a187efe
        '429':
          description: The throttling limit has been reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 429
                    code: 1015
                    codeDescription: Too many request to API, quota reached, please wait till next quota window
                    message: You have reached your requests limit for this time window, please wait...
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1015
                    context:
                      currentLimit: 30000
                      timeToReset: 100 seconds
                    uuid: 510c6726-7f65-46b7-a798-ca403133924f
      security:
      - api-key: []
      - oauth2:
        - all
    post:
      tags:
      - Categories
      summary: Update category
      description: Update the properties of the shop category. You can specify a `parentId` to assign a category as sub-category for an existing category. You should send only those fields that need to be changed. The rest of the properties will stay the same.
      operationId: updateCategory
      requestBody:
        $ref: '#/components/requestBodies/UpdateCategory'
      responses:
        '200':
          $ref: '#/components/responses/CategoryDetails'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 404
                    code: 1013
                    codeDescription: The requested resource was not found
                    message: Resource not found
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1013
                    context:
                      contactId: pVyRW
                    uuid: 87b90a96-5ee5-4ca4-8180-ac00adcf62c7
        '400':
          description: Request validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 400
                    code: 1000
                    codeDescription: General error of validation process, more details should be in context section
                    message: Validation error, see context section for more information
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1000
                    context:
                      validationType: searchFilter[query]
                      fieldName: name
                      originalName: lorem-ipsum
                      errorDescription: Not allowed search field
                    uuid: 77dabfd1-1fa7-4f9f-8d3f-487b4403e3aa
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 401
                    code: 1014
                    codeDescription: Problem during authentication process, check headers!
                    message: Unable to authenticate request. Check credentials or authentication method details
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1014
                    context:
                      authenticationType: auth_token
                    uuid: 62417847-4f12-4c25-9b3a-0b619a187efe
        '429':
          description: The throttling limit has been reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 429
                    code: 1015
                    codeDescription: Too many request to API, quota reached, please wait till next quota window
                    message: You have reached your requests limit for this time window, please wait...
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1015
                    context:
                      currentLimit: 30000
                      timeToReset: 100 seconds
                    uuid: 510c6726-7f65-46b7-a798-ca403133924f
      security:
      - api-key: []
      - oauth2:
        - all
    delete:
      tags:
      - Categories
      summary: Delete category
      description: ''
      operationId: deleteCategory
      responses:
        '204':
          description: Delete category
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 404
                    code: 1013
                    codeDescription: The requested resource was not found
                    message: Resource not found
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1013
                    context:
                      contactId: pVyRW
                    uuid: 87b90a96-5ee5-4ca4-8180-ac00adcf62c7
        '400':
          description: Request validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 400
                    code: 1000
                    codeDescription: General error of validation process, more details should be in context section
                    message: Validation error, see context section for more information
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1000
                    context:
                      validationType: searchFilter[query]
                      fieldName: name
                      originalName: lorem-ipsum
                      errorDescription: Not allowed search field
                    uuid: 77dabfd1-1fa7-4f9f-8d3f-487b4403e3aa
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 401
                    code: 1014
                    codeDescription: Problem during authentication process, check headers!
                    message: Unable to authenticate request. Check credentials or authentication method details
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1014
                    context:
                      authenticationType: auth_token
                    uuid: 62417847-4f12-4c25-9b3a-0b619a187efe
        '429':
          description: The throttling limit has been reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 429
                    code: 1015
                    codeDescription: Too many request to API, quota reached, please wait till next quota window
                    message: You have reached your requests limit for this time window, please wait...
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1015
                    context:
                      currentLimit: 30000
                      timeToReset: 100 seconds
                    uuid: 510c6726-7f65-46b7-a798-ca403133924f
      security:
      - api-key: []
      - oauth2:
        - all
components:
  headers:
    RateLimitLimit:
      description: The total number of requests available per time frame
      schema:
        type: integer
        format: int32
    RateLimitReset:
      description: Seconds left in the current time frame, e.g. "432 seconds"
      schema:
        type: string
    TotalPages:
      description: The total number of pages
      schema:
        type: integer
        format: int32
    RateLimitRemaining:
      description: The number of requests left in the current time frame
      schema:
        type: integer
        format: int32
    CurrentPage:
      description: The current page number
      schema:
        type: integer
        format: int32
    TotalCount:
      description: The total number of resources found for the specified conditions
      schema:
        type: integer
        format: int32
  schemas:
    ErrorResponse:
      required:
      - httpStatus
      - code
      - codeDescription
      - message
      - moreInfo
      - context
      - uuid
      properties:
        httpStatus:
          description: HTTP response code
          type: integer
          format: int32
        code:
          description: API error code
          type: integer
          format: int32
        codeDescription:
          description: API error code description
          type: string
        message:
          description: Error message
          type: string
        moreInfo:
          description: URL to error description in the API Docs
          type: string
        context:
          type: object
        uuid:
          description: UUID of the error response
          type: string
      type: object
    Category:
      type: object
      allOf:
      - $ref: '#/components/schemas/BaseCategory'
      - $ref: '#/components/schemas/CreateAndUpdate'
    SortOrderEnum:
      type: string
      enum:
      - ASC
      - DESC
    BaseCategory:
      properties:
        categoryId:
          description: The category ID
          type: string
          readOnly: true
          example: atQ
        href:
          description: Direct hyperlink to a resource
          type: string
          format: uri
          readOnly: true
          example: https://api.getresponse.com/v3/shops/pf3/categories/atQ
        name:
          description: The name of the category
          type: string
          maxLength: 64
          minLength: 2
          example: Headwear
        parentId:
          description: The parent category ID
          type: string
          maxLength: 64
          minLength: 2
          example: amh
        isDefault:
          description: This is a default category
          type: boolean
          example: true
        url:
          description: The external URL to the category
          type: string
          format: uri
          maxLength: 2048
          example: https://somedomain.com/category/446
        externalId:
          description: The external ID is the identifying string or number of the category given by another software
          type: string
          maxLength: 255
          example: ext3343
      type: object
    CreateAndUpdate:
      properties:
        createdOn:
          description: The creation date
          type: string
          format: date-time
          readOnly: true
        updatedOn:
          description: The date of the last update
          type: string
          format: date-time
          readOnly: true
      type: object
    NewCategory:
      required:
      - name
      type: object
      allOf:
      - $ref: '#/components/schemas/BaseCategory'
      - $ref: '#/components/schemas/CreateAndUpdate'
  parameters:
    PerPage:
      name: perPage
      in: query
      description: Requested number of results per page
      required: false
      schema:
        type: integer
        format: int32
        default: 100
        maximum: 1000
        minimum: 1
    categoryId:
      name: categoryId
      in: path
      description: The category ID
      required: true
      schema:
        type: string
      example: C3s
    Page:
      name: page
      in: query
      description: Page number
      required: false
      schema:
        type: integer
        format: int32
        default: 1
        minimum: 1
    Fields:
      name: fields
      in: query
      description: List of fields that should be returned. Id is always returned. Fields should be separated by comma
      required: false
      schema:
        type: string
    shopId:
      name: shopId
      in: path
      description: The shop ID
      required: true
      schema:
        type: string
      example: pf3
  responses:
    CategoryList:
      description: The list of categories
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        CurrentPage:
          $ref: '#/components/headers/CurrentPage'
        TotalPages:
          $ref: '#/components/headers/TotalPages'
        TotalCount:
          $ref: '#/components/headers/TotalCount'
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Category'
    CategoryDetails:
      description: The category details
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Category'
  requestBodies:
    UpdateCategory:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Category'
    NewCategory:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NewCategory'
  securitySchemes:
    api-key:
      type: apiKey
      description: Header value must be prefixed with api-key
      name: X-Auth-Token
      in: header
    oauth2:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://app.getresponse.com/oauth2_authorize.html
          scopes:
            all: all data access
        authorizationCode:
          authorizationUrl: https://app.getresponse.com/oauth2_authorize.html
          tokenUrl: https://api.getresponse.com/v3/token
          scopes:
            all: all data access
        clientCredentials:
          tokenUrl: https://api.getresponse.com/v3/token
          scopes:
            all: all data access
externalDocs:
  description: Find out more about API
  url: https://apidocs.getresponse.com
x-tagGroups:
- name: User
  tags:
  - Accounts
  - Multimedia
  - File Library
- name: Contacts
  tags:
  - Campaigns (Lists)
  - Contacts
  - Custom Fields
  - Search Contacts
  - Subscription Confirmations
  - Predefined Fields
  - Suppressions
  - Imports
- name: Email Marketing
  tags:
  - Newsletters
  - Autoresponders
  - RSS Newsletters
  - Legacy Landing Pages
  - From Fields
  - A/B tests
  - A/B tests - subject
  - Click Tracks
- name: Tags
  tags:
  - Tags
- name: GDPR Fields
  tags:
  - GDPR Fields
- name: Forms and surveys
  tags:
  - Legacy Forms
  - Forms
- name: Automation
  tags:
  - Workflows
  - Custom Events
  - Tracking
- name: Ecommerce
  tags:
  - Addresses
  - Carts
  - Categories
  - Meta Fields
  - Orders
  - Products
  - Product Variants
  - Shops
  - Taxes
- name: Transactional Emails
  tags:
  - Transactional Emails
  - Transactional Emails Templates
- name: SMS
  tags:
  - SMS Messages
  - SMS Automation Messages
- name: Statistics
  tags:
  - Ecommerce
  - Sms
  - Website
  - Landing Page
  - Form and Popup
- name: Webinars
  tags:
  - Webinars
- name: Websites
  tags:
  - Websites
  - Landing Pages
- name: Forms and Popups
  tags:
  - Forms and Popups
- name: Custom Reports
  tags:
  - Custom Reports