Mavenlink External Payments API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Kantata OX API Documentation External Payments 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: External Payments
  description: 'An external payment is a manual record of a payment made outside of Kantata OX. An external payment can

    be applied to an invoice, or just recorded directly to a project.'
paths:
  /external_payments:
    get:
      summary: Fetching a list of External Payments
      description: 'The external payments currently visible to the user that is logged-in.


        This endpoint returns structured External Payment 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 `external_payments` top-level JSON key.

        Please see our Response Format section for more information.'
      operationId: Get External Payments
      tags:
      - External Payments
      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: include
        description: 'Any of the below associations can be included in your request by providing the `include` param, e.g. `include=association1,association2`.

          - `invoice` (Invoice) - The invoice (if any) for which the external payment was created.

          - `user` (User) - The user who created the external payment.

          - `workspace` (Workspace) - The project in which the external payment was created.'
        schema:
          type: string
      - in: query
        name: invoice_id
        description: Limit returned external payments to those paying the invoice with the specified ID.
        schema:
          type: integer
          format: int32
      - 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`, `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: 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_id
        description: Limit returned external payments to those created by the user with the specified ID.
        schema:
          type: integer
          format: int32
      - in: query
        name: workspace_id
        description: Limit returned external payments to those logged within the specified workspace_id.
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: A list of External Payments 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
                  external_payments:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/ExternalPayment'
                  users:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/User'
                  workspaces:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Workspace'
                  invoices:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Invoice'
        '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 External Payment
      description: 'Creates an external payment for the specified project or invoice. If an invoice ID is provided, a

        payment is only created for that invoice when it''s a single project invoice and in a non-draft pending state.


        This endpoint returns structured External Payment 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 `external_payments` top-level JSON key.

        Please see our Response Format section for more information.'
      operationId: Create External Payment
      tags:
      - External Payments
      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`.

          - `invoice` (Invoice) - The invoice (if any) for which the external payment was created.

          - `user` (User) - The user who created the external payment.

          - `workspace` (Workspace) - The project in which the external payment was created.'
        schema:
          type: string
      responses:
        '200':
          description: External Payment 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
                  external_payments:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/ExternalPayment'
                  users:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/User'
                  workspaces:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Workspace'
                  invoices:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Invoice'
        '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:
                external_payment:
                  type: object
                  properties:
                    workspace_id:
                      type: integer
                      format: int32
                      description: The ID of the project in which the payment will be created.
                    invoice_id:
                      type: integer
                      format: int32
                      description: 'The ID of the invoice (if any) that is being paid by the external payment.  This automatically sets the amount

                        attribute of the payment to the amount of the specified invoice, and will override any `amount_in_cents` parameter sent.'
                    amount_in_cents:
                      type: integer
                      format: int32
                      description: 'Indicates that the payment is not for an invoice, and will be ignored if an `invoice_id` is provided.

                        Must be in base cent units of the currency of the project in which the payment is created.'
                    message:
                      type: string
                      description: An optional string describing the payment (255 characters maximum).
                  required:
                  - workspace_id
        required: true
  /external_payments/{id}:
    get:
      summary: Fetching a single External Payment
      description: 'This endpoint returns structured External Payment 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 `external_payments` top-level JSON key.

        Please see our Response Format section for more information.'
      operationId: Get External Payment
      tags:
      - External Payments
      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`.

          - `invoice` (Invoice) - The invoice (if any) for which the external payment was created.

          - `user` (User) - The user who created the external payment.

          - `workspace` (Workspace) - The project in which the external payment was created.'
        schema:
          type: string
      responses:
        '200':
          description: The External Payment 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
                  external_payments:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/ExternalPayment'
                  users:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/User'
                  workspaces:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Workspace'
                  invoices:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Invoice'
        '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'
    delete:
      summary: Deleting an existing External Payment
      description: 'The response will contain no content and an HTTP 204 status code if the request was

        successful, or a standard Kantata OX error message explaining why the object could not be deleted.'
      operationId: Delete External Payment
      tags:
      - External Payments
      parameters:
      - in: path
        name: id
        required: true
        description: The ID of the Model.
        schema:
          type: integer
      responses:
        '204':
          description: External Payment has been deleted.
        '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'
components:
  schemas:
    ExternalPayment:
      title: External Payment
      description: An External Payment is a record within a workspace of a payment that happened outside of Kantata OX.
      type: object
      properties:
        amount_in_cents:
          type: integer
          format: int32
          description: The amount the payment was for, in cents.
        created_at:
          type: string
          format: date-time
          description: The date and time the payment was created.
        invoice_id:
          type: integer
          format: int32
          description: The id of the invoice, if any, for which the payment was created.
        message:
          type: string
          description: The message that accompanied the payment.
        updated_at:
          type: string
          format: date-time
          description: The date and time the payment was last updated.
        user_id:
          type: integer
          format: int32
          description: The id of the user who created the payment.
        workspace_id:
          type: integer
          format: int32
          description: The id of the project in which the payment was created.
    Workspace:
      title: Workspace
      description: Workspaces (also called projects) represent the space in which Kantata OX users plan, communicate, and collaborate.
      type: object
      properties:
        access_level:
          type: string
          description: Whether the project is open, and who can join it. Possible values are `invitation`, `open`, and `admin`.
        account_color_id:
          type: string
          description: '`account_color_id` will only be included in the response if `account_color` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        account_id:
          type: integer
          format: int32
          description: The ID of the account which the project is in.
        account_insights_mapping_ids:
          type: array
          items:
            type: string
          description: '`account_insights_mapping_ids` will only be included in the response if `account_insights_mappings` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        actual_fees_includes_additional_line_items:
          type: boolean
          description: 'Whether invoice additional items are included in actual fees calculations for the project.

            Visible when the authenticated user is a project administrator and is on the account that the project is on.'
        actual_fees_includes_expenses:
          type: boolean
          description: 'Whether expenses are included in actual fees calculations for the project.

            Visible when the authenticated user is a project administrator and is on the account that the project is on.'
        approver_id:
          type: string
          description: '`approver_id` will only be included in the response if `approver` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        approver_ids:
          type: array
          items:
            type: string
          description: '`approver_ids` will only be included in the response if `approvers` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        archived:
          type: boolean
          description: Whether the project is archived.
        billable_minutes:
          type: integer
          format: int32
          description: 'The total amount of billable time entries, in minutes. Only visible if the authenticated user has financial access in the project and is on the provider team.

            Visible when the authenticated user can see total time approved in the project.


            Only returned when requested through the optional_fields param.'
        billing_milestone_ids:
          type: array
          items:
            type: string
          description: '`billing_milestone_ids` will only be included in the response if `billing_milestones` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        budget_remaining:
          type: string
          description: 'The amount of the project budget remaining.

            Visible when the authenticated user is on the provider team and can either see reports on the account or has financial access in the project.'
        budget_used:
          type: string
          description: 'The amount of the project budget that has been used.

            Visible when the authenticated user is on the provider team and can either see reports on the account or has financial access in the project.'
        budget_used_in_cents:
          type: integer
          format: int32
          description: 'The amount of the project budget that has been used, in the subunits of the currency (e.g. cents for USD).

            Visible when the authenticated user is on the provider team and can either see reports on the account or has financial access in the project.'
        budgeted:
          type: boolean
          description: Whether the project is budgeted.
        can_create_line_items:
          type: boolean
          description: Whether the authenticated user can create line items in the project (i.e. time entries, expenses, fixed fee items, or additional items).
        can_invite:
          type: boolean
          description: Whether the authenticated user can invite others to the project.
        change_orders_enabled:
          type: boolean
          description: Whether change orders are enabled in the project.
        client_lead_name:
          type: string
          description: 'The name of the team lead for the client side of the project.

            Only returned when requested through the optional_fields param.'
        client_role_name:
          type: string
          description: The client team name.
        consultant_role_name:
          type: string
          description: The provider team name.
        created_at:
          type: string
          format: date-time
          description: The date the project was created.
        creator_id:
          type: string
          description: '`creator_id` will only be included in the response if `creator` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        currency:
          type: string
          description: The currency of the project. Only visible if the authenticated user has financial access in the project.
        currency_base_unit:
          type: integer
          format: int32
          description: The base unit of the currency of the project. For example, the base unit for USD is 100.
        currency_symbol:
          type: string
          description: The [ISO symbol](https://knowledge.kantata.com/hc/en-us/articles/360041576473) for the currency of the project. For example, `USD`.
        current_status_report_id:
          type: string
          description: '`current_status_report_id` will only be included in the response if `current_status_report` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        current_user_participation_id:
          type: string
          description: '`current_user_participation_id` will only be included in the response if `current_user_participation` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        custom_field_value_ids:
          type: array
          items:
            type: string
          description: '`custom_field_value_ids` will only be included in the response if `custom_field_values` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        default_rate:
          type: string
          description: The default billing rate for the project.
        description:
          type: string
          description: The description of the project.
        due_date:
          type: string
          format: date
          description: The due date of the project.
        effective_due_date:
          type: string
          format: date
          description: The due date of the project (deprecated).
        estimated_minutes:
          type: integer
          format: int32
          description: 'The total task estimated minutes of the project.

            Visible when the authenticated user can see reports on the account or has financial access in the project.


            Only returned when requested through the optional_fields param.'
        exclude_archived_stories_percent_complete:
          type: boolean
          description: Whether archived tasks are excluded from the calculation of the project completion percentage.
        expenses_in_burn_rate:
          type: boolean
          description: 'Whether both expenses and invoice additional items are included in the actual fees calculation for the project. This field is the `AND` of `actual_fees_includes_expenses` and `actual_fees_includes_additional_line_items`.

            Visible when the authenticated user is a project administrator and is on the account that the project is on.'
        external_link:
          type: object
          description: 'A link that displays within the project workspace. Requires the Project Button facilitated feature.

            Visible when the workspace has the project button feature enabled.'
          properties:
            url:
              type: string
              description: 'The URL of the link.

                Visible when the workspace has the project button feature enabled.'
            text:
              type: string
              description: 'The button text.

                Visible when the workspace has the project button feature enabled.'
        external_reference_ids:
          type: array
          items:
            type: string
          description: '`external_reference_ids` will only be included in the response if `external_references` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        financial_viewer_ids:
          type: array
          items:
            type: string
          description: '`financial_viewer_ids` will only be included in the response if `financial_viewers` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        has_active_expense_report_submissions:
          type: boolean
          description: Whether the project has active expense report submissions.
        has_active_timesheet_submissions:
          type: boolean
          description: Whether the project has active timesheet submissions.
        has_budget_access:
          type: boolean
          description: Whether the authenticated user has budget access in the project.
        incoming_email_address:
          type: string
          description: 'The email address for the project—unique to the authenticated user—which can be used to post to the project''s Activity Feed via email.

            Visible when the authenticated user is a project administrator and is on the account that the project is on.


            Only returned when requested through the optional_fields param.'
        lock_date:
          type: string
          format: date
          description: 'The line item lock date for the account the project is on, if any.

            Only returned when requested through the optional_fields param.'
        minutes_logged:
          type: integer
          format: int32
          description: 'The total minutes logged on the project, including time adjustments. Only visible if the authenticated user has financial access in the project and is on the provider team.

            Visible when the authenticated user can see total time approved in the project.


            Only returned when requested through the optional_fields param.'
        next_uncompleted_milestone_id:
          type: string
          description: '`next_uncompleted_milestone_id` will only be included in the response if `next_uncompleted_milestone` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        non_billable_minutes:
          type: integer
          format: int32
          description: 'The total of all non-billable time entries in minutes, only included if the current user has financial access and is a maven in the project.

            Visible when the authenticated user can see total time approved in the project.


            Only returned when requested through the optional_fields param.'
        over_budget:
          type: boolean
          description: 'Whether the project is over budget. Only visible if the authenticated user has financial access in the project.

            Visible when the authenticated user is a project administrator and is on the account that the project is on.'
        participant_ids:
          type: array
          items:
            type: string
          description: '`participant_ids` will only be included in the response if `participants` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        participation_ids:
          type: array
          items:
            type: string
          description: '`participation_ids` will only be included in the response if `participations` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        percent_of_budget_used:
          type: integer
          format: int32
          description: 'The percent of the project budget used.

  

# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mavenlink/refs/heads/main/openapi/mavenlink-external-payments-api-openapi.yml