openapi: 3.2.0
info:
  title: Karbonhq Tenant Settings API
  version: v3
  contact:
    name: API Support
    url: https://developers.karbonhq.com/issues/
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://karbonhq.com/terms-of-use/
  description: 'Operations tagged Tenant Settings across 2 of this provider''s published API definitions: KarbonAPI.json, karbonhq-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.karbonhq.com
  description: The production API server
security:
- ApiKeyAuth: []
  BearerAuth: []
tags:
- name: Tenant Settings
  description: Retrieve lists of valid Contact Types, Work Types and Work Statuses
paths:
  /v3/TenantSettings:
    get:
      tags:
      - Tenant Settings
      summary: Gets lists of customer specific Contact and Work settings
      description: Get specific settings for a tenant, including the valid work statuses, work types, service types and client types
      operationId: getTenantSettings
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTenantSettings'
              example:
                '@odata.context': https://api.karbonhq.com/v3/$metadata#TenantSettings/$entity
                TenantKey: 2BzmMRkhbwBT
                ClientAccessActivated: true
                WorkStatuses:
                - Name: Planned
                  Type: Primary
                  Children: []
                - Name: InProgress
                  Type: Primary
                  Children:
                  - Name: Review
                    Type: Secondary
                    WorkStatusKey: 2mwflHRTqsdv
                  - Name: Assemble
                    Type: Secondary
                    WorkStatusKey: 4mdN65g99lzF
                  - Name: Lodge
                    Type: Secondary
                    WorkStatusKey: 22tBP6QkrMbY
                  - Name: Follow-up
                    Type: Secondary
                    WorkStatusKey: 3sDb8y6mgzrz
                - Name: Waiting
                  Type: Primary
                  Children:
                  - Name: Waiting for client
                    Type: Secondary
                    WorkStatusKey: GrZfvNMt49q
                  - Name: Wait for confirmation
                    Type: Secondary
                    WorkStatusKey: 3G9vZTc3cXwz
                - Name: Completed
                  Type: Primary
                  Children:
                  - Name: Billed
                    Type: Secondary
                    WorkStatusKey: lqlGVMcvm7T
                  - Name: Cancelled
                    Type: Secondary
                    WorkStatusKey: nJ8jJDwF6l
                - Name: ReadyToStart
                  Type: Primary
                  Children: []
                WorkTypes:
                - Name: Accounting
                  WorkTypeKey: nTlQkTQnNz7
                  AvailableStatuses:
                    Primary:
                    - In Progress
                    - Ready To Start
                    - Waiting
                    - Completed
                    Secondary:
                    - 2mwflHRTqsdv
                    - 3sDb8y6mgzrz
                    - GrZfvNMt49q
                    - nJ8jJDwF6l
                - Name: Bookkeeping
                  WorkTypeKey: 3RJgJSgq5xz
                  AvailableStatuses:
                    Primary:
                    - In Progress
                    - Ready To Start
                    - Waiting
                    - Completed
                    Secondary:
                    - GrZfvNMt49q
                    - nJ8jJDwF6l
                ContactTypes:
                - Name: Prospect
                  ContactTypeKey: 2FZQTGSgmyyQ
                - Name: Client
                  ContactTypeKey: 2kYcl5QHnSxh
                - Name: Inactive
                  ContactTypeKey: 3dxPhBZvhCGm
                - Name: Other
                  ContactTypeKey: 478pf88jbnQr
                ServiceTypes:
                - Name: Tax Compliance
                  ServiceTypeKey: 5kQr8VtLm2xP
                  WorkTypeKeys:
                  - nTlQkTQnNz7
                  - 3RJgJSgq5xz
                - Name: Advisory
                  ServiceTypeKey: 7hMn3WdKp9zR
                  WorkTypeKeys:
                  - 3RJgJSgq5xz
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFound'
              examples:
                Unauthorized Access:
                  $ref: '#/components/examples/UnauthorizedAccess'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorMessage'
    servers:
    - url: https://api.karbonhq.com
      description: The production API server
components:
  schemas:
    GetTenantSettings:
      description: A collection of customer specific Contact and Work settings
      type: object
      properties:
        ContactTypes:
          type: array
          items:
            $ref: '#/components/schemas/SettingContactType'
        TenantKey:
          type: string
          description: The unique key specific to the customer's Karbon account
          example: 2BzmMRkhbwBT
        ClientAccessActivated:
          type: boolean
          description: Indicates whether the tenant has activated Karbon for Clients (K4C)
          example: true
        WorkStatuses:
          type: array
          items:
            $ref: '#/components/schemas/SettingWorkStatus'
        WorkTypes:
          type: array
          items:
            $ref: '#/components/schemas/SettingWorkType'
        ServiceTypes:
          type: array
          items:
            $ref: '#/components/schemas/SettingServiceType'
    ResourceNotFound:
      description: A generic response shown when the API cannot find a requested entity
      type: object
      properties:
        statusCode:
          type:
          - string
          - 'null'
          description: The generic HTTP Error code
          example: '404'
        message:
          type: string
          description: The error message
          example: Resource not found
    SettingContactType:
      description: 'The name and unique key for a Contact Type '
      type: object
      properties:
        Name:
          type: string
          description: The name assigned to the Customer Type
          example: Customer
        ContactTypeKey:
          type: string
          description: The unique key assigned to the Customer Type
          example: z9p3q3d1e3
    RateLimitErrorMessage:
      description: The error message returned when the API rate limit is hit
      type: object
      properties:
        statusCode:
          type:
          - string
          - 'null'
          description: The generic HTTP Error code
          example: '429'
        message:
          type: string
          description: The error message
          example: Rate limit is exceeded. Try again in 10 seconds.
    SettingServiceType:
      description: The schema for a single Service Type entry
      type: object
      properties:
        Name:
          type: string
          description: The name assigned to the Service Type
          example: Tax Compliance
        ServiceTypeKey:
          type: string
          description: The unique key assigned to the Service Type
          example: 5kQr8VtLm2xP
        WorkTypeKeys:
          type: array
          items:
            type: string
            description: The unique key of a Work Type belonging to this Service Type, matching a WorkTypeKey in the WorkTypes array
            example: nTlQkTQnNz7
    SettingWorkStatus:
      description: A Work Status, its child statuses with Name, Type and unique Key
      type: object
      properties:
        Name:
          type: string
          description: The name assigned the Work Status
          example: InProgress
        Type:
          type: string
          enum:
          - Primary
          - Secondary
          description: The type of status, expected to be Primary at this level
          example: Primary
        Children:
          type: array
          items:
            type: object
            properties:
              Name:
                type: string
                example: In Review
                description: The name of the Secondary Work Status
              Type:
                type: string
                enum:
                - Primary
                - Secondary
                example: Secondary
                description: The type of Work Status, expected to always be Secondary at this level
              WorkStatusKey:
                type: string
                example: 2mwflHRTqsdv
                description: ' The unique key of the Work Status'
    SettingWorkType:
      description: The schema for a single Work Type entry
      type: object
      properties:
        Name:
          type: string
          description: The name assigned to the Work Type
          example: Tax
        WorkTypeKey:
          type: string
          description: The unique key assigned to the Work Type
          example: a1b2c3d4e5
        AvailableStatuses:
          type: object
          properties:
            primary:
              type: array
              items:
                type: string
                description: The name of the Primary Status
                example: Active
            secondary:
              type: array
              items:
                type: string
                description: The unique key of the secondary Work Status that can be used with this Work Type
                example: r2t4p6m72
  examples:
    UnauthorizedAccess:
      description: A generic response shown when the API cannot confirm the authentication creditials provided
      value:
        error:
          statusCode: '401'
          message: JWT not present.
  securitySchemes:
    BearerAuth:
      description: The Application ID for your API application, supplied by secure message when your Application is first registered
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      description: The AccessKey for your API application, found inside the Settings > Connected Apps section in Karbon
      type: apiKey
      in: header
      name: AccessKey
externalDocs:
  description: Karbon Developers - API release notes
  url: https://developers.karbonhq.com/release-notes/
x-refined-from:
- KarbonAPI.json
- karbonhq-openapi.yml