Karbon Estimate Summaries API

openapi: 3.2.0
info:
  title: Karbonhq Estimate Summaries 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 Estimate Summaries 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: Estimate Summaries
  description: Estimate and track time to understand jobs that are on-budget, allocate resources, and uncover performance insights to transform your firm. Read more
paths:
  /v3/EstimateSummaries/{WorkItemKey}:
    get:
      tags:
      - Estimate Summaries
      summary: Gets estimate summaries using WorkItemKey
      parameters:
      - required: true
        in: path
        name: WorkItemKey
        schema:
          type: string
        example: 4jgPTtcXxwC2
        description: The Karbon-generated Work Item key
      description: Use the `GET` method on this endpoint to receive the estimate summaries of a Work Item specified using the `WorkItemKey`.
      operationId: getEstimateSummariesByWorkItemKey
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  '@odata.context':
                    type: string
                    description: The information about Karbon controllers generating this response.
                    example: https://api.karbonhq.com/v3/$metadata#EstimateSummaries
                  value:
                    type: array
                    items:
                      type: object
                      properties:
                        EstimateSummaryKey:
                          type: string
                          description: A randomly generated GUID
                          example: 160F79F6-E650-40C3-8BD9-F70C287B7476-0
                        UserKey:
                          type: string
                          description: A Karbon-generated unique identifier for the Karbon user
                          example: RXq4mB32PXg
                        RoleKey:
                          type: string
                          description: A Karbon-generated unique identifier for the user's role
                          example: qTLmJpG85Ng
                        RoleName:
                          type: string
                          description: The Role of the user
                          example: Accountant
                        TaskTypeKey:
                          type: string
                          description: A Karbon-generated unique identifier for the task
                          example: 3h5Tbh9GgLs7
                        TaskTypeName:
                          type: string
                          description: The name of the task
                          example: Admin
                        EstimateMinutes:
                          type: integer
                          description: The total estimated time (in minutes) for the task to be completed
                          example: 15
                        HourlyRate:
                          type: number
                          format: decimal
                          description: The hourly rate of the user
                          example: 150
                        ActualMinutes:
                          type: integer
                          description: The actual time (in minutes) spent on the task
                          example: 14
                        EstimateAmount:
                          type: number
                          format: decimal
                          description: The estimated cost of the task, calculated from the estimated time at the user's hourly rate
                          example: 37.5
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Unsupported Option:
                  $ref: '#/components/examples/Unsupported_option'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFound'
              examples:
                Unauthorized Access:
                  $ref: '#/components/examples/UnauthorizedAccess'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Resource Not Found:
                  $ref: '#/components/examples/HTTP_Resource_Not_Found'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorMessage'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Undefined Error:
                  $ref: '#/components/examples/elongated_5001'
    servers:
    - url: https://api.karbonhq.com
      description: The production API server
  /v3/WorkItems/{WorkItemKey}/EstimateSummaries/{EstimateSummaryKey}:
    get:
      tags:
      - Estimate Summaries
      summary: Gets a single Estimate Summary using WorkItemKey and EstimateSummaryKey
      parameters:
      - required: true
        in: path
        name: WorkItemKey
        schema:
          type: string
        example: 4jgPTtcXxwC2
        description: The Karbon-generated Work Item key
      - required: true
        in: path
        name: EstimateSummaryKey
        schema:
          type: string
        example: 160F79F6-E650-40C3-8BD9-F70C287B7476-0
        description: The Karbon-generated Estimate Summary key, as returned by GET /v3/EstimateSummaries/{WorkItemKey}
      description: 'Use the `GET` method on this endpoint to receive a single estimate summary on a Work Item, specified using the `WorkItemKey` and `EstimateSummaryKey`.


        An EstimateSummaryKey starting with `0-` represents time recorded against a task with no estimate assigned, rather than an actual estimate. It can be retrieved but not updated.'
      operationId: getEstimateSummaryByKey
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  EstimateSummaryKey:
                    type: string
                    description: A randomly generated GUID. Changing HourlyRate on a PATCH can reissue this key — use the OData-EntityId response header to get the current one.
                    example: 160F79F6-E650-40C3-8BD9-F70C287B7476-0
                  UserKey:
                    type: string
                    description: A Karbon-generated unique identifier for the Karbon user
                    example: RXq4mB32PXg
                  RoleKey:
                    type: string
                    description: A Karbon-generated unique identifier for the user's role
                    example: qTLmJpG85Ng
                  RoleName:
                    type: string
                    description: The Role of the user
                    example: Accountant
                  TaskTypeKey:
                    type: string
                    description: A Karbon-generated unique identifier for the task
                    example: 3h5Tbh9GgLs7
                  TaskTypeName:
                    type: string
                    description: The name of the task
                    example: Admin
                  EstimateMinutes:
                    type: integer
                    description: The total estimated time (in minutes) for the task to be completed
                    example: 15
                  HourlyRate:
                    type: number
                    format: decimal
                    description: The hourly rate of the user
                    example: 150
                  ActualMinutes:
                    type: integer
                    description: The actual time (in minutes) spent on the task
                    example: 14
                  EstimateAmount:
                    type: number
                    format: decimal
                    description: The estimated cost of the task, calculated from the estimated time at the user's hourly rate
                    example: 37.5
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Unsupported Option:
                  $ref: '#/components/examples/Unsupported_option'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFound'
              examples:
                Unauthorized Access:
                  $ref: '#/components/examples/UnauthorizedAccess'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Resource Not Found:
                  $ref: '#/components/examples/HTTP_Resource_Not_Found'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorMessage'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Undefined Error:
                  $ref: '#/components/examples/elongated_5001'
    patch:
      tags:
      - Estimate Summaries
      summary: Updates a single Estimate Summary
      parameters:
      - required: true
        in: path
        name: WorkItemKey
        schema:
          type: string
        example: 4jgPTtcXxwC2
        description: The Karbon-generated Work Item key
      - required: true
        in: path
        name: EstimateSummaryKey
        schema:
          type: string
        example: 160F79F6-E650-40C3-8BD9-F70C287B7476-0
        description: The Karbon-generated Estimate Summary key, as returned by GET /v3/EstimateSummaries/{WorkItemKey}
      description: 'Use the `PATCH` method on this endpoint to update the estimated minutes or amount, and/or the hourly rate, for an estimate summary. Only `EstimateMinutes`, `EstimateAmount` and `HourlyRate` are accepted, and each is optional.


        An EstimateSummaryKey starting with `0-` represents time recorded against a task with no estimate assigned, rather than an actual estimate, and cannot be updated through this endpoint — assign an estimate to the task in Karbon first.


        Each Karbon account''s Time and Budget settings choose whether estimates are controlled by time or by amount, and this setting cannot be changed through the API. Only the field matching that setting can be set, and `EstimateMinutes` and `EstimateAmount` cannot be supplied together.


        A successful update returns `204 No Content`. Changing `HourlyRate` can reissue the `EstimateSummaryKey`, so the response always includes an `OData-EntityId` header with the estimate summary''s location after the update — use that URL for subsequent requests rather than the key you sent.'
      operationId: updateEstimateSummary
      requestBody:
        description: The fields to update. Only EstimateMinutes, EstimateAmount and HourlyRate are accepted, and EstimateMinutes and EstimateAmount cannot be supplied together. Refer to the table below for more information on each field in the request body.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                EstimateMinutes:
                  type: integer
                  description: The total estimated time (in minutes) for the task. Between 0 and 599,999,940. Cannot be supplied together with EstimateAmount.
                  example: 90
                EstimateAmount:
                  type: number
                  format: decimal
                  description: The estimated cost of the task. Between 0 and 99,999,999. Cannot be supplied together with EstimateMinutes.
                  example: 250.0
                HourlyRate:
                  type: number
                  format: decimal
                  description: The hourly rate to estimate the task at. Between 0 and 99,999,999.
                  example: 150
            example:
              EstimateAmount: 250.0
      responses:
        '204':
          description: Estimate summary successfully updated
          headers:
            OData-EntityId:
              description: The estimate summary's location after the update, as a URL you can GET. Changing the hourly rate can reissue the EstimateSummaryKey, so use this location for subsequent requests.
              schema:
                type: string
        '400':
          description: Bad Request. Returned for an invalid request body, an unsupported PATCH property, or when the EstimateSummaryKey does not belong to the WorkItem.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Unsupported Option:
                  $ref: '#/components/examples/Unsupported_option'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFound'
              examples:
                Unauthorized Access:
                  $ref: '#/components/examples/UnauthorizedAccess'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Resource Not Found:
                  $ref: '#/components/examples/HTTP_Resource_Not_Found'
        '422':
          description: Unprocessable Entity. Returned when the Work Item is completed, the rate change is blocked by the firm's WIP lock date, rate plans are not enabled for the firm, or the estimate cannot hold the field supplied (for example, setting HourlyRate on a non-billable estimate, or EstimateMinutes on an estimate budgeted by amount).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorMessage'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessages'
              examples:
                Undefined Error:
                  $ref: '#/components/examples/elongated_5001'
    servers:
    - url: https://api.karbonhq.com
      description: The production API server
components:
  examples:
    Unsupported_option:
      description: The error returned when the query option in a request is not allowed for by the API
      value:
        error:
          code: '4002'
          message: Query option '<Option Name>' is not allowed. To allow it, set the 'AllowedQueryOptions' property on EnableQueryAttribute or QueryValidationSettings.
    elongated_5001:
      description: A response shown when the API encounters an exception
      value:
        error:
          code: '5001'
          message: Unexpected Internal Error. Please contact Karbon HQ Technical support with API Request Id of 63792674374107265425.
    HTTP_Resource_Not_Found:
      description: The error returned when the request path and request method does not match any configured API path and method
      value:
        error:
          code: '4002'
          message: No HTTP resource was found that matches the request URI 'http://api.karbonhq.com/v3/<endpoint>
    UnauthorizedAccess:
      description: A generic response shown when the API cannot confirm the authentication creditials provided
      value:
        error:
          statusCode: '401'
          message: JWT not present.
  schemas:
    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
    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.
    ErrorMessages:
      description: The details of an error associated with an API request
      required:
      - error
      type: object
      properties:
        error:
          required:
          - code
          - message
          type: object
          properties:
            code:
              type: string
              example: '4004'
              description: A Karbon-generated code to identify the error
            message:
              type: string
              example: The record could not be found
              description: The error message
  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