Yokoy
Yokoy Tag API

Tag is a custom dimension that can be added to each category that help map additional information to that spend and use it at multiple levels, such as analytics or for accounting purposes. Tags are often used to enhance Yokoy’s data model for: - **management reporting** along multi-dimensional classifications (matrix model). For example, project accounting next to cost accounting (cost centers and cost carriers/projects in a matrix), activity-based controlling (ABC) alongside cost or project accounting, or asset management (e.g. asset capitalisation schedules) - **classifications** for processing purposes. For example, approval groups independent of cost center or project accounting structure. Each tag belongs to a tag dimension. Tag dimensions are created in Yokoy (**Admin > Company**).
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.0
info:
  description: Public API of the Yokoy Application
  title: Yokoy Card account Tag 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: 'Tag is a custom dimension that can be added to each category that help map additional information to that spend and use it at multiple levels, such as analytics or for accounting purposes.

    Tags are often used to enhance Yokoy’s data model for:

    - **management reporting** along multi-dimensional classifications (matrix model).

    For example, project accounting next to cost accounting (cost centers and cost carriers/projects in a matrix), activity-based controlling (ABC) alongside cost or project accounting, or asset management (e.g. asset capitalisation schedules)

    - **classifications** for processing purposes.

    For example, approval groups independent of cost center or project accounting structure.

    Each tag belongs to a tag dimension. Tag dimensions are created in Yokoy (**Admin > Company**).

    '
  name: Tag
paths:
  /legal-entities/{legalEntityId}/tags:
    parameters:
    - $ref: '#/components/parameters/LegalEntityIdInPath'
    - $ref: '#/components/parameters/YokoyAuthMethod'
    - $ref: '#/components/parameters/YokoyCorrelationId'
    get:
      description: Retrieves all tags for the legal entity identified by its Yokoy unique ID in the path.
      operationId: listTags
      parameters:
      - $ref: '#/components/parameters/QueryFilter'
      - $ref: '#/components/parameters/PaginationCount'
      - $ref: '#/components/parameters/PaginationCursor'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  tags:
                    items:
                      $ref: '#/components/schemas/Tag'
                    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 tags
      tags:
      - Tag
    post:
      description: Creates a new tag and returns the created entity.
      operationId: createTag
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Tag'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
          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 a tag
      tags:
      - Tag
  /legal-entities/{legalEntityId}/tags/{tagId}:
    parameters:
    - $ref: '#/components/parameters/LegalEntityIdInPath'
    - description: Yokoy unique ID of the tag.
      example: CP0YGe9VwzWixLOZdTK8
      in: path
      name: tagId
      required: true
      schema:
        pattern: '[\w-]+'
        type: string
    - $ref: '#/components/parameters/YokoyAuthMethod'
    - $ref: '#/components/parameters/YokoyCorrelationId'
    delete:
      description: Deletes a tag identified by its Yokoy unique ID.
      operationId: deleteTag
      responses:
        '204':
          description: Tag deleted.
        '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: Remove a tag
      tags:
      - Tag
    get:
      description: Retrieves a tag identified by its Yokoy unique ID.
      operationId: getTag
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
          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 tag by ID
      tags:
      - Tag
    patch:
      description: Updates a tag by replacing some attributes. The tag is identified by its Yokoy unique ID passed as a path parameter. The whole entity is returned.
      operationId: modifyTag
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: Dictionary of tag attributes to update. Explicit null values mark attributes for deletion.
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
          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 a tag
      tags:
      - Tag
    put:
      description: Updates a tag identified by its Yokoy unique ID by replacing all attributes. The whole entity is returned.
      operationId: updateTag
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Tag'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
          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 a tag
      tags:
      - Tag
components:
  parameters:
    PaginationCursor:
      description: 'Optional cursor for paginating. When provided, the API fetches a subsequent page of items.

        The subsequent page is identified by the value given in `nextCursor` in the previous response.

        `cursor` can only be used if the `count` attribute is passed as a query parameter.

        '
      example: 06x2u4nagAMEq3gGMoch
      in: query
      name: cursor
      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
    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
    LegalEntityIdInPath:
      description: Yokoy unique ID of the legal entity (company).
      example: aB9jQoE3HE
      in: path
      name: legalEntityId
      required: true
      schema:
        pattern: '[\w-]+'
        type: string
    PaginationCount:
      description: 'Optional count for paginating. When provided, the results are paginated. Without `count`, no pagination is provided.

        The maximum number of items that can be included in a paginated response is `100`.

        When paginated, the response includes the `itemsPerPage` attribute.

        If the number of items available is greater than or equal to `count`, it also includes the `nextCursor` attribute, which can be used to fetch the subsequent page of items.

        '
      example: 30
      in: query
      name: count
      required: false
      schema:
        maximum: 100
        type: number
  responses:
    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.
    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.
    ValidationError:
      content:
        application/json:
          example:
            code: 400
            message: 'ValidationError: name is mandatory'
          schema:
            $ref: '#/components/schemas/Error'
      description: The request was not valid.
    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.
    InternalError:
      content:
        application/json:
          example:
            code: 500
            message: Server error
          schema:
            $ref: '#/components/schemas/Error'
      description: An internal error occurred.
    NotFound:
      content:
        application/json:
          example:
            code: 404
            message: Resource not found
          schema:
            $ref: '#/components/schemas/Error'
      description: The specified resource was not found.
    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.
    ServiceUnavailable:
      content:
        application/json:
          example:
            code: 503
            message: Service unavailable
          schema:
            $ref: '#/components/schemas/Error'
      description: The server is unavailable. Please try again later
  schemas:
    Tag:
      properties:
        code:
          description: External reference used by the ERP. If not required, it can be the same as the dimension code.
          example: 11
          type: string
        customInformation:
          additionalProperties:
            type: string
          description: Dictionary of custom information attributes associated with the tag.
          example: '{"requiresEscalation": true, "ledgerCode": "ABC123" }'
          nullable: true
          type: object
        dimensionCode:
          description: Dimension code associated with the tag.
          example: miscellaneous
          type: string
        expenseApproverIds:
          description: List of expense approvers identified by their Yokoy unique ID. This is used in expense-based workflows.
          items:
            description: Yokoy ID of the user.
            example: 9L7rovNzNhTCsJSTkbfq
            pattern: '[\w-]+'
            type: string
          nullable: true
          type: array
        id:
          description: Yokoy unique ID of the tag.
          example: CP0YGe9VwzWixLOZdTK8
          pattern: '[\w-]+'
          readOnly: true
          type: string
        invoiceApproverIds:
          description: List of invoice approvers identified by their Yokoy unique ID. This is used in invoice-based workflows.
          items:
            description: Yokoy ID of the user.
            example: 9L7rovNzNhTCsJSTkbfq
            pattern: '[\w-]+'
            type: string
          nullable: true
          type: array
        name:
          description: Descriptive name of the tag.
          example: Relocation services
          type: string
        statusActive:
          description: Status of the tag.
          example: true
          type: boolean
      required:
      - name
      - code
      - dimensionCode
      - statusActive
      type: object
    Error:
      properties:
        code:
          type: integer
        message:
          type: string
      required:
      - code
      - message
      type: object
  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
Yokoy Tag API

Documentation

Specifications

Other Resources

OpenAPI Specification
