Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
version: 1.0.0
title: Kantata OX API Documentation Invoices API
description: Kantata OX's API provides access to the majority of Kantata OX's data model.
termsOfService: https://www.kantata.com/terms-of-use
contact:
name: Kantata OX Support
url: https://knowledge.kantata.com/hc/en-us
license:
name: COPYRIGHT © 2026 Kantata, Inc.
url: https://www.kantata.com/terms-of-use
x-logo:
url: https://theme.zdassets.com/theme_assets/56104/04e93064d309f75d054b8cee885d1ea51e9be8f7.png
backgroundColor: '#FFFFFF'
altText: Kantata OX API Documentation
href: https://developer.kantata.com
servers:
- url: https://api.mavenlink.com/api/v1
tags:
- name: Invoices
description: 'Users can create Invoices in a Kantata OX project. An Invoice must have at least one line item (a time entry,
expense, fixed fee item, or additional item). By default, the recipient of an invoice is the primary client
in the project. Manual formatting options are available to define the format and information that should be displayed on an
invoice.
Invoices can only be created and viewed by participants with financial permission in a project.'
paths:
/invoices:
get:
summary: Fetching a list of Invoices
description: 'This endpoint returns structured Invoice objects.
As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the `results` array
and will be indexed by ID in the `invoices` top-level JSON key.
Please see our Response Format section for more information.'
operationId: Get Invoices
tags:
- Invoices
parameters:
- in: query
name: created_after
description: Filter for records created after a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.
schema:
type: string
format: date-time
- in: query
name: created_before
description: Filter for records created before a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.
schema:
type: string
format: date-time
- in: query
name: external_reference_external_message
description: Filter the objects based on the external message of their associated external references. This is an exact match.
schema:
type: string
- in: query
name: external_reference_external_status
description: Filter by the status of the external object in the external system.
schema:
type: string
- in: query
name: external_reference_service_model
description: Filter by the type of the external object this external reference belongs to.
schema:
type: string
- in: query
name: external_reference_service_model_ref
description: Filter by the id of the external object this external reference belongs to.
schema:
type: integer
format: int32
- in: query
name: external_reference_service_model_refs
description: Filter for objects that correlate to the specified external object IDs. Provide a comma-separated list of up to 200 external IDs.
schema:
type: string
- in: query
name: external_reference_service_name
description: Filter by the name of the provider for integration.
schema:
type: string
- in: query
name: external_reference_status
description: Filter by the status of the integration, this can be successful or fail.
schema:
type: string
- in: query
name: has_external_references
description: Filter by whether or not the object has external references.
schema:
type: boolean
- in: query
name: include
description: 'Any of the below associations can be included in your request by providing the `include` param, e.g. `include=association1,association2`.
- `additional_items` (AdditionalItem) - When included, the `additional_item_ids` array will reference all additional items included in the invoice.
- `billing_milestones` (BillingMilestone) - When included, the `billing_milestone_ids` array will reference all billing milestones included in the invoice.
- `expenses` (Expense) - When included, the `expense_ids` array will reference all expenses included in the invoice.
- `external_references` (ExternalReference) - Includes references to external integrations for this object.
- `fixed_fee_items` (FixedFeeItem) - When included, the `fixed_fee_items` array will reference all fixed fee items included in the invoice.
- `recipient` (User) - The User who received the invoice. Namely, the client lead at the time that the invoice
was created (or null, if no lead client existed at the time).
- `time_entries` (TimeEntry) - When included, the `time_entry_ids` array will reference all time entries included in the invoice.
- `user` (User) - The user who created the invoice.
- `workspaces` (Workspace) - When included, the `workspace_ids` array will reference all projects covered by the invoice.'
schema:
type: string
- in: query
name: only
description: 'Allows you to request one or more resources directly by ID. Multiple IDs can be supplied
in a comma separated list, like `GET /api/v1/workspaces.json?only=5,6,7`.'
schema:
type: string
- in: query
name: order
description: 'Supply `order` with the name of a valid sort field for the endpoint and a direction.
Valid values: `created_at:asc`, `created_at:desc`, `id:asc`, `id:desc`, `invoice_date:asc`, `invoice_date:desc`, `updated_at:asc`, and `updated_at:desc`.'
schema:
type: string
default: created_at:desc
- in: query
name: page
schema:
type: integer
format: int32
default: 1
- in: query
name: paid
description: When `true` is passed, only paid invoices are returned.
schema:
type: boolean
default: false
- in: query
name: pending
description: When `true` is passed, only non-accepted, non-draft invoices are returned.
schema:
type: boolean
default: false
- in: query
name: per_page
schema:
type: integer
format: int32
default: 20
maximum: 200
- in: query
name: updated_after
description: Filter for records updated after a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.
schema:
type: string
format: date-time
- in: query
name: updated_before
description: Filter for records updated before a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.
schema:
type: string
format: date-time
- in: query
name: user_invoice_number
description: "Provide one or more user invoice numbers, separated by commas. When provided, only invoices\n with the specified user invoice numbers will be returned."
schema:
type: string
- in: query
name: within_dates
description: "Provide a date range in 2000-01-01:2000-12-31 format. When provided, only invoices created\n within the specified range will be returned."
schema:
type: string
- in: query
name: without_drafts
description: When `true` is passed, draft invoices will not be returned.
schema:
type: boolean
default: false
- in: query
name: without_external_reference_service_name
description: Exclude by the existence of an external reference with the specified service name.
schema:
type: string
- in: query
name: workspace_id
description: "Provide one or more workspace IDs, separated by commas. If present, only invoices\n in the provided projects will be returned."
schema:
type: string
responses:
'200':
description: A list of Invoices have been retrieved.
content:
application/json:
schema:
type: object
properties:
count:
type: integer
format: int32
meta:
type: object
properties:
count:
type: integer
format: int32
page_count:
type: integer
format: int32
page_number:
type: integer
format: int32
page_size:
type: integer
format: int32
results:
type: array
items:
type: object
properties:
key:
type: string
id:
type: string
invoices:
type: object
additionalProperties:
$ref: '#/components/schemas/Invoice'
external_references:
type: object
additionalProperties:
$ref: '#/components/schemas/ExternalReference'
users:
type: object
additionalProperties:
$ref: '#/components/schemas/User'
workspaces:
type: object
additionalProperties:
$ref: '#/components/schemas/Workspace'
additional_items:
type: object
additionalProperties:
$ref: '#/components/schemas/AdditionalItem'
time_entries:
type: object
additionalProperties:
$ref: '#/components/schemas/TimeEntry'
expenses:
type: object
additionalProperties:
$ref: '#/components/schemas/Expense'
fixed_fee_items:
type: object
additionalProperties:
$ref: '#/components/schemas/FixedFeeItem'
billing_milestones:
type: object
additionalProperties:
$ref: '#/components/schemas/BillingMilestone'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'401':
description: Unauthorized request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'403':
description: Forbidden request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'404':
description: Page Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'503':
description: Service is unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
post:
summary: Creating a new Invoice
description: 'This endpoint returns structured Invoice objects.
As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the `results` array
and will be indexed by ID in the `invoices` top-level JSON key.
Please see our Response Format section for more information.'
operationId: Create Invoice
tags:
- Invoices
parameters:
- in: query
name: include
description: 'Any of the below associations can be included in your request by providing the `include` param, e.g. `include=association1,association2`.
- `additional_items` (AdditionalItem) - When included, the `additional_item_ids` array will reference all additional items included in the invoice.
- `billing_milestones` (BillingMilestone) - When included, the `billing_milestone_ids` array will reference all billing milestones included in the invoice.
- `expenses` (Expense) - When included, the `expense_ids` array will reference all expenses included in the invoice.
- `external_references` (ExternalReference) - Includes references to external integrations for this object.
- `fixed_fee_items` (FixedFeeItem) - When included, the `fixed_fee_items` array will reference all fixed fee items included in the invoice.
- `recipient` (User) - The User who received the invoice. Namely, the client lead at the time that the invoice
was created (or null, if no lead client existed at the time).
- `time_entries` (TimeEntry) - When included, the `time_entry_ids` array will reference all time entries included in the invoice.
- `user` (User) - The user who created the invoice.
- `workspaces` (Workspace) - When included, the `workspace_ids` array will reference all projects covered by the invoice.'
schema:
type: string
responses:
'200':
description: Invoice has been created.
content:
application/json:
schema:
type: object
properties:
count:
type: integer
format: int32
meta:
type: object
properties:
count:
type: integer
format: int32
page_count:
type: integer
format: int32
page_number:
type: integer
format: int32
page_size:
type: integer
format: int32
results:
type: array
items:
type: object
properties:
key:
type: string
id:
type: string
invoices:
type: object
additionalProperties:
$ref: '#/components/schemas/Invoice'
external_references:
type: object
additionalProperties:
$ref: '#/components/schemas/ExternalReference'
users:
type: object
additionalProperties:
$ref: '#/components/schemas/User'
workspaces:
type: object
additionalProperties:
$ref: '#/components/schemas/Workspace'
additional_items:
type: object
additionalProperties:
$ref: '#/components/schemas/AdditionalItem'
time_entries:
type: object
additionalProperties:
$ref: '#/components/schemas/TimeEntry'
expenses:
type: object
additionalProperties:
$ref: '#/components/schemas/Expense'
fixed_fee_items:
type: object
additionalProperties:
$ref: '#/components/schemas/FixedFeeItem'
billing_milestones:
type: object
additionalProperties:
$ref: '#/components/schemas/BillingMilestone'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'401':
description: Unauthorized request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'403':
description: Forbidden request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'404':
description: Page Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'503':
description: Service is unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
requestBody:
content:
application/json:
schema:
type: object
properties:
invoice:
type: object
properties:
time_entry_ids:
type: array
items:
type: integer
format: int32
description: '[Time Entry](/tag/Time-Entries) IDs. (At least one of the following is required: time_entry_ids, expense_ids, additional_items, fixed_fee_items, or billing_milestone_ids.).'
expense_ids:
type: array
items:
type: integer
format: int32
description: '[Expense](/tag/Expenses) IDs. (At least one of the following is required: time_entry_ids, expense_ids, additional_items, fixed_fee_items, or billing_milestone_ids.).'
fixed_fee_items:
type: array
description: 'Fixed fee item objects to create (At least one of the following is required: time_entry_ids, expense_ids, additional_items, fixed_fee_items, or billing_milestone_ids.).'
items:
type: object
properties:
notes:
type: string
description: Notes to display on the fixed fee item.
amount:
type: integer
format: int32
description: The value of the fixed fee item, in the currency's main unit. Dollars, for example.
taxable:
type: boolean
description: Whether the fixed fee item is taxable.
story_id:
type: integer
format: int32
description: The ID of the [Story](/tag/Stories) associated with the fixed fee item.
workspace_id:
type: integer
format: int32
description: The ID of the [Workspace](/tag/Workspaces) associated with the fixed fee item.
additional_items:
type: array
description: 'Additional item objects to create (At least one of the following is required: time_entry_ids, expense_ids, additional_items, fixed_fee_items, or billing_milestone_ids.).'
items:
type: object
properties:
notes:
type: string
description: Notes to be displayed on the additional item.
amount:
type: integer
format: int32
description: The value of the additional item, in the currency's main unit. Dollars, for example.
taxable:
type: boolean
description: Whether the additional item is taxable.
workspace_id:
type: integer
format: int32
description: The ID of the [Workspace](/tag/Workspaces) associated with the additional item.
workspace_id:
type: integer
format: int32
description: The ID of the [Workspace](/tag/Workspaces) in which to create the invoice. (Either `workspace_id` or `workspace_ids` is required.).
workspace_ids:
type: array
items:
type: integer
format: int32
description: The IDs of the [Workspaces](/tag/Workspaces) in which to create the (multi-project) invoice. (Either `workspace_id` or `workspace_ids` is required.).
payment_schedule:
type: integer
format: int32
description: The number of days within which the total amount of the invoice is expected to be paid. For example, use `30` for a Net 30 payment schedule. See https://en.wikipedia.org/wiki/Net_D.
invoice_date:
type: string
format: date
description: The invoice date. The date must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.
user_invoice_number:
type: integer
format: int32
description: The invoice number (defined by the user).
draft:
type: boolean
description: Whether the invoice is a draft.
message:
type: string
description: Notes to be displayed on the invoice.
user_invoice_title:
type: string
description: The invoice title (defined by the user).
purchase_order:
type: string
description: The invoice purchase order (defined by the user).
project_code:
type: string
description: The invoice project code (defined by the user).
suppress_emails:
type: boolean
description: Setting suppress_emails to true will prevent creation emails from being sent.
billing_milestone_ids:
type: array
items:
type: integer
format: int32
description: 'The IDs of [billing milestones](/tag/Billing-Milestones) to add to the invoice. (At least one of the following is required: time_entry_ids, expense_ids, additional_items, fixed_fee_items, or billing_milestone_ids.).'
external_reference:
type: object
description: 'Typically populated programmatically by a third party system via an integration, this is an optional
object that holds data from an external system. It connects objects in an external system with objects in
Kantata OX (for example, to connect a Jira issue to a Kantata OX Project).'
properties:
service_name:
type: string
description: The provider name of the integration. If you are adding multiple external references to the same object, the `service_name` must be unique.
service_model:
type: string
description: The object type of the external object this external reference belongs to.
service_model_ref:
type: string
description: The object ID of the external object this external reference belongs to.
status:
type: string
description: The status of the integration. Options are `successful`, `pending`, or `failed`.
external_message:
type: string
description: The message on the external object.
external_link:
type: string
description: The link to the external object.
external_status:
type: string
description: The status of the external object in the external system.
locked:
type: boolean
description: Whether the subject is locked.
required:
- service_name
- service_model
- service_model_ref
required:
- payment_schedule
required: true
/invoices/next_invoice_number:
get:
summary: Retrieve the next available invoice number
operationId: Get Next Invoice Number
tags:
- Invoices
responses:
'200':
description: A list of Invoices have been retrieved.
content:
application/json:
schema:
type: object
properties:
next_invoice_number:
type: string
description: The next invoice number.
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'401':
description: Unauthorized request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'403':
description: Forbidden request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'404':
description: Page Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'503':
description: Service is unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
/invoices/{id}:
get:
summary: Fetching a single Invoice
description: 'This endpoint returns structured Invoice objects.
As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the `results` array
and will be indexed by ID in the `invoices` top-level JSON key.
Please see our Response Format section for more information.'
operationId: Get Invoice
tags:
- Invoices
parameters:
- in: path
name: id
required: true
description: The ID of the Model.
schema:
type: integer
- in: query
name: include
description: 'Any of the below associations can be included in your request by providing the `include` param, e.g. `include=association1,association2`.
- `additional_items` (AdditionalItem) - When included, the `additional_item_ids` array will reference all additional items included in the invoice.
- `billing_milestones` (BillingMilestone) - When included, the `billing_milestone_ids` array will reference all billing milestones included in the invoice.
- `expenses` (Expense) - When included, the `expense_ids` array will reference all expenses included in the invoice.
- `external_references` (ExternalReference) - Includes references to external integrations for this object.
- `fixed_fee_items` (FixedFeeItem) - When included, the `fixed_fee_items` array will reference all fixed fee items included in the invoice.
- `recipient` (User) - The User who received the invoice. Namely, the client lead at the time that the invoice
was created (or null, if no lead client existed at the time).
- `time_entries` (TimeEntry) - When included, the `time_entry_ids` array will reference all time entries included in the invoice.
- `user` (User) - The user who created the invoice.
- `workspaces` (Workspace) - When included, the `workspace_ids` array will reference all projects covered by the invoice.'
schema:
type: string
responses:
'200':
description: The Invoice has been retrieved.
content:
application/json:
schema:
type: object
properties:
count:
type: integer
format: int32
meta:
type: object
properties:
count:
type: integer
format: int32
page_count:
type: integer
format: int32
page_number:
type: integer
format: int32
page_size:
type: integer
format: int32
results:
type: array
items:
type: object
properties:
key:
type: string
id:
type: string
invoices:
type: object
additionalProperties:
$ref: '#/components/schemas/Invoice'
external_references:
type: object
additionalProperties:
$ref: '#/components/schemas/ExternalReference'
users:
type: object
additionalProperties:
$ref: '#/components/schemas/User'
workspaces:
type: object
additionalProperties:
$ref: '#/components/schemas/Workspace'
additional_items:
type: object
additionalProperties:
$ref: '#/components/schemas/AdditionalItem'
time_entries:
type: object
additionalProperties:
$ref: '#/components/schemas/TimeEntry'
expenses:
type: object
additionalProperties:
$ref: '#/components/schemas/Expense'
fixed_fee_items:
type: object
additionalProperties:
$ref: '#/components/schemas/FixedFeeItem'
billing_milestones:
type: object
additionalProperties:
$ref: '#/components/schemas/BillingMilestone'
'400':
description: Bad Request
# --- truncated at 32 KB (106 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mavenlink/refs/heads/main/openapi/mavenlink-invoices-api-openapi.yml