Kantata Kantata OX Knowledge Base
Release Notes
Status Page

Workspaces

Workspaces (also called projects) represent the space in which Kantata OX users plan, communicate, and collaborate.

Fetching a list of Workspaces

Gets a list of projects.

This endpoint has its own rate limit. See the Knowledge Base for more information.

Archived Projects

By default, archived projects are not returned in the response. Use the include_archived=true filter to retrieve archived projects.

Search Filter

The search parameter filters for projects that match one or more keywords. By default, the following fields are searched:

  • workspace_id
  • title
  • description
  • full_name of the primary_maven (i.e. the Provider team lead)
  • full_name of the primary_counterpart (i.e. the Client team lead)
  • name of workspace_groups, including the primary_workspace_group
  • display_value of custom_field_values (Excluding currency and date custom fields)

You can search on specific fields using the format search=field_name:'keyword'. For example, search=description:'acme'. This is supported for the following fields:

  • title
  • description
  • group - Searches only the name field of workspace_groups. The keyword must match the entire name of the group (i.e. not a partial match).
  • custom_field_value - Searches the display_value of custom_field_values. (Excluding currency and date custom fields.)
  • status - Searches only the message field of the project status. The keyword must match the entire name of the project status (i.e. not a partial match).

To combine multiple field-specific search terms, separate them by a space. For example, search=title:'acme' description:'website'.

You can combine a field-specific search term with general search terms. For example, search=description:'acme' design.

This endpoint returns structured Workspace 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 workspaces top-level JSON key. Please see our Response Format section for more information.

Request
query Parameters
account_color_ids
string

Filter by color ID. Provide a comma-separated list of color IDs.

archived
string

Filter for only archived projects, or include or exclude archived projects from the results. Options are only, exclude, and include.

budgeted
boolean

Return only budgeted projects (true) or only non-budgeted projects (false).

by_custom_choice_value
string

Filter by a custom field choice value, represented as a string with the custom field ID, followed by a colon, and then comma-separated custom field choice value IDs. The custom field choice value can also be the word blank. Multiple custom fields can be delimited by semicolons or by parentheses and colons.

The following formats are supported:

  • custom_field_ID:choice_value_ID
  • custom_field_ID:choice_value_1_ID,choice_value_2_ID
  • custom_field_ID:blank
  • (custom_field_1_ID:choice_value_1_ID,choice_value_2_ID):(custom_field_2_ID:choice_value_3_ID).
by_custom_currency_value
string

Filter by a custom field currency value, represented as a string with the custom field ID, followed by a colon, and then the currency value. Optionally, the currency ISO code can be supplied as well, separated from the currency value by another colon. Multiple custom fields can be delimited by semicolons or by parentheses and colons. The following formats are supported:

  • (1:200.2:USD):(2:100).
by_custom_date_value
string

Filter by a custom field date value, represented as a string with the custom field ID, followed by a colon, the starting date, another colon, and then the ending date. You can provide both a starting date and ending date, or provide just one. Multiple custom fields can be delimited by semicolons or by parentheses and colons. The following formats are supported:

  • (1:2014-12-05:2014-12-25):(2:2014-12-05).
by_custom_number_value
string

Filter by a custom field number value, represented as a string with the custom field ID, followed by a colon, and then the number value. Multiple custom fields can be delimited by semicolons or by parentheses and colons. The following formats are supported:

  • (1:200):(2:101).
by_custom_text_value
string

Filter by a custom field text value, represented as a string with the custom field ID, followed by a colon, and then the text value. Multiple custom fields can be delimited by semicolons or by parentheses and colons. The following formats are supported:

  • (1:something):(2:else).
can_create_line_items
boolean

Return only projects where the authenticated user can create expenses or time entries (true) or only projects where the user can't (false).

created_after
string <date-time>

Filter for records created after a specified datetime. The datetime must be in ISO 8601 format.

created_at
string

(Deprecated) Use the created_before and created_after filters instead.

Filter for projects created between a specified date range. Format as from_date;to_date. Dates must be in ISO 8601 format. For example, 2014-12-05;2014-12-25.

created_before
string <date-time>

Filter for records created before a specified datetime. The datetime must be in ISO 8601 format.

creator
string

Filter for projects created by a specific user(s). Provide a comma-separated list of user IDs. For example, 10,20.

current_user_is_maven_participant
boolean

Filter for projects where the authenticated user is on the provider team. When included in your request, this filter is always processed as true; the actual value you provide is ignored.

custom_date_range
string

Filter for projects with date custom field value(s) within a specified range. Format as custom_field_id:from_date:to_date;custom_field_id:from_date:to_date. Multiple custom fields can be delimited by semicolons. Dates must be in ISO 8601 format. For example, 1:2014-12-05:2014-12-25;2:2015-12-05:2015-12-25.

custom_integer_ranges
string

Filter for projects with number custom field value(s) within a specified range. Format as custom_field_id:min:max;custom_field_id:min:max. Multiple custom fields can be delimited by semicolons. For example, 42:20:10;43:50:100.

due_date_after
string <date>

Filter for projects that are due after the specified date. Can be used with due_date_before to filter by a date range. The date must be in ISO 8601 format.

due_date_before
string <date>

Filter for projects that are due before the specified date. Can be used with due_date_after to filter by a date range. The date must be in ISO 8601 format.

except
string

Filter out specific projects from the results. Provide a comma-separated list of workspace IDs.

external_reference_external_message
string

Filter the objects based on the external message of their associated external references. This is an exact match.

external_reference_external_status
string

Filter by the status of the external object in the external system.

external_reference_service_model
string

Filter by the type of the external object this external reference belongs to.

external_reference_service_model_ref
integer <int32>

Filter by the id of the external object this external reference belongs to.

external_reference_service_model_refs
string

Filter for objects that correlate to the specified external object IDs. Provide a comma-separated list of up to 200 external IDs.

external_reference_service_name
string

Filter by the name of the provider for integration.

external_reference_status
string

Filter by the status of the integration, this can be successful or fail.

financials_viewable_by_user
boolean

Return only projects that the authenticated user can view, has financial access in, and is on the provider team. If false, no filtering is applied.

for_approver
integer <int32>

Filter for projects where the user with the specified user ID can approve time.

has_approvers
boolean

Return only projects that have an approver (true) or only projects that don't (false).

has_external_references
boolean

Filter by whether or not the object has external references.

has_maven_participant
integer <int32>

Filter for projects where the user with the specified user ID is on the provider team.

has_participant
integer <int32>

Filter for projects where the user with the specified user ID is a participant.

has_participation
boolean

Filter for projects where the authenticated user is a participant.

has_value_for_custom_field_ids
string

Filter by the presence of a custom field value for the specified comma-separated custom field ID(s).

include
string

Any of the below associations can be included in your request by providing the include param, e.g. include=association1,association2.

  • account_color (AccountColor) - Retrieves the color of the workspace. The response will include account_color_id, which references the data in the account_colors top-level key.
  • account_insights_mappings (AccountInsightsMapping) - Retrieves the Insights dynamic dashboards in the workspace. The response will include account_insights_mapping_ids, which references the data in the account_insights_mappings top-level key.
  • approver (User) - Retrieves the first approver (as determined by user ID) on the workspace who is viewable to the current user. The response will include approver_id, which references the data in the users top-level key.
  • approvers (User) - Retrieves all time approvers on the workspace who are viewable to the current user. The response will include approver_ids, which references the data in the users top-level key.
  • creator (User) - Retrieves the user who created the project. The response will include creator_id, which references the data in the users top-level key. If the creator has left the project, you can use primary_counterpart to get the provider-side team lead.
  • current_status_report (StatusReport) - Retrieves the most recent project status report from today. The response will include current_status_report_id, which references the data in the status_reports top-level key.
  • current_user_participation (Participation) - Retrieves the workspace participation of the current user. The response will include current_user_participation_ids, which references the data in the participations top-level key.
  • custom_field_values (CustomFieldValue) - Retrieves custom field values for the workspace. The response will include custom_field_value_ids, which references the data in the custom_field_values top-level key.
  • external_references (ExternalReference) - Includes references to external integrations for this object.
  • financial_viewers (User) - Retrieves the users on the project who have financial access. The response will include financial_viewer_ids, which references the data in the users top-level key.
  • next_uncompleted_milestone (Story) - Retrieves the next project milestone that is not complete. The response will include next_uncompleted_milestone_id, which references the data in the stories top-level key.
  • participants (User) - Retrieves users that are participating in the project. The response will include participant_ids, which references the data in the users top-level key.
  • participations (Participation) - Retrieves the participations of each participant in the project. The response will include participation_ids, which references the data in the participations top-level key.
  • possible_approvers (User) - Retrieves the users that can be made time approvers on the workspace. The response will include possible_approver_ids, which references the data in the users top-level key.
  • primary_counterpart (User) - Retrieves the lead of the Clients team. The response will include primary_counterpart_id, which references the data in the users top-level key.
  • primary_maven (User) - Retrieves the lead of the Providers team. The response will include primary_maven_id, which references the data in the users top-level key.
  • primary_workspace_group (WorkspaceGroup) - Retrieves the primary group associated with the project. The response will include primary_workspace_group_id, which references the data in the workspace_groups top-level key.
  • status_reports (StatusReport) - Retrieves the status reports for the workspace. The response will include status_report_ids, which references the data in the status_reports top-level key.
  • timesheet_submissions (TimesheetSubmission) - Retrieves the list of all submitted timesheets which the user can approve on the project. The response will include timesheet_submission_ids, which references the data in the timesheet_submissions top-level key.
  • workspace_groups (WorkspaceGroup) - Retrieves groups associated with the project that is visible to the current user. The response will include workspace_group_ids, which references the data in the workspace_groups top-level key.
  • workspace_resources (WorkspaceResource) - Retrieves the named resources for the workspace. The response will include workspace_resource_ids, which references the data in the workspace_resources top-level key.
  • workspace_resources_with_unnamed (WorkspaceResource) - Retrieves the named and unnamed resources for the workspace. The response will include workspace_resources_with_unnamed_ids, which references the data in the workspace_resources top-level key.
include_archived
boolean
Default: false

Include (true) or exclude (false) archived projects from the results.

matching
string

Filter for projects with a title that match the specified string. This filter is not case sensitive. This filter functions as a "starts with" filter for each word in project titles.

Additionally, the following common words (known as stop words) are ignored: a, an, and, are, as, at, be, but, by, for, if, in, into, is, it, no, not, of, on, or, such, that, the, their, then, there, these, they, this, to, was, with.

milestone_weight_percentage_complete
string

Filter for projects which have a milestone percent completion within the specified range. Provide two comma-separated numbers. For example, 15,30.

on_account_by_orgs
boolean

Filter for projects that are on the authenticated user’s account and within the organization hierarchy the authenticated user is a part of. Requires the Report Viewer account permission or above.

on_my_account
boolean

Filter for projects that are on the same account as the authenticated user.

only
string

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.

only_joinable
boolean

Filter for projects which the authenticated user can join and are within the organization hierarchy the user is a part of.

only_participating_or_joinable
boolean

Filter for projects which the authenticated user is participating in or can join.

only_project_manager_in
boolean

Filter for projects that are on the same account as the authenticated user, where the user is on the provider team, and where they have financial access or higher.

optional_fields
Array of strings

Allows you to request one or more optional fields as an array.

Items Enum: "client_lead_name" "provider_lead_name" "stage" "estimated_minutes" "total_invoiced" "total_minutes_approved" "billable_minutes" "non_billable_minutes" "minutes_logged" "incoming_email_address" "lock_date"
order
string
Default: "updated_at:desc"

Supply order with the name of a valid sort field for the endpoint and a direction.

Valid values: amount_paid:asc, amount_paid:desc, color_name:asc, color_name:desc, created_at:asc, created_at:desc, custom_field:<custom_field_id>:asc, custom_field:<custom_field_id>:desc, due_date:asc, due_date:desc, last_viewed:asc, last_viewed:desc, percentage_complete:asc, percentage_complete:desc, price:asc, price:desc, provider_lead_name:asc, provider_lead_name:desc, search, start_date:asc, start_date:desc, status:asc, status:desc, title:asc, title:desc, updated_at:asc, and updated_at:desc.

Note: The custom_field:<custom_field_id>:asc and custom_field:<custom_field_id>:desc options do not support multi-choice custom fields.

page
integer <int32>
Default: 1
participant_or_org_member_in
boolean

Filter for projects that are on the same account as the authenticated user, that the user is participating in, and that are within the organization hierarchy the user is a part of.

pending_timesheet_submissions
string

Filter for projects that have pending timesheet submissions within a specified date range. Format as from_date;to_date. Dates must be in ISO 8601 format. For example, 2014-12-05;2014-12-25.

per_page
integer <int32> <= 200
Default: 20
provider_lead
string

Filter for projects with the specified provider team leads. Provide a comma-separated list of user IDs. For example, 10,20.

require_time_approvals
boolean

Return only projects that require time approvals (true) or only projects that don't (false).

requiring_expense_approval
boolean

Return only projects that require expense approvals (true) or only projects that don't (false).

search
string
selected_choices
string

Filter for projects that have a specific choice selected for a choice custom field. Format as custom_field_id:choice_ids;custom_field_id:choice_ids. Pass none to indicate no selection. Multiple custom fields can be delimited by semicolons. For example: 1:3,2;4:2,none.

stage
string

Return only projects in the estimate stage or project stage. Options are estimate and project.

start_date_after
string <date>

Filter for projects that start after the specified date. Can be used with start_date_before to filter by a date range. The date must be in ISO 8601 format.

start_date_before
string <date>

Filter for projects that start before the specified date. Can be used with start_date_after to filter by a date range. The date must be in ISO 8601 format.

updated_after
string <date-time>

Filter for records updated after a specified datetime. The datetime must be in ISO 8601 format.

updated_before
string <date-time>

Filter for records updated before a specified datetime. The datetime must be in ISO 8601 format.

user_not_participating
integer <int32>

Filter for projects where the user with the specified ID is not participating.

viewable_for_time_administration
boolean

Return only projects where the authenticated user can approve time. Can be used in combination with the include_archived filter.

without_external_reference_service_name
string

Exclude by the existence of an external reference with the specified service name.

workspace_groups
string

Filter for projects that are associated with the specified project groups. Provide a comma-separated list of group IDs. For example, 10,20.

Responses
200

A list of Workspaces have been retrieved.

Response Schema: application/json
count
integer <int32>
object
Array of objects
object
object
object
object
object
object
object
object
object
object
object
object
400

Bad Request

401

Unauthorized request

403

Forbidden request

404

Page Not Found

422

Unprocessable Entity

503

Service is unavailable

get/workspaces
Request samples
Response samples
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "workspaces": {
    },
  • "external_references": {
    },
  • "stories": {
    },
  • "users": {
    },
  • "participations": {
    },
  • "timesheet_submissions": {
    },
  • "workspace_groups": {
    },
  • "custom_field_values": {
    },
  • "workspace_resources": {
    },
  • "status_reports": {
    },
  • "account_colors": {
    },
  • "account_insights_mappings": {
    }
}

Creating a new Workspace

Creates a new workspace (project).

This endpoint has its own rate limit. See the Knowledge Base for more information.

This endpoint returns structured Workspace 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 workspaces top-level JSON key. Please see our Response Format section for more information.

Request
query Parameters
include
string

Any of the below associations can be included in your request by providing the include param, e.g. include=association1,association2.

  • account_color (AccountColor) - Retrieves the color of the workspace. The response will include account_color_id, which references the data in the account_colors top-level key.
  • account_insights_mappings (AccountInsightsMapping) - Retrieves the Insights dynamic dashboards in the workspace. The response will include account_insights_mapping_ids, which references the data in the account_insights_mappings top-level key.
  • approver (User) - Retrieves the first approver (as determined by user ID) on the workspace who is viewable to the current user. The response will include approver_id, which references the data in the users top-level key.
  • approvers (User) - Retrieves all time approvers on the workspace who are viewable to the current user. The response will include approver_ids, which references the data in the users top-level key.
  • creator (User) - Retrieves the user who created the project. The response will include creator_id, which references the data in the users top-level key. If the creator has left the project, you can use primary_counterpart to get the provider-side team lead.
  • current_status_report (StatusReport) - Retrieves the most recent project status report from today. The response will include current_status_report_id, which references the data in the status_reports top-level key.
  • current_user_participation (Participation) - Retrieves the workspace participation of the current user. The response will include current_user_participation_ids, which references the data in the participations top-level key.
  • custom_field_values (CustomFieldValue) - Retrieves custom field values for the workspace. The response will include custom_field_value_ids, which references the data in the custom_field_values top-level key.
  • external_references (ExternalReference) - Includes references to external integrations for this object.
  • financial_viewers (User) - Retrieves the users on the project who have financial access. The response will include financial_viewer_ids, which references the data in the users top-level key.
  • next_uncompleted_milestone (Story) - Retrieves the next project milestone that is not complete. The response will include next_uncompleted_milestone_id, which references the data in the stories top-level key.
  • participants (User) - Retrieves users that are participating in the project. The response will include participant_ids, which references the data in the users top-level key.
  • participations (Participation) - Retrieves the participations of each participant in the project. The response will include participation_ids, which references the data in the participations top-level key.
  • possible_approvers (User) - Retrieves the users that can be made time approvers on the workspace. The response will include possible_approver_ids, which references the data in the users top-level key.
  • primary_counterpart (User) - Retrieves the lead of the Clients team. The response will include primary_counterpart_id, which references the data in the users top-level key.
  • primary_maven (User) - Retrieves the lead of the Providers team. The response will include primary_maven_id, which references the data in the users top-level key.
  • primary_workspace_group (WorkspaceGroup) - Retrieves the primary group associated with the project. The response will include primary_workspace_group_id, which references the data in the workspace_groups top-level key.
  • status_reports (StatusReport) - Retrieves the status reports for the workspace. The response will include status_report_ids, which references the data in the status_reports top-level key.
  • timesheet_submissions (TimesheetSubmission) - Retrieves the list of all submitted timesheets which the user can approve on the project. The response will include timesheet_submission_ids, which references the data in the timesheet_submissions top-level key.
  • workspace_groups (WorkspaceGroup) - Retrieves groups associated with the project that is visible to the current user. The response will include workspace_group_ids, which references the data in the workspace_groups top-level key.
  • workspace_resources (WorkspaceResource) - Retrieves the named resources for the workspace. The response will include workspace_resource_ids, which references the data in the workspace_resources top-level key.
  • workspace_resources_with_unnamed (WorkspaceResource) - Retrieves the named and unnamed resources for the workspace. The response will include workspace_resources_with_unnamed_ids, which references the data in the workspace_resources top-level key.
optional_fields
Array of strings

Allows you to request one or more optional fields as an array.

Items Enum: "client_lead_name" "provider_lead_name" "stage" "estimated_minutes" "total_invoiced" "total_minutes_approved" "billable_minutes" "non_billable_minutes" "minutes_logged" "incoming_email_address" "lock_date"
Request Body schema: application/json
required
object
consultant_role_name
string

The label for the consultant team (i.e. the team providing the service).

client_role_name
string

The label for the client team (i.e. the team paying for the service).

budgeted
boolean

Whether the project is budgeted. Defaults to true for paid accounts. Defaults to false for free accounts.

start_date
string <date>

When the project starts. The date must be in ISO 8601 format.

due_date
string <date>

When the project is due. The date must be in ISO 8601 format.

description
string

The description of the project.

currency
string

The currency of the project. Only applicable if budgeted is true. See the Knowledge Base for the list of currency codes. Defaults to the account currency or USD. If a rate_card_id is provided, this field is ignored.

access_level
string

Whether the project is open, and who can join the project.

Enum: "invitation" "open" "admins"
rate_card_id
integer <int32>

The ID of the rate card for the project. The currency of the rate card must match the currency of the project.

exclude_archived_stories_percent_complete
boolean

Whether archived tasks are excluded from the calculation of the project completion percentage.

tasks_default_non_billable
boolean

Whether tasks in the project default to non-billable.

stories_are_fixed_fee_by_default
boolean

Whether tasks in the project default to fixed fee (true) or time and materials (false).

expenses_in_burn_rate
boolean

Sets whether both expenses and invoice additional items should be included in the actual fees calculation for the project. Note that setting this field sets the values of both actual_fees_includes_expenses and actual_fees_includes_additional_line_items. To set the values individually, set actual_fees_includes_expenses and actual_fees_includes_additional_line_items instead.

actual_fees_includes_expenses
boolean

Sets whether expenses should be included in the actual fees calculation for the project.

actual_fees_includes_additional_line_items
boolean

Sets whether invoice additional items should be included in the actual fees calculation for the project.

posts_require_privacy_decision
boolean

Whether project posts are visible to everyone in the project (false) or are private (true) by default.

status_key
integer <int32>

The status of the project. See the Knowledge Base for a list of project status IDs.

object

Invoice customization preferences that will be automatically generated in each invoice for the project.

approver_id
integer <int32>

The user ID of the designated time approver for the project.

workspace_group_ids
Array of integers <int32>

The IDs of the groups the project belongs to.

project_template_start_date
string <date>

When project_tracker_template_id is provided, this sets the start date that tasks will be based on when the template is applied. The date must be in ISO 8601 format.

project_template_checklist_as_todos
boolean

Whether checklist items are converted to To Dos when applying a template.

Array of objects

When project_tracker_template_id is provided, this maps template resources to named or unnamed resources when the template is applied. If named resources are specified via the user_id field, the users should also be included in the participations field.

project_template_weekends_as_workdays
boolean

When project_tracker_template_id is provided, this sets whether weekends count as work days when applying the template. If true, weekend days will be included in task durations.

project_template_create_unnamed_resources
boolean

When project_tracker_template_id is provided, this maps all template resources and task assignments to unnamed resources, and ignores project_template_assignment_mappings for task assignments.

project_template_distribute_hours
boolean

When project_tracker_template_id is provided, this sets whether task estimated hours in the template are automatically added as scheduled hours for all tasks when applying the template. The hours will be distributed evenly between the task start date and end date.

project_tracker_template_id
integer <int32>

The ID of the template to use to populate tasks and other information in the project.

primary_workspace_group_id
integer <int32>

The ID of the group that is the primary group for the project.

target_margin
integer <int32>

The desired profit, expressed as a percentage.

object

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).

account_color_id
integer <int32>

The ID of the account color to apply to the project.

object

A link to display within the project workspace. Requires the Project Button facilitated feature.

account_insights_mapping_ids
Array of integers <int32>

The IDs of Insights dynamic dashboards to add to the project.

Array of objects

Custom field values for the project.

stage
string

The stage of the project. Options are estimate and project.

Enum: "estimate" "project"
time_trackable
boolean

Sets whether tasks in the project can have time tracked to them. This field is only usable if allowed by Time & Expense account settings.

title
required
string
creator_role
string

Which team to add the project creator to. Options are maven / consultant (i.e. the provider team) and buyer / client (i.e. the client team). Defaults to maven.

Enum: "client" "consultant"
price
integer <int32>

The starting budget of the project. This is required for budgeted projects.

change_orders_enabled
boolean

Whether schedule and budget changes require approval.

Defaults to true if the project is budgeted.

change_orders
boolean

Whether schedule and budget changes require approval.

Defaults to true if the project is budgeted.

Array of objects

The organizations to assign to the project.

Array of objects

Users to add to the project on the provider team.

primary_maven_id
integer <int32>

The ID of the user to set as the team lead on the provider team.

require_expense_approvals
boolean

Whether expenses logged to the project must be approved.

require_time_approvals
boolean

Whether time tracked to the project must be approved.

estimate_scenario_id
integer <int32>

The ID of the estimate scenario to create this project from. Must also provide a start_date.

attachment_ids
Array of integers <int32>

The IDs of file attachments to associate with the project after it is created.

Responses
200

Workspace has been created.

Response Schema: application/json
count
integer <int32>
object
Array of objects
object
object
object
object
object
object
object
object
object
object
object
object
400

Bad Request

401

Unauthorized request

403

Forbidden request

404

Page Not Found

422

Unprocessable Entity

503

Service is unavailable

post/workspaces
Request samples
application/json
{
  • "workspace": {
    }
}
Response samples
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "workspaces": {
    },
  • "external_references": {
    },
  • "stories": {
    },
  • "users": {
    },
  • "participations": {
    },
  • "timesheet_submissions": {
    },
  • "workspace_groups": {
    },
  • "custom_field_values": {
    },
  • "workspace_resources": {
    },
  • "status_reports": {
    },
  • "account_colors": {
    },
  • "account_insights_mappings": {
    }
}

Fetching a single Workspace

Gets a project by ID.

By default, you will receive a 404 status if you try to retrieve an archived project. Use the include_archived:true filter to retrieve an archived project.

Users with Project Lead (or lower) account permissions can retrieve projects they are not participating in if they have the All projects or All projects accessible to their organization (if Organizations are enabled) permission in the View Resource Center section of the Resource Management Access Group set.

This endpoint returns structured Workspace 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 workspaces top-level JSON key. Please see our Response Format section for more information.

Request
path Parameters
id
required
integer

The ID of the Model.

query Parameters
include
string

Any of the below associations can be included in your request by providing the include param, e.g. include=association1,association2.

  • account_color (AccountColor) - Retrieves the color of the workspace. The response will include account_color_id, which references the data in the account_colors top-level key.
  • account_insights_mappings (AccountInsightsMapping) - Retrieves the Insights dynamic dashboards in the workspace. The response will include account_insights_mapping_ids, which references the data in the account_insights_mappings top-level key.
  • approver (User) - Retrieves the first approver (as determined by user ID) on the workspace who is viewable to the current user. The response will include approver_id, which references the data in the users top-level key.
  • approvers (User) - Retrieves all time approvers on the workspace who are viewable to the current user. The response will include approver_ids, which references the data in the users top-level key.
  • creator (User) - Retrieves the user who created the project. The response will include creator_id, which references the data in the users top-level key. If the creator has left the project, you can use primary_counterpart to get the provider-side team lead.
  • current_status_report (StatusReport) - Retrieves the most recent project status report from today. The response will include current_status_report_id, which references the data in the status_reports top-level key.
  • current_user_participation (Participation) - Retrieves the workspace participation of the current user. The response will include current_user_participation_ids, which references the data in the participations top-level key.
  • custom_field_values (CustomFieldValue) - Retrieves custom field values for the workspace. The response will include custom_field_value_ids, which references the data in the custom_field_values top-level key.
  • external_references (ExternalReference) - Includes references to external integrations for this object.
  • financial_viewers (User) - Retrieves the users on the project who have financial access. The response will include financial_viewer_ids, which references the data in the users top-level key.
  • next_uncompleted_milestone (Story) - Retrieves the next project milestone that is not complete. The response will include next_uncompleted_milestone_id, which references the data in the stories top-level key.
  • participants (User) - Retrieves users that are participating in the project. The response will include participant_ids, which references the data in the users top-level key.
  • participations (Participation) - Retrieves the participations of each participant in the project. The response will include participation_ids, which references the data in the participations top-level key.
  • possible_approvers (User) - Retrieves the users that can be made time approvers on the workspace. The response will include possible_approver_ids, which references the data in the users top-level key.
  • primary_counterpart (User) - Retrieves the lead of the Clients team. The response will include primary_counterpart_id, which references the data in the users top-level key.
  • primary_maven (User) - Retrieves the lead of the Providers team. The response will include primary_maven_id, which references the data in the users top-level key.
  • primary_workspace_group (WorkspaceGroup) - Retrieves the primary group associated with the project. The response will include primary_workspace_group_id, which references the data in the workspace_groups top-level key.
  • status_reports (StatusReport) - Retrieves the status reports for the workspace. The response will include status_report_ids, which references the data in the status_reports top-level key.
  • timesheet_submissions (TimesheetSubmission) - Retrieves the list of all submitted timesheets which the user can approve on the project. The response will include timesheet_submission_ids, which references the data in the timesheet_submissions top-level key.
  • workspace_groups (WorkspaceGroup) - Retrieves groups associated with the project that is visible to the current user. The response will include workspace_group_ids, which references the data in the workspace_groups top-level key.
  • workspace_resources (WorkspaceResource) - Retrieves the named resources for the workspace. The response will include workspace_resource_ids, which references the data in the workspace_resources top-level key.
  • workspace_resources_with_unnamed (WorkspaceResource) - Retrieves the named and unnamed resources for the workspace. The response will include workspace_resources_with_unnamed_ids, which references the data in the workspace_resources top-level key.
optional_fields
Array of strings

Allows you to request one or more optional fields as an array.

Items Enum: "client_lead_name" "provider_lead_name" "stage" "estimated_minutes" "total_invoiced" "total_minutes_approved" "billable_minutes" "non_billable_minutes" "minutes_logged" "incoming_email_address" "lock_date"
Responses
200

The Workspace has been retrieved.

Response Schema: application/json
count
integer <int32>
object
Array of objects
object
object
object
object
object
object
object
object
object
object
object
object
400

Bad Request

401

Unauthorized request

403

Forbidden request

404

Page Not Found

422

Unprocessable Entity

503

Service is unavailable

get/workspaces/{id}
Request samples
Response samples
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "workspaces": {
    },
  • "external_references": {
    },
  • "stories": {
    },
  • "users": {
    },
  • "participations": {
    },
  • "timesheet_submissions": {
    },
  • "workspace_groups": {
    },
  • "custom_field_values": {
    },
  • "workspace_resources": {
    },
  • "status_reports": {
    },
  • "account_colors": {
    },
  • "account_insights_mappings": {
    }
}

Updating an existing Workspace

This endpoint returns structured Workspace 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 workspaces top-level JSON key. Please see our Response Format section for more information.

Request
path Parameters
id
required
integer

The ID of the Model.

query Parameters
include
string

Any of the below associations can be included in your request by providing the include param, e.g. include=association1,association2.

  • account_color (AccountColor) - Retrieves the color of the workspace. The response will include account_color_id, which references the data in the account_colors top-level key.
  • account_insights_mappings (AccountInsightsMapping) - Retrieves the Insights dynamic dashboards in the workspace. The response will include account_insights_mapping_ids, which references the data in the account_insights_mappings top-level key.
  • approver (User) - Retrieves the first approver (as determined by user ID) on the workspace who is viewable to the current user. The response will include approver_id, which references the data in the users top-level key.
  • approvers (User) - Retrieves all time approvers on the workspace who are viewable to the current user. The response will include approver_ids, which references the data in the users top-level key.
  • creator (User) - Retrieves the user who created the project. The response will include creator_id, which references the data in the users top-level key. If the creator has left the project, you can use primary_counterpart to get the provider-side team lead.
  • current_status_report (StatusReport) - Retrieves the most recent project status report from today. The response will include current_status_report_id, which references the data in the status_reports top-level key.
  • current_user_participation (Participation) - Retrieves the workspace participation of the current user. The response will include current_user_participation_ids, which references the data in the participations top-level key.
  • custom_field_values (CustomFieldValue) - Retrieves custom field values for the workspace. The response will include custom_field_value_ids, which references the data in the custom_field_values top-level key.
  • external_references (ExternalReference) - Includes references to external integrations for this object.
  • financial_viewers (User) - Retrieves the users on the project who have financial access. The response will include financial_viewer_ids, which references the data in the users top-level key.
  • next_uncompleted_milestone (Story) - Retrieves the next project milestone that is not complete. The response will include next_uncompleted_milestone_id, which references the data in the stories top-level key.
  • participants (User) - Retrieves users that are participating in the project. The response will include participant_ids, which references the data in the users top-level key.
  • participations (Participation) - Retrieves the participations of each participant in the project. The response will include participation_ids, which references the data in the participations top-level key.
  • possible_approvers (User) - Retrieves the users that can be made time approvers on the workspace. The response will include possible_approver_ids, which references the data in the users top-level key.
  • primary_counterpart (User) - Retrieves the lead of the Clients team. The response will include primary_counterpart_id, which references the data in the users top-level key.
  • primary_maven (User) - Retrieves the lead of the Providers team. The response will include primary_maven_id, which references the data in the users top-level key.
  • primary_workspace_group (WorkspaceGroup) - Retrieves the primary group associated with the project. The response will include primary_workspace_group_id, which references the data in the workspace_groups top-level key.
  • status_reports (StatusReport) - Retrieves the status reports for the workspace. The response will include status_report_ids, which references the data in the status_reports top-level key.
  • timesheet_submissions (TimesheetSubmission) - Retrieves the list of all submitted timesheets which the user can approve on the project. The response will include timesheet_submission_ids, which references the data in the timesheet_submissions top-level key.
  • workspace_groups (WorkspaceGroup) - Retrieves groups associated with the project that is visible to the current user. The response will include workspace_group_ids, which references the data in the workspace_groups top-level key.
  • workspace_resources (WorkspaceResource) - Retrieves the named resources for the workspace. The response will include workspace_resource_ids, which references the data in the workspace_resources top-level key.
  • workspace_resources_with_unnamed (WorkspaceResource) - Retrieves the named and unnamed resources for the workspace. The response will include workspace_resources_with_unnamed_ids, which references the data in the workspace_resources top-level key.
optional_fields
Array of strings

Allows you to request one or more optional fields as an array.

Items Enum: "client_lead_name" "provider_lead_name" "stage" "estimated_minutes" "total_invoiced" "total_minutes_approved" "billable_minutes" "non_billable_minutes" "minutes_logged" "incoming_email_address" "lock_date"
Request Body schema: application/json
required
object
consultant_role_name
string

The label for the consultant team (i.e. the team providing the service).

client_role_name
string

The label for the client team (i.e. the team paying for the service).

budgeted
boolean

Whether the project is budgeted. Defaults to true for paid accounts. Defaults to false for free accounts.

start_date
string <date>

When the project starts. The date must be in ISO 8601 format.

due_date
string <date>

When the project is due. The date must be in ISO 8601 format.

description
string

The description of the project.

currency
string

The currency of the project. Only applicable if budgeted is true. See the Knowledge Base for the list of currency codes. Defaults to the account currency or USD. If a rate_card_id is provided, this field is ignored.

access_level
string

Whether the project is open, and who can join the project.

Enum: "invitation" "open" "admins"
rate_card_id
integer <int32>

The ID of the rate card for the project. The currency of the rate card must match the currency of the project.

exclude_archived_stories_percent_complete
boolean

Whether archived tasks are excluded from the calculation of the project completion percentage.

tasks_default_non_billable
boolean

Whether tasks in the project default to non-billable.

stories_are_fixed_fee_by_default
boolean

Whether tasks in the project default to fixed fee (true) or time and materials (false).

expenses_in_burn_rate
boolean

Sets whether both expenses and invoice additional items should be included in the actual fees calculation for the project. Note that setting this field sets the values of both actual_fees_includes_expenses and actual_fees_includes_additional_line_items. To set the values individually, set actual_fees_includes_expenses and actual_fees_includes_additional_line_items instead.

actual_fees_includes_expenses
boolean

Sets whether expenses should be included in the actual fees calculation for the project.

actual_fees_includes_additional_line_items
boolean

Sets whether invoice additional items should be included in the actual fees calculation for the project.

posts_require_privacy_decision
boolean

Whether project posts are visible to everyone in the project (false) or are private (true) by default.

status_key
integer <int32>

The status of the project. See the Knowledge Base for a list of project status IDs.

object

Invoice customization preferences that will be automatically generated in each invoice for the project.

approver_id
integer <int32>

The user ID of the designated time approver for the project.

workspace_group_ids
Array of integers <int32>

The IDs of the groups the project belongs to.

project_template_start_date
string <date>

When project_tracker_template_id is provided, this sets the start date that tasks will be based on when the template is applied. The date must be in ISO 8601 format.

project_template_checklist_as_todos
boolean

Whether checklist items are converted to To Dos when applying a template.

Array of objects

When project_tracker_template_id is provided, this maps template resources to named or unnamed resources when the template is applied. If named resources are specified via the user_id field, the users should also be included in the participations field.

project_template_weekends_as_workdays
boolean

When project_tracker_template_id is provided, this sets whether weekends count as work days when applying the template. If true, weekend days will be included in task durations.

project_template_create_unnamed_resources
boolean

When project_tracker_template_id is provided, this maps all template resources and task assignments to unnamed resources, and ignores project_template_assignment_mappings for task assignments.

project_template_distribute_hours
boolean

When project_tracker_template_id is provided, this sets whether task estimated hours in the template are automatically added as scheduled hours for all tasks when applying the template. The hours will be distributed evenly between the task start date and end date.

project_tracker_template_id
integer <int32>

The ID of the template to use to populate tasks and other information in the project.

primary_workspace_group_id
integer <int32>

The ID of the group that is the primary group for the project.

target_margin
integer <int32>

The desired profit, expressed as a percentage.

object

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).

account_color_id
integer <int32>

The ID of the account color to apply to the project.

object

A link to display within the project workspace. Requires the Project Button facilitated feature.

account_insights_mapping_ids
Array of integers <int32>

The IDs of Insights dynamic dashboards to add to the project.

Array of objects

Custom field values for the project.

stage
string

The stage of the project. Options are estimate and project.

Enum: "estimate" "project"
time_trackable
boolean

Sets whether tasks in the project can have time tracked to them. This field is only usable if allowed by Time & Expense account settings.

title
string
archived
boolean

Set to true to archive the project or to false to unarchive the project.

price
integer <int32>

The project budget, in base units of the currency (e.g. dollars for USD ).

project_template_before_story_id
integer <int32>

When project_tracker_template_id is provided, the template tasks are inserted after the provided task ID. The provided task ID must belong to an existing and top-level task.

change_orders_enabled
boolean

Whether approval is required for schedule and budget change orders.

Responses
200

Workspace has been updated.

Response Schema: application/json
count
integer <int32>
object
Array of objects
object
object
object
object
object
object
object
object
object
object
object
object
400

Bad Request

401

Unauthorized request

403

Forbidden request

404

Page Not Found

422

Unprocessable Entity

503

Service is unavailable

put/workspaces/{id}
Request samples
application/json
{
  • "workspace": {
    }
}
Response samples
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "workspaces": {
    },
  • "external_references": {
    },
  • "stories": {
    },
  • "users": {
    },
  • "participations": {
    },
  • "timesheet_submissions": {
    },
  • "workspace_groups": {
    },
  • "custom_field_values": {
    },
  • "workspace_resources": {
    },
  • "status_reports": {
    },
  • "account_colors": {
    },
  • "account_insights_mappings": {
    }
}

Deleting an existing Workspace

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.

Request
path Parameters
id
required
integer

The ID of the Model.

Responses
204

Workspace has been deleted.

400

Bad Request

401

Unauthorized request

403

Forbidden request

404

Page Not Found

422

Unprocessable Entity

503

Service is unavailable

delete/workspaces/{id}
Request samples
Response samples
application/json
{
  • "errors": [
    ]
}

Apply a Project Template to an existing Workspace

Applies a template to an existing project.

This endpoint returns structured Workspace 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 workspaces top-level JSON key. Please see our Response Format section for more information.

Request
path Parameters
id
required
integer

The ID of the Model.

query Parameters
edit_stories
boolean

If true, the project participants and unnamed resources specified in the request body will be added to the project, but the template tasks will not actually be created in the project. Instead, template_stories_json will be returned in the response, containing information about the template tasks and assignments.

include
string

Any of the below associations can be included in your request by providing the include param, e.g. include=association1,association2.

  • account_color (AccountColor) - Retrieves the color of the workspace. The response will include account_color_id, which references the data in the account_colors top-level key.
  • account_insights_mappings (AccountInsightsMapping) - Retrieves the Insights dynamic dashboards in the workspace. The response will include account_insights_mapping_ids, which references the data in the account_insights_mappings top-level key.
  • approver (User) - Retrieves the first approver (as determined by user ID) on the workspace who is viewable to the current user. The response will include approver_id, which references the data in the users top-level key.
  • approvers (User) - Retrieves all time approvers on the workspace who are viewable to the current user. The response will include approver_ids, which references the data in the users top-level key.
  • creator (User) - Retrieves the user who created the project. The response will include creator_id, which references the data in the users top-level key. If the creator has left the project, you can use primary_counterpart to get the provider-side team lead.
  • current_status_report (StatusReport) - Retrieves the most recent project status report from today. The response will include current_status_report_id, which references the data in the status_reports top-level key.
  • current_user_participation (Participation) - Retrieves the workspace participation of the current user. The response will include current_user_participation_ids, which references the data in the participations top-level key.
  • custom_field_values (CustomFieldValue) - Retrieves custom field values for the workspace. The response will include custom_field_value_ids, which references the data in the custom_field_values top-level key.
  • external_references (ExternalReference) - Includes references to external integrations for this object.
  • financial_viewers (User) - Retrieves the users on the project who have financial access. The response will include financial_viewer_ids, which references the data in the users top-level key.
  • next_uncompleted_milestone (Story) - Retrieves the next project milestone that is not complete. The response will include next_uncompleted_milestone_id, which references the data in the stories top-level key.
  • participants (User) - Retrieves users that are participating in the project. The response will include participant_ids, which references the data in the users top-level key.
  • participations (Participation) - Retrieves the participations of each participant in the project. The response will include participation_ids, which references the data in the participations top-level key.
  • possible_approvers (User) - Retrieves the users that can be made time approvers on the workspace. The response will include possible_approver_ids, which references the data in the users top-level key.
  • primary_counterpart (User) - Retrieves the lead of the Clients team. The response will include primary_counterpart_id, which references the data in the users top-level key.
  • primary_maven (User) - Retrieves the lead of the Providers team. The response will include primary_maven_id, which references the data in the users top-level key.
  • primary_workspace_group (WorkspaceGroup) - Retrieves the primary group associated with the project. The response will include primary_workspace_group_id, which references the data in the workspace_groups top-level key.
  • status_reports (StatusReport) - Retrieves the status reports for the workspace. The response will include status_report_ids, which references the data in the status_reports top-level key.
  • timesheet_submissions (TimesheetSubmission) - Retrieves the list of all submitted timesheets which the user can approve on the project. The response will include timesheet_submission_ids, which references the data in the timesheet_submissions top-level key.
  • workspace_groups (WorkspaceGroup) - Retrieves groups associated with the project that is visible to the current user. The response will include workspace_group_ids, which references the data in the workspace_groups top-level key.
  • workspace_resources (WorkspaceResource) - Retrieves the named resources for the workspace. The response will include workspace_resource_ids, which references the data in the workspace_resources top-level key.
  • workspace_resources_with_unnamed (WorkspaceResource) - Retrieves the named and unnamed resources for the workspace. The response will include workspace_resources_with_unnamed_ids, which references the data in the workspace_resources top-level key.
optional_fields
Array of strings

Allows you to request one or more optional fields as an array.

Items Enum: "client_lead_name" "provider_lead_name" "stage" "estimated_minutes" "total_invoiced" "total_minutes_approved" "billable_minutes" "non_billable_minutes" "minutes_logged" "incoming_email_address" "lock_date"
Request Body schema: application/json
required
object
project_tracker_template_id
integer <int32>

The ID of the template to use to populate tasks and other information in the project.

project_template_weekends_as_workdays
boolean

Whether weekends count as work days when applying the template. If true, weekend days will be included in task durations.

project_template_start_date
string <date>

The start date that tasks will be based on when the template is applied. The date must be in ISO 8601 format.

project_template_checklist_as_todos
boolean

Whether checklist items are converted to To Dos when applying the template.

project_template_create_unnamed_resources
boolean

If true, all template resources and task assignments will be mapped to unnamed resources and project_template_assignment_mappings will be ignored.

project_template_distribute_hours
boolean

Whether task estimated hours in the template are automatically added as scheduled hours for all tasks when applying the template. The hours will be distributed evenly between the task start date and end date.

Array of objects

This maps template resources to named or unnamed resources when the template is applied.

project_template_before_story_id
integer <int32>

The ID of an existing task the template tasks should be inserted after. The provided task ID must belong to a top-level task.

Responses
200

Workspace has been updated.

Response Schema: application/json
count
integer <int32>
object
Array of objects
object
object
object
object
object
object
object
object
object
object
object
object
400

Bad Request

401

Unauthorized request

403

Forbidden request

404

Page Not Found

422

Unprocessable Entity

503

Service is unavailable

put/workspaces/{id}/apply_template
Request samples
application/json
{
  • "workspace": {
    }
}
Response samples
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "workspaces": {
    },
  • "external_references": {
    },
  • "stories": {
    },
  • "users": {
    },
  • "participations": {
    },
  • "timesheet_submissions": {
    },
  • "workspace_groups": {
    },
  • "custom_field_values": {
    },
  • "workspace_resources": {
    },
  • "status_reports": {
    },
  • "account_colors": {
    },
  • "account_insights_mappings": {
    }
}

Creating a Workspace Invitation

Sends an invitation to a project.

To add participants to a project, they must first be invited. Users that already exist in Kantata OX will automatically accept the invitation and be added to the project. Users that don't already exist will have the option to create an account.

This endpoint has its own rate limit. See the Knowledge Base for more information.

This endpoint returns structured Workspace Invitation 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 workspace_invitations top-level JSON key. Please see our Response Format section for more information.

Request
path Parameters
id
required
integer

The ID of the Model.

Request Body schema: application/json
required
object
full_name
required
string

The name of the user being invited (required).

email_address
required
string

The email address of the user being invited.

invitee_role
required
string

The role of the user being invited; either 'maven' (consultant) or 'buyer' (client).

subject
string

The subject of the invitation email message.

message
string

The text of the invitation email message.

Responses
200

Workspace Invitation has been created.

Response Schema: application/json
count
integer <int32>
object
Array of objects
object
400

Bad Request

401

Unauthorized request

403

Forbidden request

404

Page Not Found

422

Unprocessable Entity

503

Service is unavailable

post/workspaces/{id}/invite
Request samples
application/json
{
  • "invitation": {
    }
}
Response samples
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "workspace_invitations": {
    }
}

Fetch permissions in a Workspace

Gets less common project permissions for the authenticated user.

This endpoint returns structured Workspace 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 workspaces top-level JSON key. Please see our Response Format section for more information.

Request
path Parameters
id
required
integer

The ID of the Model.

query Parameters
include
string

Any of the below associations can be included in your request by providing the include param, e.g. include=association1,association2.

  • account_color (AccountColor) - Retrieves the color of the workspace. The response will include account_color_id, which references the data in the account_colors top-level key.
  • account_insights_mappings (AccountInsightsMapping) - Retrieves the Insights dynamic dashboards in the workspace. The response will include account_insights_mapping_ids, which references the data in the account_insights_mappings top-level key.
  • approver (User) - Retrieves the first approver (as determined by user ID) on the workspace who is viewable to the current user. The response will include approver_id, which references the data in the users top-level key.
  • approvers (User) - Retrieves all time approvers on the workspace who are viewable to the current user. The response will include approver_ids, which references the data in the users top-level key.
  • creator (User) - Retrieves the user who created the project. The response will include creator_id, which references the data in the users top-level key. If the creator has left the project, you can use primary_counterpart to get the provider-side team lead.
  • current_status_report (StatusReport) - Retrieves the most recent project status report from today. The response will include current_status_report_id, which references the data in the status_reports top-level key.
  • current_user_participation (Participation) - Retrieves the workspace participation of the current user. The response will include current_user_participation_ids, which references the data in the participations top-level key.
  • custom_field_values (CustomFieldValue) - Retrieves custom field values for the workspace. The response will include custom_field_value_ids, which references the data in the custom_field_values top-level key.
  • external_references (ExternalReference) - Includes references to external integrations for this object.
  • financial_viewers (User) - Retrieves the users on the project who have financial access. The response will include financial_viewer_ids, which references the data in the users top-level key.
  • next_uncompleted_milestone (Story) - Retrieves the next project milestone that is not complete. The response will include next_uncompleted_milestone_id, which references the data in the stories top-level key.
  • participants (User) - Retrieves users that are participating in the project. The response will include participant_ids, which references the data in the users top-level key.
  • participations (Participation) - Retrieves the participations of each participant in the project. The response will include participation_ids, which references the data in the participations top-level key.
  • possible_approvers (User) - Retrieves the users that can be made time approvers on the workspace. The response will include possible_approver_ids, which references the data in the users top-level key.
  • primary_counterpart (User) - Retrieves the lead of the Clients team. The response will include primary_counterpart_id, which references the data in the users top-level key.
  • primary_maven (User) - Retrieves the lead of the Providers team. The response will include primary_maven_id, which references the data in the users top-level key.
  • primary_workspace_group (WorkspaceGroup) - Retrieves the primary group associated with the project. The response will include primary_workspace_group_id, which references the data in the workspace_groups top-level key.
  • status_reports (StatusReport) - Retrieves the status reports for the workspace. The response will include status_report_ids, which references the data in the status_reports top-level key.
  • timesheet_submissions (TimesheetSubmission) - Retrieves the list of all submitted timesheets which the user can approve on the project. The response will include timesheet_submission_ids, which references the data in the timesheet_submissions top-level key.
  • workspace_groups (WorkspaceGroup) - Retrieves groups associated with the project that is visible to the current user. The response will include workspace_group_ids, which references the data in the workspace_groups top-level key.
  • workspace_resources (WorkspaceResource) - Retrieves the named resources for the workspace. The response will include workspace_resource_ids, which references the data in the workspace_resources top-level key.
  • workspace_resources_with_unnamed (WorkspaceResource) - Retrieves the named and unnamed resources for the workspace. The response will include workspace_resources_with_unnamed_ids, which references the data in the workspace_resources top-level key.
optional_fields
Array of strings

Allows you to request one or more optional fields as an array.

Items Enum: "client_lead_name" "provider_lead_name" "stage" "estimated_minutes" "total_invoiced" "total_minutes_approved" "billable_minutes" "non_billable_minutes" "minutes_logged" "incoming_email_address" "lock_date"
Responses
200

A list of Workspaces have been retrieved.

Response Schema: application/json
can_change_budgetability
boolean

Whether the user has permission to change the project budget settings.

can_change_currency
boolean

Whether currency can be changed for the project.

can_change_time_approvals
boolean

Whether the user has permission to change the time approval settings, and whether changing time approval settings is allowed in the project.

can_change_expense_approvals
boolean

Whether the user has permission to change the expense approval settings, and whether changing the expense approval settings is allowed in the project.

can_edit_change_orders
boolean

Whether project change orders can be disabled.

can_edit_project_settings
boolean

Whether the user has permission to edit settings in the project.

can_edit_team_names
boolean

Whether the user has permission to edit team names in the project.

can_manage_invoice_preferences
boolean

Whether the user has permission to edit invoice preferences in the project.

can_manage_finance
boolean

Whether the user has permission (and the account has access) to project finance settings.

can_view_insights_dynamic_dashboards
boolean

Whether the user has permission to view dynamic dashboards on the account.

400

Bad Request

401

Unauthorized request

403

Forbidden request

404

Page Not Found

422

Unprocessable Entity

503

Service is unavailable

get/workspaces/{id}/permissions
Request samples
Response samples
application/json
{
  • "can_change_budgetability": true,
  • "can_change_currency": true,
  • "can_change_time_approvals": true,
  • "can_change_expense_approvals": true,
  • "can_edit_change_orders": true,
  • "can_edit_project_settings": true,
  • "can_edit_team_names": true,
  • "can_manage_invoice_preferences": true,
  • "can_manage_finance": true,
  • "can_view_insights_dynamic_dashboards": true
}

Toggle expense approval setting

Enables the expense approval setting for a project.

If a backfill_date is specified, expenses until the specified date will be approved and the results of the approval will be emailed to the authenticated user. Once the expenses have been approved, they cannot be unapproved.

This endpoint returns structured Workspace 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 workspaces top-level JSON key. Please see our Response Format section for more information.

Request
path Parameters
id
required
integer

The ID of the Model.

query Parameters
include
string

Any of the below associations can be included in your request by providing the include param, e.g. include=association1,association2.

  • account_color (AccountColor) - Retrieves the color of the workspace. The response will include account_color_id, which references the data in the account_colors top-level key.
  • account_insights_mappings (AccountInsightsMapping) - Retrieves the Insights dynamic dashboards in the workspace. The response will include account_insights_mapping_ids, which references the data in the account_insights_mappings top-level key.
  • approver (User) - Retrieves the first approver (as determined by user ID) on the workspace who is viewable to the current user. The response will include approver_id, which references the data in the users top-level key.
  • approvers (User) - Retrieves all time approvers on the workspace who are viewable to the current user. The response will include approver_ids, which references the data in the users top-level key.
  • creator (User) - Retrieves the user who created the project. The response will include creator_id, which references the data in the users top-level key. If the creator has left the project, you can use primary_counterpart to get the provider-side team lead.
  • current_status_report (StatusReport) - Retrieves the most recent project status report from today. The response will include current_status_report_id, which references the data in the status_reports top-level key.
  • current_user_participation (Participation) - Retrieves the workspace participation of the current user. The response will include current_user_participation_ids, which references the data in the participations top-level key.
  • custom_field_values (CustomFieldValue) - Retrieves custom field values for the workspace. The response will include custom_field_value_ids, which references the data in the custom_field_values top-level key.
  • external_references (ExternalReference) - Includes references to external integrations for this object.
  • financial_viewers (User) - Retrieves the users on the project who have financial access. The response will include financial_viewer_ids, which references the data in the users top-level key.
  • next_uncompleted_milestone (Story) - Retrieves the next project milestone that is not complete. The response will include next_uncompleted_milestone_id, which references the data in the stories top-level key.
  • participants (User) - Retrieves users that are participating in the project. The response will include participant_ids, which references the data in the users top-level key.
  • participations (Participation) - Retrieves the participations of each participant in the project. The response will include participation_ids, which references the data in the participations top-level key.
  • possible_approvers (User) - Retrieves the users that can be made time approvers on the workspace. The response will include possible_approver_ids, which references the data in the users top-level key.
  • primary_counterpart (User) - Retrieves the lead of the Clients team. The response will include primary_counterpart_id, which references the data in the users top-level key.
  • primary_maven (User) - Retrieves the lead of the Providers team. The response will include primary_maven_id, which references the data in the users top-level key.
  • primary_workspace_group (WorkspaceGroup) - Retrieves the primary group associated with the project. The response will include primary_workspace_group_id, which references the data in the workspace_groups top-level key.
  • status_reports (StatusReport) - Retrieves the status reports for the workspace. The response will include status_report_ids, which references the data in the status_reports top-level key.
  • timesheet_submissions (TimesheetSubmission) - Retrieves the list of all submitted timesheets which the user can approve on the project. The response will include timesheet_submission_ids, which references the data in the timesheet_submissions top-level key.
  • workspace_groups (WorkspaceGroup) - Retrieves groups associated with the project that is visible to the current user. The response will include workspace_group_ids, which references the data in the workspace_groups top-level key.
  • workspace_resources (WorkspaceResource) - Retrieves the named resources for the workspace. The response will include workspace_resource_ids, which references the data in the workspace_resources top-level key.
  • workspace_resources_with_unnamed (WorkspaceResource) - Retrieves the named and unnamed resources for the workspace. The response will include workspace_resources_with_unnamed_ids, which references the data in the workspace_resources top-level key.
optional_fields
Array of strings

Allows you to request one or more optional fields as an array.

Items Enum: "client_lead_name" "provider_lead_name" "stage" "estimated_minutes" "total_invoiced" "total_minutes_approved" "billable_minutes" "non_billable_minutes" "minutes_logged" "incoming_email_address" "lock_date"
Request Body schema: application/json
required
object
enable
boolean

Whether expense approvals should be enabled.

backfill_date
string <date>

Date through which to backfill expenses. The date must be in ISO 8601 format.

Responses
200

Workspace has been updated.

Response Schema: application/json
count
integer <int32>
object
Array of objects
object
object
object
object
object
object
object
object
object
object
object
object
400

Bad Request

401

Unauthorized request

403

Forbidden request

404

Page Not Found

422

Unprocessable Entity

503

Service is unavailable

put/workspaces/{id}/toggle_expense_approvals
Request samples
application/json
{
  • "workspace": {
    }
}
Response samples
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "workspaces": {
    },
  • "external_references": {
    },
  • "stories": {
    },
  • "users": {
    },
  • "participations": {
    },
  • "timesheet_submissions": {
    },
  • "workspace_groups": {
    },
  • "custom_field_values": {
    },
  • "workspace_resources": {
    },
  • "status_reports": {
    },
  • "account_colors": {
    },
  • "account_insights_mappings": {
    }
}

Toggle time approval setting

Turns the time approval setting for a project on or off.

If you enable the time approval setting and specify a backfill_date, time entries until the specified date will be approved and the results of the approval will be emailed to the authenticated user. Once the time entries have been approved, they cannot be unapproved.

This setting can't be turned off if there are active timesheet submissions or approvals for the project.

This endpoint returns structured Workspace 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 workspaces top-level JSON key. Please see our Response Format section for more information.

Request
path Parameters
id
required
integer

The ID of the Model.

query Parameters
include
string

Any of the below associations can be included in your request by providing the include param, e.g. include=association1,association2.

  • account_color (AccountColor) - Retrieves the color of the workspace. The response will include account_color_id, which references the data in the account_colors top-level key.
  • account_insights_mappings (AccountInsightsMapping) - Retrieves the Insights dynamic dashboards in the workspace. The response will include account_insights_mapping_ids, which references the data in the account_insights_mappings top-level key.
  • approver (User) - Retrieves the first approver (as determined by user ID) on the workspace who is viewable to the current user. The response will include approver_id, which references the data in the users top-level key.
  • approvers (User) - Retrieves all time approvers on the workspace who are viewable to the current user. The response will include approver_ids, which references the data in the users top-level key.
  • creator (User) - Retrieves the user who created the project. The response will include creator_id, which references the data in the users top-level key. If the creator has left the project, you can use primary_counterpart to get the provider-side team lead.
  • current_status_report (StatusReport) - Retrieves the most recent project status report from today. The response will include current_status_report_id, which references the data in the status_reports top-level key.
  • current_user_participation (Participation) - Retrieves the workspace participation of the current user. The response will include current_user_participation_ids, which references the data in the participations top-level key.
  • custom_field_values (CustomFieldValue) - Retrieves custom field values for the workspace. The response will include custom_field_value_ids, which references the data in the custom_field_values top-level key.
  • external_references (ExternalReference) - Includes references to external integrations for this object.
  • financial_viewers (User) - Retrieves the users on the project who have financial access. The response will include financial_viewer_ids, which references the data in the users top-level key.
  • next_uncompleted_milestone (Story) - Retrieves the next project milestone that is not complete. The response will include next_uncompleted_milestone_id, which references the data in the stories top-level key.
  • participants (User) - Retrieves users that are participating in the project. The response will include participant_ids, which references the data in the users top-level key.
  • participations (Participation) - Retrieves the participations of each participant in the project. The response will include participation_ids, which references the data in the participations top-level key.
  • possible_approvers (User) - Retrieves the users that can be made time approvers on the workspace. The response will include possible_approver_ids, which references the data in the users top-level key.
  • primary_counterpart (User) - Retrieves the lead of the Clients team. The response will include primary_counterpart_id, which references the data in the users top-level key.
  • primary_maven (User) - Retrieves the lead of the Providers team. The response will include primary_maven_id, which references the data in the users top-level key.
  • primary_workspace_group (WorkspaceGroup) - Retrieves the primary group associated with the project. The response will include primary_workspace_group_id, which references the data in the workspace_groups top-level key.
  • status_reports (StatusReport) - Retrieves the status reports for the workspace. The response will include status_report_ids, which references the data in the status_reports top-level key.
  • timesheet_submissions (TimesheetSubmission) - Retrieves the list of all submitted timesheets which the user can approve on the project. The response will include timesheet_submission_ids, which references the data in the timesheet_submissions top-level key.
  • workspace_groups (WorkspaceGroup) - Retrieves groups associated with the project that is visible to the current user. The response will include workspace_group_ids, which references the data in the workspace_groups top-level key.
  • workspace_resources (WorkspaceResource) - Retrieves the named resources for the workspace. The response will include workspace_resource_ids, which references the data in the workspace_resources top-level key.
  • workspace_resources_with_unnamed (WorkspaceResource) - Retrieves the named and unnamed resources for the workspace. The response will include workspace_resources_with_unnamed_ids, which references the data in the workspace_resources top-level key.
optional_fields
Array of strings

Allows you to request one or more optional fields as an array.

Items Enum: "client_lead_name" "provider_lead_name" "stage" "estimated_minutes" "total_invoiced" "total_minutes_approved" "billable_minutes" "non_billable_minutes" "minutes_logged" "incoming_email_address" "lock_date"
Request Body schema: application/json
required
object
enable
boolean

Whether time approvals should be enabled.

backfill_date
string <date>

If enable is true, this is the date through which to approve existing time entries. The date must be in ISO 8601 format.

Responses
200

Workspace has been updated.

Response Schema: application/json
count
integer <int32>
object
Array of objects
object
object
object
object
object
object
object
object
object
object
object
object
400

Bad Request

401

Unauthorized request

403

Forbidden request

404

Page Not Found

422

Unprocessable Entity

503

Service is unavailable

put/workspaces/{id}/toggle_time_approvals
Request samples
application/json
{
  • "workspace": {
    }
}
Response samples
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "workspaces": {
    },
  • "external_references": {
    },
  • "stories": {
    },
  • "users": {
    },
  • "participations": {
    },
  • "timesheet_submissions": {
    },
  • "workspace_groups": {
    },
  • "custom_field_values": {
    },
  • "workspace_resources": {
    },
  • "status_reports": {
    },
  • "account_colors": {
    },
  • "account_insights_mappings": {
    }
}

Unarchive Workspace with Approvals

Unarchives a project.

If a time lock is set for the account and the project’s time approval setting is enabled, this endpoint will also approve all unsubmitted time entries on or before the time lock date.

This endpoint returns structured Workspace 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 workspaces top-level JSON key. Please see our Response Format section for more information.

Request
path Parameters
id
required
integer

The ID of the Model.

query Parameters
include
string

Any of the below associations can be included in your request by providing the include param, e.g. include=association1,association2.

  • account_color (AccountColor) - Retrieves the color of the workspace. The response will include account_color_id, which references the data in the account_colors top-level key.
  • account_insights_mappings (AccountInsightsMapping) - Retrieves the Insights dynamic dashboards in the workspace. The response will include account_insights_mapping_ids, which references the data in the account_insights_mappings top-level key.
  • approver (User) - Retrieves the first approver (as determined by user ID) on the workspace who is viewable to the current user. The response will include approver_id, which references the data in the users top-level key.
  • approvers (User) - Retrieves all time approvers on the workspace who are viewable to the current user. The response will include approver_ids, which references the data in the users top-level key.
  • creator (User) - Retrieves the user who created the project. The response will include creator_id, which references the data in the users top-level key. If the creator has left the project, you can use primary_counterpart to get the provider-side team lead.
  • current_status_report (StatusReport) - Retrieves the most recent project status report from today. The response will include current_status_report_id, which references the data in the status_reports top-level key.
  • current_user_participation (Participation) - Retrieves the workspace participation of the current user. The response will include current_user_participation_ids, which references the data in the participations top-level key.
  • custom_field_values (CustomFieldValue) - Retrieves custom field values for the workspace. The response will include custom_field_value_ids, which references the data in the custom_field_values top-level key.
  • external_references (ExternalReference) - Includes references to external integrations for this object.
  • financial_viewers (User) - Retrieves the users on the project who have financial access. The response will include financial_viewer_ids, which references the data in the users top-level key.
  • next_uncompleted_milestone (Story) - Retrieves the next project milestone that is not complete. The response will include next_uncompleted_milestone_id, which references the data in the stories top-level key.
  • participants (User) - Retrieves users that are participating in the project. The response will include participant_ids, which references the data in the users top-level key.
  • participations (Participation) - Retrieves the participations of each participant in the project. The response will include participation_ids, which references the data in the participations top-level key.
  • possible_approvers (User) - Retrieves the users that can be made time approvers on the workspace. The response will include possible_approver_ids, which references the data in the users top-level key.
  • primary_counterpart (User) - Retrieves the lead of the Clients team. The response will include primary_counterpart_id, which references the data in the users top-level key.
  • primary_maven (User) - Retrieves the lead of the Providers team. The response will include primary_maven_id, which references the data in the users top-level key.
  • primary_workspace_group (WorkspaceGroup) - Retrieves the primary group associated with the project. The response will include primary_workspace_group_id, which references the data in the workspace_groups top-level key.
  • status_reports (StatusReport) - Retrieves the status reports for the workspace. The response will include status_report_ids, which references the data in the status_reports top-level key.
  • timesheet_submissions (TimesheetSubmission) - Retrieves the list of all submitted timesheets which the user can approve on the project. The response will include timesheet_submission_ids, which references the data in the timesheet_submissions top-level key.
  • workspace_groups (WorkspaceGroup) - Retrieves groups associated with the project that is visible to the current user. The response will include workspace_group_ids, which references the data in the workspace_groups top-level key.
  • workspace_resources (WorkspaceResource) - Retrieves the named resources for the workspace. The response will include workspace_resource_ids, which references the data in the workspace_resources top-level key.
  • workspace_resources_with_unnamed (WorkspaceResource) - Retrieves the named and unnamed resources for the workspace. The response will include workspace_resources_with_unnamed_ids, which references the data in the workspace_resources top-level key.
optional_fields
Array of strings

Allows you to request one or more optional fields as an array.

Items Enum: "client_lead_name" "provider_lead_name" "stage" "estimated_minutes" "total_invoiced" "total_minutes_approved" "billable_minutes" "non_billable_minutes" "minutes_logged" "incoming_email_address" "lock_date"
Responses
200

Workspace has been updated.

Response Schema: application/json
count
integer <int32>
object
Array of objects
object
object
object
object
object
object
object
object
object
object
object
object
400

Bad Request

401

Unauthorized request

403

Forbidden request

404

Page Not Found

422

Unprocessable Entity

503

Service is unavailable

put/workspaces/{id}/unarchive_with_approvals
Request samples
Response samples
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "workspaces": {
    },
  • "external_references": {
    },
  • "stories": {
    },
  • "users": {
    },
  • "participations": {
    },
  • "timesheet_submissions": {
    },
  • "workspace_groups": {
    },
  • "custom_field_values": {
    },
  • "workspace_resources": {
    },
  • "status_reports": {
    },
  • "account_colors": {
    },
  • "account_insights_mappings": {
    }
}