Up Categories API

openapi: 3.0.3
info:
  contact:
    email: contact@dsb.gov.au
    name: Data Standards Body
    url: https://dsb.gov.au/
  description: Specifications for resource endpoints applicable to data holders in the Banking sector.
  license:
    name: MIT License
    url: https://opensource.org/licenses/MIT
  title: CDR Banking Accounts Categories API
  version: 1.36.0
servers:
- description: MTLS
  url: https://mtls.dh.example.com/cds-au/v1
tags:
- name: Categories
  description: 'Categories enable understanding where your money goes by driving

    powerful insights in Up. All categories in Up are pre-defined

    and are automatically assigned to new purchases in most cases. A

    parent-child relationship is used to represent categories,

    however parent categories cannot be directly assigned to

    transactions.

    '
paths:
  /categories:
    get:
      tags:
      - Categories
      summary: List categories
      description: 'Retrieve a list of all categories and their ancestry. The returned list

        is not paginated.

        '
      parameters:
      - name: filter[parent]
        in: query
        schema:
          type: string
        required: false
        example: good-life
        description: 'The unique identifier of a parent category for which to

          return only its children. Providing an invalid category

          identifier results in a `404` response.

          '
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCategoriesResponse'
          x-up:example:
            type: exampleRequestResponse
            request:
              headers:
                Authorization: Bearer up:demo:OTFUmA1YX3oq9Mtp
              pathParameters: {}
              queryParameters:
                filter[parent]: good-life
              payload: null
            response:
              data:
              - type: categories
                id: hobbies
                attributes:
                  name: Hobbies
                relationships:
                  parent:
                    data:
                      type: categories
                      id: good-life
                    links:
                      related: https://api.up.com.au/api/v1/categories/good-life
                  children:
                    data: []
                    links:
                      related: https://api.up.com.au/api/v1/categories?filter%5Bparent%5D=hobbies
                links:
                  self: https://api.up.com.au/api/v1/categories/hobbies
              - type: categories
                id: restaurants-and-cafes
                attributes:
                  name: Restaurants & Cafes
                relationships:
                  parent:
                    data:
                      type: categories
                      id: good-life
                    links:
                      related: https://api.up.com.au/api/v1/categories/good-life
                  children:
                    data: []
                    links:
                      related: https://api.up.com.au/api/v1/categories?filter%5Bparent%5D=restaurants-and-cafes
                links:
                  self: https://api.up.com.au/api/v1/categories/restaurants-and-cafes
  /categories/{id}:
    get:
      tags:
      - Categories
      summary: Retrieve category
      description: 'Retrieve a specific category by providing its unique identifier.

        '
      parameters:
      - name: id
        in: path
        schema:
          type: string
        required: true
        example: restaurants-and-cafes
        description: 'The unique identifier for the category.

          '
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCategoryResponse'
          x-up:example:
            type: exampleRequestResponse
            request:
              headers:
                Authorization: Bearer up:demo:h3cqAp7XGqD2Jpg4
              pathParameters:
                id: home
              queryParameters: {}
              payload: null
            response:
              data:
                type: categories
                id: home
                attributes:
                  name: Home
                relationships:
                  parent:
                    data: null
                  children:
                    data:
                    - type: categories
                      id: groceries
                    links:
                      related: https://api.up.com.au/api/v1/categories?filter%5Bparent%5D=home
                links:
                  self: https://api.up.com.au/api/v1/categories/home
  /transactions/{transactionId}/relationships/category:
    patch:
      tags:
      - Categories
      summary: Categorize transaction
      description: 'Updates the category associated with a transaction. Only transactions

        for which `isCategorizable` is set to true support this operation. The

        `id` is taken from the list exposed on `/categories` and cannot be one of

        the top-level (parent) categories. To de-categorize a transaction, set

        the entire `data` key to `null`. An HTTP `204` is returned on success.

        The associated category, along with its request URL is also exposed via

        the `category` relationship on the transaction resource returned from

        `/transactions/{id}`.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTransactionCategoryRequest'
      parameters:
      - name: transactionId
        in: path
        schema:
          type: string
        required: true
        example: 88b4ed70-7f15-4b46-a676-46aafad4c183
        description: 'The unique identifier for the transaction.

          '
      responses:
        '204':
          description: Successful Response
          x-up:example:
            type: exampleRequestResponse
            request:
              headers:
                Authorization: Bearer up:demo:jxaEroUCArojsqOr
                Content-Type: application/json
              pathParameters:
                transactionId: b2372db2-f032-4350-b276-bfe25467087b
              queryParameters: {}
              payload:
                data:
                  type: categories
                  id: restaurants-and-cafes
            response: null
components:
  schemas:
    CategoryResource:
      type: object
      description: 'Provides information about a category and its ancestry.

        '
      properties:
        type:
          type: string
          description: 'The type of this resource: `categories`'
        id:
          type: string
          description: 'The unique identifier for this category. This is a human-readable but

            URL-safe value.

            '
        attributes:
          type: object
          properties:
            name:
              type: string
              description: 'The name of this category as seen in the Up application.

                '
          required:
          - name
        relationships:
          type: object
          properties:
            parent:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    type:
                      type: string
                      description: 'The type of this resource: `categories`'
                    id:
                      type: string
                      description: 'The unique identifier of the resource within its type.

                        '
                  required:
                  - type
                  - id
                  nullable: true
                links:
                  type: object
                  properties:
                    related:
                      type: string
                      description: 'The link to retrieve the related resource(s) in this relationship.

                        '
                  required:
                  - related
              required:
              - data
            children:
              type: object
              properties:
                data:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        description: 'The type of this resource: `categories`'
                      id:
                        type: string
                        description: 'The unique identifier of the resource within its type.

                          '
                    required:
                    - type
                    - id
                links:
                  type: object
                  properties:
                    related:
                      type: string
                      description: 'The link to retrieve the related resource(s) in this relationship.

                        '
                  required:
                  - related
              required:
              - data
          required:
          - parent
          - children
        links:
          type: object
          properties:
            self:
              type: string
              description: 'The canonical link to this resource within the API.

                '
          required:
          - self
      required:
      - type
      - id
      - attributes
      - relationships
    ListCategoriesResponse:
      type: object
      description: 'Successful response to get all categories and their ancestry. The

        returned list is not paginated.

        '
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CategoryResource'
          description: 'The list of categories returned in this response.

            '
      required:
      - data
    GetCategoryResponse:
      type: object
      description: 'Successful response to get a single category and its ancestry.

        '
      properties:
        data:
          description: 'The category returned in this response.

            '
          allOf:
          - $ref: '#/components/schemas/CategoryResource'
      required:
      - data
    UpdateTransactionCategoryRequest:
      type: object
      description: 'Request to update the category associated with a transaction.

        '
      properties:
        data:
          nullable: true
          description: 'The category to set on the transaction. Set this entire key to `null`

            de-categorize a transaction.

            '
          allOf:
          - $ref: '#/components/schemas/CategoryInputResourceIdentifier'
      required:
      - data
    CategoryInputResourceIdentifier:
      type: object
      description: 'Uniquely identifies a category in the API.

        '
      properties:
        type:
          type: string
          description: 'The type of this resource: `categories`'
        id:
          type: string
          description: 'The unique identifier of the category, as returned by the `/categories`

            endpoint.

            '
      required:
      - type
      - id