Yokoy Expense category API

openapi: 3.2.0
info:
  description: Public API of the Yokoy Application
  title: Yokoy Card account Expense category API
  version: 1.41.0
servers:
- description: API server scoped to organization with ID `organizationId`
  url: https://api.yokoy.ai/v1/organizations/{organizationId}
  variables:
    organizationId:
      default: AbcDeF1234
      description: Yokoy organization ID
- description: API test server scoped to organization with ID `organizationId`
  url: https://api.test.yokoy.ai/v1/organizations/{organizationId}
  variables:
    organizationId:
      default: AbcDeF1234
      description: Yokoy organization ID
tags:
- description: Categories for expenses (also called booking accounts). These categories only apply to expenses and trips. For invoices, use supplier invoice categories.
  name: Expense category
paths:
  /legal-entities/{legalEntityId}/categories:
    parameters:
    - $ref: '#/components/parameters/LegalEntityIdInPath'
    - $ref: '#/components/parameters/YokoyAuthMethod'
    - $ref: '#/components/parameters/YokoyCorrelationId'
    get:
      description: Retrieves all categories belonging to the legal entity identified in the path.
      operationId: listExpenseCategories
      parameters:
      - $ref: '#/components/parameters/QueryFilter'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  categories:
                    items:
                      $ref: '#/components/schemas/Category'
                    type: array
                type: object
          description: OK
        '400':
          $ref: '#/components/responses/InvalidFilter'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/GatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
      - OAuth2: []
      summary: List all expense categories for a legal entity
      tags:
      - Expense category
    post:
      description: Creates a new category for the legal entity specified by its Yokoy unique ID in the path. It returns the created entity.
      operationId: createExpenseCategory
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Category'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
          description: Created
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/GatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
      - OAuth2: []
      summary: Create an expense category
      tags:
      - Expense category
  /legal-entities/{legalEntityId}/categories/{categoryId}:
    parameters:
    - $ref: '#/components/parameters/LegalEntityIdInPath'
    - description: Yokoy unique ID of the expense category.
      example: 1WOspYIfp6
      in: path
      name: categoryId
      required: true
      schema:
        pattern: '[\w-]+'
        type: string
    - $ref: '#/components/parameters/YokoyAuthMethod'
    - $ref: '#/components/parameters/YokoyCorrelationId'
    get:
      description: Retrieves an expense category by specifying its Yokoy unique ID in the path.
      operationId: getExpenseCategory
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
          description: OK
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/GatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
      - OAuth2: []
      summary: Get an expense category by ID
      tags:
      - Expense category
    patch:
      description: Updates an expense category by replacing some attributes. The legal entity and expense category are specified by their unique IDs in the path. Only the attributes specified in the body are updated. Other attributes are not updated. The whole entity is returned.
      operationId: modifyExpenseCategory
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: Dictionary of expense category attributes to update. Explicit null values mark attributes for deletion.
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
          description: OK
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/GatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
      - OAuth2: []
      summary: Modify an expense category
      tags:
      - Expense category
    put:
      description: Updates an expense category by replacing all attributes. The legal entity and expense category are specified by their unique IDs in the path. Any category attributes that are not specified in the request body are updated with null or "". If any required attributes are updated as null, the category is marked as inactive. The whole entity is returned.
      operationId: updateExpenseCategory
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Category'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
          description: OK
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/GatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
      - OAuth2: []
      summary: Update an expense category
      tags:
      - Expense category
components:
  parameters:
    LegalEntityIdInPath:
      description: Yokoy unique ID of the legal entity (company).
      example: aB9jQoE3HE
      in: path
      name: legalEntityId
      required: true
      schema:
        pattern: '[\w-]+'
        type: string
    YokoyAuthMethod:
      example: yokoy
      in: header
      name: X-Yk-Auth-Method
      required: true
      schema:
        enum:
        - yokoy
        type: string
    YokoyCorrelationId:
      description: Correlation ID that can be used to trace a request in the flow.
      example: 4ea8985e-80a2-40a0-8a40-401a1a1374b3
      in: header
      name: X-Yk-Correlation-Id
      required: false
      schema:
        type: string
    QueryFilter:
      description: Filter string used to restrict the data returned. You can use [SCIM specification](https://tools.ietf.org/html/rfc7644#section-3.4.2.2) filters.
      example: created ge 2024-03-02T09:00.000Z and customInformation.customField eq foo
      in: query
      name: filter
      schema:
        type: string
  schemas:
    Category:
      properties:
        accountReference:
          description: Account (ERP). Expense account on which the expense is booked.
          example: '6300'
          type: string
        chargeToEmployee:
          description: Only applies to private expenses that are paid with the company card. If enabled, the expense is booked on the user account instead of the expense account.
          example: false
          type:
          - boolean
          - 'null'
        customInformation:
          additionalProperties:
            type: string
          description: Dictionary of custom information attributes associated with the category.
          example:
            externalId: Cat1
          type:
          - object
          - 'null'
        id:
          description: Yokoy unique ID of the expense category.
          example: 9L7rovNzNhTCsJSTkbfq
          pattern: '[\w-]+'
          readOnly: true
          type: string
        name:
          description: Name of the expense category.
          example: Lunch
          type: string
        statusActive:
          description: Status of the expense category. Only active categories can be used for new expenses.
          example: true
          type: boolean
      required:
      - name
      - accountReference
      - statusActive
      type: object
    Error:
      properties:
        code:
          type: integer
        message:
          type: string
      required:
      - code
      - message
      type: object
  responses:
    Unauthorized:
      content:
        application/json:
          example:
            code: 401
            message: Token expired
          schema:
            $ref: '#/components/schemas/Error'
      description: The server was unable to establish the identity of the client.
    GatewayError:
      content:
        application/json:
          example:
            code: 502
            message: Gateway error
          schema:
            $ref: '#/components/schemas/Error'
      description: An issue occurred in a downstream service. Please try again later.
    InvalidFilter:
      content:
        application/json:
          example:
            code: 400
            message: 'Invalid filter string: foo e bar'
          schema:
            $ref: '#/components/schemas/Error'
      description: The request was not valid.
    TooManyRequests:
      content:
        application/json:
          example:
            code: 429
            message: Too many requests
          schema:
            $ref: '#/components/schemas/Error'
      description: The request cannot be processed by the server due to too many concurrent requests.
    ValidationError:
      content:
        application/json:
          example:
            code: 400
            message: 'ValidationError: name is mandatory'
          schema:
            $ref: '#/components/schemas/Error'
      description: The request was not valid.
    Forbidden:
      content:
        application/json:
          example:
            code: 403
            message: User not authorized to access organization
          schema:
            $ref: '#/components/schemas/Error'
      description: The client is not authorized to perform the requested operation.
    NotFound:
      content:
        application/json:
          example:
            code: 404
            message: Resource not found
          schema:
            $ref: '#/components/schemas/Error'
      description: The specified resource was not found.
    ServiceUnavailable:
      content:
        application/json:
          example:
            code: 503
            message: Service unavailable
          schema:
            $ref: '#/components/schemas/Error'
      description: The server is unavailable. Please try again later
    InternalError:
      content:
        application/json:
          example:
            code: 500
            message: Server error
          schema:
            $ref: '#/components/schemas/Error'
      description: An internal error occurred.
  securitySchemes:
    OAuth2:
      description: "Authentication to the Yokoy API relies on the standard OAuth2 client credentials flow.\n\n**1. Obtain an access token**\n\nPerform a `POST` request to\n`https://accounts.yokoy.ai/oauth2/token`. Pass the client ID\nand client secret as username and password in a basic auth\nheader. Set the content-type to\n`application/x-www-form-urlencoded` and specify\n`grant_type=client_credentials` in the body.\n\n> Note: For the Yokoy test environment, use `https://accounts.test.yokoy.ai/oauth2/token` instead.\n\nExample request for the client ID `ClientId` and client\nsecret `ClientSecret`:\n```\nPOST https://accounts.yokoy.ai/oauth2/token\nAuthorization: Basic Q2xpZW50SWQ6Q2xpZW50U2VjcmV0\nContent-Type: application/x-www-form-urlencoded\ngrant_type=client_credentials\n```\nIn this example, the string `Q2xpZW50SWQ6Q2xpZW50U2VjcmV0` is\nobtained by base64-encoding the string\n`ClientId:ClientSecret`, as required for basic access authentication.\n\n> Note: Yokoy does not require or use scopes.\n\n\nThe JSON response contains the access token in the attribute\n`access_token`. The response also contains the expiration in\nseconds.\n\nExample response:\n```\n{\n    \"access_token\": \"SOME_KEY\",\n    \"expires_in\": 3900,\n    \"token_type\": \"Bearer\"\n}\n```\n\n**2. Pass the bearer token**\n\nPass the access token from step 1 as a bearer token in subsequent requests to the API.\n\nExample header field for the example response from step 1:\n```\nAuthorization: Bearer 4lDvPkrBF87WHuyvlINQD\n```\n\nFor more information, see (Authentication & authorization)[https://developer.yokoy.ai/docs/overview/authentication].\n"
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://accounts[.test].yokoy.ai/oauth2/token
      type: oauth2