Kantata Kantata OX Knowledge Base Release Notes Status Page
Kantata OX API Documentation

Workspaces

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

Fetching a list of Workspaces

By default, you will not receive archived projects (and will receive a 404 status on the "show" route) unless you provide the include_archived=true filter.

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

A comma separated string of color ids to filter on.

archived
string

Only includes archived project, based on the specified option. Options are 'only', 'exclude', or 'include'.

budgeted
boolean

Only includes projects that are budgeted. True for only budgeted budgeted; false for only non-budgeted.

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 0 to many comma separated custom field choice values IDs. The custom field choice value can also be the word 'blank'. Multiple custom field choice values IDs can be provided by separating them with a semi-colon.

The filter supports the following formats:

  • 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_2_ID;custom_field_3_ID:blank.
by_custom_currency_value
string

Filter by a custom field currency value, represented as a string with the custom field id and the currency value, separated by a colon. Optionally, the currency can be supplied, separted from the currency value with another colon. Multiple custom field currency values an be provided by separating them with a semi-colon. For example, "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, starting date, and ending date, seperated by colons. Both a starting date and ending date can be supplied, or just one can be provided. Multiple custom field date values an be provided by separating them with a semi-colon. For example, "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 and the number value, separated by a colon. Multiple custom field number values an be provided by separating them with a semi-colon. For example, "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 and the text value, separated by a colon. Multiple custom field text values an be provided by separating them with a semi-colon. For example, "1:something; 2:else".

can_create_line_items
boolean

Only includes projects where the current user can create expenses or time entries.

created_after
string

Filter for records created after a specified datetime.

created_at
string

(Deprecated) Use created_before and created_after filters instead. Only includes projects created between the specified date range. For example, '2014-12-05;2014-12-25'.

created_before
string

Filter for records created before a specified datetime.

creator
string

Only includes projects in which the specified set IDs belong to the creator of the project. For example, '10,20'.

current_user_is_maven_participant
boolean

Only includes projects in which the requester is a Provider in the project.

custom_date_range
string

Only includes projects with custom field date values within the specified range. Argument is formatted as field_id:from:to;.

custom_integer_ranges
string

Only includes projects containing integer custom fields with values within the specified range (specified by field_id:min:max, delimited by semi-colons). For example '42:20:10;.

except
string

Only includes projects that do not match the specified 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_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

Only includes projects that can be viewed by the requester (where the requester has financial access and is a provider on the project).

for_approver
integer <int32>

Only includes projects in which the user corresponding to the passed ID can approve time.

has_approvers
boolean

Only includes projects that have an approver.

has_external_references
boolean

Filter by whether or not the object has external references.

has_maven_participant
integer <int32>

Only includes projects which the specified user is participating as a Provider.

has_participant
integer <int32>

Only includes projects in which the specified user is an active participant.

has_participation
boolean

Only includes projects in which the user that is logged-in 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) - The color of the workspace.
  • approver (User) - The first approver on the workspace who is viewable to the current user.
  • approvers (User) - The list of approvers on the workspace who are viewable to the current user.
  • creator (User) - The user who created the project. This user is referenced by the creator_id attribute in the request body. If this user has left the project, you may need to use primary_counterpart instead.
  • current_status_report (StatusReport) - The most recent project status report from today.
  • current_user_participation (Participation) - The current user's participation in the project.
  • custom_field_values (CustomFieldValue) - Custom field values for the workspace.
  • external_references (ExternalReference) - Includes references to external integrations for this object.
  • financial_viewers (User) - The list of all users on the project who have financial access.
  • next_uncompleted_milestone (Story) - The next project milestone that is not complete.
  • participants (User) - Users that are participating in the project.
  • participations (Participation) - The participations of each participant in the project.
  • possible_approvers (User) - The list of users that can be made approvers on the workspace.
  • primary_counterpart (User) - The lead of the Clients team.
  • primary_maven (User) - The lead of the Providers team.
  • primary_workspace_group (WorkspaceGroup) - Primary group associated with the project.
  • status_reports (StatusReport) - The status reports for the workspace.
  • timesheet_submissions (TimesheetSubmission) - The list of all submitted timesheets which the user can approve on the project.
  • workspace_groups (WorkspaceGroup) - Groups associated with the project that is visible to the current user.
  • workspace_resources (WorkspaceResource) - The named resources for the workspace.
  • workspace_resources_with_unnamed (WorkspaceResource) - The named and unnamed resources for the workspace.
include_archived
boolean
Default: false

Only includes archived projects (if set as 'true').

matching
string

Only includes projects in which the title matches the search string.

milestone_weight_percentage_complete
string

Only includes projects with milestones in which the percentage complete is within the specified range. For example, 15,30.

on_account_by_orgs
boolean

Filters for projects on the user's account. Filters for projects that respect the heirarchy of organizations. Only available to report viewers.

on_my_account
boolean

Only includes projects belonging to the account of the user that is logged-in.

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

Filters for projects which can be joined by the user. Filters for projects that respect the heirarchy of organizations.

only_participating_or_joinable
boolean

Filters for projects that can be joined or participated in by the user.

only_project_manager_in
boolean

Filters for projects on the user's account. Filters for projects in which the user is participating as a consultant. Filters where their access if financial or greater.

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" "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, due_date:asc, due_date:desc, last_viewed:asc, last_viewed:desc, percentage_complete:asc, percentage_complete:desc, price:asc, price:desc, search, start_date:asc, start_date:desc, status:asc, status:desc, title:asc, title:desc, updated_at:asc, and updated_at:desc.

page
integer <int32>
Default: 1
participant_or_org_member_in
boolean

Filters for projects on the user's account. Filters for projects in which the user is participating. Filters for projects that respect the heirarchy of organizations.

pending_timesheet_submissions
string

Only includes projects that have pending timesheet submissions within the specified date range. For example, '2014-12-05;2014-12-25'.

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

Only includes projects in which the specified set IDs belong to Provider Leads in the project. For example, '10,20'.

require_time_approvals
boolean

Only includes projects that require time approvals.

requiring_expense_approval
boolean

Only includes projects that require expense approvals.

search
string
selected_choices
string

Only includes projects with the selected custom field choice value. Argument is formatted as field_id:choice_ids;. 'none' represents no selection. For example: 1:3,2;4:2,none.

updated_after
string

Filter for records updated after a specified datetime.

updated_before
string

Filter for records updated before a specified datetime.

user_not_participating
integer <int32>

Only includes projects in which the specified user is not participating.

viewable_for_time_administration
boolean

Only includes projects where the current user can approve time. Takes include_archived option.

without_external_reference_service_name
string

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

workspace_groups
string

Only includes projects that are associated with the specified project groups. 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
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": {
    }
}
Creating a new 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 
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) - The color of the workspace.
    • 

  • approver (User) - The first approver on the workspace who is viewable to the current user.
    • 

  • approvers (User) - The list of approvers on the workspace who are viewable to the current user.
    • 

  • creator (User) - The user who created the project. This user is referenced by the creator_id attribute in the request body. If this user has left the project, you may need to use primary_counterpart instead.
    • 

  • current_status_report (StatusReport) - The most recent project status report from today.
    • 

  • current_user_participation (Participation) - The current user's participation in the project.
    • 

  • custom_field_values (CustomFieldValue) - Custom field values for the workspace.
    • 

  • external_references (ExternalReference) - Includes references to external integrations for this object.
    • 

  • financial_viewers (User) - The list of all users on the project who have financial access.
    • 

  • next_uncompleted_milestone (Story) - The next project milestone that is not complete.
    • 

  • participants (User) - Users that are participating in the project.
    • 

  • participations (Participation) - The participations of each participant in the project.
    • 

  • possible_approvers (User) - The list of users that can be made approvers on the workspace.
    • 

  • primary_counterpart (User) - The lead of the Clients team.
    • 

  • primary_maven (User) - The lead of the Providers team.
    • 

  • primary_workspace_group (WorkspaceGroup) - Primary group associated with the project.
    • 

  • status_reports (StatusReport) - The status reports for the workspace.
    • 

  • timesheet_submissions (TimesheetSubmission) - The list of all submitted timesheets which the user can approve on the project.
    • 

  • workspace_groups (WorkspaceGroup) - Groups associated with the project that is visible to the current user.
    • 

  • workspace_resources (WorkspaceResource) - The named resources for the workspace.
    • 

  • workspace_resources_with_unnamed (WorkspaceResource) - The named and unnamed resources for the workspace.
    • 



 
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" "lock_date"  
Request Body schema: application/json
object
 
title
required
string
 
consultant_role_name
string
The label for the consultant team.


 
client_role_name
string
The label for client team.


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


 
start_date
string <date> 
 
due_date
string <date> 
 
description
string
 
currency
string
Defaults to the user's account's currency or USD.
This is only relevant for a project that is budgeted.
If a rate_card_id is supplied, this argument is ignored.


 
access_level
string
Whether the project is open, and who can join it.


 Enum: "invitation" "open" "admins"  
rate_card_id
integer <int32> 
The rate card for the project. The rate card currency must match that of the project.


 
exclude_archived_stories_percent_complete
boolean
Exclude archived tasks from being used in completion percentage calculation.


 
tasks_default_non_billable
boolean
Defaults tasks as billable.


 
stories_are_fixed_fee_by_default
boolean
Defaults tasks as fixed fee.


 
expenses_in_burn_rate
boolean
Any expenses (and additional items in invoices) created in the project will count against the budget used in the project's burn rate calculation.


 
posts_require_privacy_decision
boolean
Determines who can see communications.


 
object
Allows for customizing invoices.


 
approver_id
integer <int32> 
Determines the time approver for a project.


 
workspace_group_ids
Array of integers <int32> 
Determines the groups to which the project belongs.


 
project_template_start_date
string <date> 
Sets the project start date when applying a template.


 
Array of objects
Assigns template resource mappings when applying a template.


 
project_template_weekends_as_workdays
boolean
Sets whether weekends count as work days when applying a template.


 
project_template_create_unnamed_resources
boolean
Converts all project template assignments with a role to unnamed resources in the project, and
ignores the project_template_assignment_mappings parameter.


 
project_template_distribute_hours
boolean
Sets whether estimated hours are automatically added as scheduled hours for all tasks when applying a template (distributed evenly between the task start date and end date).


 
project_tracker_template_id
integer <int32> 
Determines the template that should be used to fill the new project.


 
primary_workspace_group_id
integer <int32> 
Determines which group is the primary group for the project.


 
target_margin
integer <int32> 
The percentage of the cost that is profit.


 
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 account color ID associated with the project (optional).


 
Array of objects
Determines the custom field values for the project.


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


 Enum: "estimate" "project"  
creator_role
string
Can be either 'maven'/'consultant' (to represent the consultant role), or 'buyer'/'client' (to represent the client role). Defaults to 'maven' if not set.


 Enum: "client" "consultant"  
price
integer <int32> 
Determines the starting budget of a project. This is required for budgeted projects.


 
change_orders_enabled
boolean
Toggles if the project requires change orders for some fields.


If the attribute is not explicitly passed in the create request, it defaults to true if the workspace
is budgeted.


 
change_orders
boolean
Toggles if the project requires change orders for some fields.


If the attribute is not explicitly passed in the create request, it defaults to true if the workspace
is budgeted.


 
Array of objects
Determines the organizations of which the project will be a part.


 
Array of objects
Determines the participants in the project.


 
primary_maven_id
integer <int32> 
The user_id of the provider lead of the project.


 
require_expense_approvals
boolean
Requires expenses to be approved by Administrators.


 
require_time_approvals
boolean
Requires time entries to be approved by Administrators.


 
estimate_scenario_id
integer <int32> 
The estimate scenario from which the project was created.


 
attachment_ids
Array of integers <int32> 
The attachment ids for the files to be associated with the project after its 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
 
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": {
    }
}
Fetching a single Workspace
By default, you will receive a 404 status on the "show" route when loading an archived project unless
you provide the include_archived:true filter.


Users with Project lead (or lower) permissions can access projects they are not participants of IF they have All Projects or All Projects Accessible to Their Organization (if Orgs are enabled) access in the View Projects and Team Members in 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) - The color of the workspace.
    • 

  • approver (User) - The first approver on the workspace who is viewable to the current user.
    • 

  • approvers (User) - The list of approvers on the workspace who are viewable to the current user.
    • 

  • creator (User) - The user who created the project. This user is referenced by the creator_id attribute in the request body. If this user has left the project, you may need to use primary_counterpart instead.
    • 

  • current_status_report (StatusReport) - The most recent project status report from today.
    • 

  • current_user_participation (Participation) - The current user's participation in the project.
    • 

  • custom_field_values (CustomFieldValue) - Custom field values for the workspace.
    • 

  • external_references (ExternalReference) - Includes references to external integrations for this object.
    • 

  • financial_viewers (User) - The list of all users on the project who have financial access.
    • 

  • next_uncompleted_milestone (Story) - The next project milestone that is not complete.
    • 

  • participants (User) - Users that are participating in the project.
    • 

  • participations (Participation) - The participations of each participant in the project.
    • 

  • possible_approvers (User) - The list of users that can be made approvers on the workspace.
    • 

  • primary_counterpart (User) - The lead of the Clients team.
    • 

  • primary_maven (User) - The lead of the Providers team.
    • 

  • primary_workspace_group (WorkspaceGroup) - Primary group associated with the project.
    • 

  • status_reports (StatusReport) - The status reports for the workspace.
    • 

  • timesheet_submissions (TimesheetSubmission) - The list of all submitted timesheets which the user can approve on the project.
    • 

  • workspace_groups (WorkspaceGroup) - Groups associated with the project that is visible to the current user.
    • 

  • workspace_resources (WorkspaceResource) - The named resources for the workspace.
    • 

  • workspace_resources_with_unnamed (WorkspaceResource) - The named and unnamed resources for the workspace.
    • 



 
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" "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
 
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": {