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

Users

Users represent the individuals that are participating in Kantata OX projects . User objects are often returned as nested JSON objects within other returned items such as posts or tasks.

Fetching visible users

This endpoint allows you to access all visible users based on the permission level of the requester.

Note: This endpoint relies on project participation and will not return a member of your account who is not in a project. To see all users on the account, use the on_my_account option.

If the requester is an Account Administrator, the request will return all users who are participating in a project on the requester's account. In addition, it will return users not on the requester's account if they are participating in any project with an account member (either on the requester's account or their own account).

If the requester is not an Account Administrator, the request will only return users who are participating in a project with the requester.

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

Request
query Parameters
account_id
integer <int32>

Only includes users on the specified account. This filter is not available in conjunction with the on_my_account option.

account_role_ids
string

Only includes users with a specified role ID. (Format: 'role_id,role_id').

all_contacts
boolean

Returns all users in the requester's contact list.

assignable_to_resource
integer <int32>

Only includes users who can be assigned to a project resource with a specified ID.

belonging_to_orgs
string

Only includes users that belong to the specified geographies or departments (Format: 'geo_id,geo_id;dept_id,dept_id').

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

by_email_address
string

Only includes users whose email address exactly matches the specified address.

by_full_name
string

Only includes users with all or part of the specified full name.

by_full_name_or_account_role
string

Only includes users with a matching full_name or default_role specified a search term.

can_be_approver_in_workspace
integer <int32>

Only includes users that are providers and have financial access in a project with a specified ID.

can_view_reports
boolean

Only include users who have account level permission of reports viewer or above.

clients_only
boolean

Only includes users that are in at least one project as a client.

consultants_only
boolean

Only includes users that are in at least one project as a provider.

contacts_on_different_account
boolean

Returns all the users that are in the requester's contact list, but on seperate accounts.

created_after
string

Filter for records created after a specified datetime.

created_before
string

Filter for records created before a specified datetime.

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.

has_external_references
boolean

Filter by whether or not the object has external references.

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_membership (AccountMembership)
  • custom_field_values (CustomFieldValue) - The list of all the users custom field values that are readable by the current user.
  • external_references (ExternalReference) - Includes references to external integrations for this object.
  • role (Role)
  • skill_memberships (SkillMembership)
  • skills (Skill)
  • work_samples (WorkSample) - The list of all portfolio items belonging to this user.
is_project_lead
boolean

Only include users who have account level permission of project lead or above.

managers
boolean
Default: false

Only include users who are managers.

matching
string
not_assigned_to
integer <int32>

Only includes users who are not assigned to a task with specified ID.

not_following
integer <int32>

Only includes users who are not following a task with the specified ID.

not_on_calendars
string

Only includes users who are not added to the specified holiday calendars (Format: 'calendar_id,calendar_id,calendar_id'.

not_participant_in
integer <int32>

Only includes users not participating in a project with a specified ID.

on_my_account
boolean

Returns all users on the requester's account.

on_my_account_or_participant_in_workspace
integer <int32>

Returns all the users that are on the account, as well as all users participating in the provided workspace ID.

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_possible_managees
boolean

Only includes possible managees on the account.

only_possible_managers
boolean

Only includes possible managers on the account.

optional_fields
Array of strings

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

Items Enum: "bio" "website" "city" "state" "country" "abbreviated_timezone" "last_site_activity" "classification"
order
string
Default: "alphabetical:asc"

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

Valid values: alphabetical:asc and alphabetical:desc.

page
integer <int32>
Default: 1
participant_in
integer <int32>

Only includes users participating in a project with a specified ID.

per_page
integer <int32> <= 200
Default: 20
potential_followers_for_story
integer <int32>

Only includes users who are able to follow a task with the specified ID.

provider_leads_on_account_projects
boolean

Only includes users who are providers and leads in projects on the requester's account.

search
string
show_disabled
boolean
Default: false

Includes users with an inactive account membership and users who have been disabled by the Kantata team.

show_users_in_insights_groups
boolean

Only includes users who have access to insights.

updated_after
string

Filter for records updated after a specified datetime.

updated_before
string

Filter for records updated before a specified datetime.

with_created_estimates
boolean
Default: false

Only include users who have created an estimate.

with_skills
string

Only includes users with a set of skills at the specified levels (Format: '{'skill_id':[level,level],'skill_id':[level],'operation':'<or/and>'}').

with_users
Array of integers <int32>

Include only users for the provided IDs (Format: 'id,id,id').

without_external_reference_service_name
string

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

without_skills
string

Only includes users without the specified set of skills (Format: 'id,id,id').

without_timesheet_submission
string

Only include users who have not submitted a timesheet in a project between the specified start and end dates. (Format: 'workspace_id:start_date:end_date').

without_users
Array of integers <int32>

Exclude users for the provided IDs (Format: 'id,id,id').

write_access_in
integer <int32>

Only includes users who are participating in a project with a specified ID, and are not read-only in the project.

Responses
200

A list of Users have been retrieved.

Response Schema: application/json
count
integer <int32>
object
Array of objects
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/users
Request samples 
Response samples 
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "users": {
    },
  • "external_references": {
    },
  • "roles": {
    },
  • "skills": {
    },
  • "skill_memberships": {
    },
  • "account_memberships": {
    },
  • "work_samples": {
    },
  • "custom_field_values": {
    }
}
Fetch your own data
This endpoint allows you to fetch your own data.


This endpoint returns structured User 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 users 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_membership (AccountMembership)
    • 

  • custom_field_values (CustomFieldValue) - The list of all the users custom field values that are readable by the current user.
    • 

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

  • role (Role)
    • 

  • skill_memberships (SkillMembership)
    • 

  • skills (Skill)
    • 

  • work_samples (WorkSample) - The list of all portfolio items belonging to this user.
    • 



 
optional_fields
Array of strings
Allows you to request one or more optional fields as an array.


Items Enum: "bio" "website" "city" "state" "country" "abbreviated_timezone" "last_site_activity" "classification"  
Responses 
200
A list of Users have been retrieved.


Response Schema: application/json
count
integer <int32> 
 
object
 
Array of objects
 
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/users/me
Request samples 
Response samples 
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "users": {
    },
  • "external_references": {
    },
  • "roles": {
    },
  • "skills": {
    },
  • "skill_memberships": {
    },
  • "account_memberships": {
    },
  • "work_samples": {
    },
  • "custom_field_values": {
    }
}
Fetching a single User
This endpoint returns structured User 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 users 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_membership (AccountMembership)
    • 

  • custom_field_values (CustomFieldValue) - The list of all the users custom field values that are readable by the current user.
    • 

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

  • role (Role)
    • 

  • skill_memberships (SkillMembership)
    • 

  • skills (Skill)
    • 

  • work_samples (WorkSample) - The list of all portfolio items belonging to this user.
    • 



 
optional_fields
Array of strings
Allows you to request one or more optional fields as an array.


Items Enum: "bio" "website" "city" "state" "country" "abbreviated_timezone" "last_site_activity" "classification"  
Responses 
200
The User has been retrieved.


Response Schema: application/json
count
integer <int32> 
 
object
 
Array of objects
 
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/users/{id}
Request samples 
Response samples 
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "users": {
    },
  • "external_references": {
    },
  • "roles": {
    },
  • "skills": {
    },
  • "skill_memberships": {
    },
  • "account_memberships": {
    },
  • "work_samples": {
    },
  • "custom_field_values": {
    }
}
Updating an existing User
This endpoint returns structured User 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 users 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_membership (AccountMembership)
    • 

  • custom_field_values (CustomFieldValue) - The list of all the users custom field values that are readable by the current user.
    • 

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

  • role (Role)
    • 

  • skill_memberships (SkillMembership)
    • 

  • skills (Skill)
    • 

  • work_samples (WorkSample) - The list of all portfolio items belonging to this user.
    • 



 
optional_fields
Array of strings
Allows you to request one or more optional fields as an array.


Items Enum: "bio" "website" "city" "state" "country" "abbreviated_timezone" "last_site_activity" "classification"  
Request Body schema: application/json
object
 
full_name
string
The full name of the user.


 
headline
string
A short description of the user.


 
email_address
string
The email address for the user. If this value is different than the user's existing email_address it will require a new verification.


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


 
Responses 
200
User has been updated.


Response Schema: application/json
count
integer <int32> 
 
object
 
Array of objects
 
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/users/{id}
Request samples 
application/json
{
  • "user": {
    }
}
Response samples 
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "users": {
    },
  • "external_references": {
    },
  • "roles": {
    },
  • "skills": {
    },
  • "skill_memberships": {
    },
  • "account_memberships": {
    },
  • "work_samples": {
    },
  • "custom_field_values": {
    }
}
Fetch My Work Capacity
This endpoint returns a summary of a user's work capacity for a provided range of dates.


This endpoint returns structured User 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 users 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
end_date
required
string <date> 
The end date for calculating my work capacity in YYYY-MM-DD format (e.g. 2016-01-01).


 
start_date
required
string <date> 
The start date for calculating my work capacity in YYYY-MM-DD format (e.g. 2015-12-16).


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


    

  • account_membership (AccountMembership)
    • 

  • custom_field_values (CustomFieldValue) - The list of all the users custom field values that are readable by the current user.
    • 

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

  • role (Role)
    • 

  • skill_memberships (SkillMembership)
    • 

  • skills (Skill)
    • 

  • work_samples (WorkSample) - The list of all portfolio items belonging to this user.
    • 



 
optional_fields
Array of strings
Allows you to request one or more optional fields as an array.


Items Enum: "bio" "website" "city" "state" "country" "abbreviated_timezone" "last_site_activity" "classification"  
Responses 
200
A list of Users have been retrieved.


Response Schema: application/json
start_date
string <date> 
The start date for calculating my work capacity in YYYY-MM-DD format (e.g. 2012-09-27).


 
end_date
string <date> 
The end date for calculating my work capacity in YYYY-MM-DD format (e.g. 2012-09-27).


 
object
 
400
Bad Request


401
Unauthorized request


403
Forbidden request


404
Page Not Found


422
Unprocessable Entity


503
Service is unavailable


get/users/{id}/capacity
Request samples 
Response samples 
application/json
{
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "hours": {
    }
}
Reset Profile Photo
Delete the profile photo for the specified user.


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


Request 
path Parameters
id
required
integer
The ID of the Model.


 
Responses 
204
User has been deleted.


400
Bad Request


401
Unauthorized request


403
Forbidden request


404
Page Not Found


422
Unprocessable Entity


503
Service is unavailable


delete/users/{id}/profile_photo
Request samples 
Response samples 
application/json
{
  • "errors": [
    ]
}
Update Profile Photo
Update the profile photo for the specified user.


This endpoint returns structured User 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 users 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_membership (AccountMembership)
    • 

  • custom_field_values (CustomFieldValue) - The list of all the users custom field values that are readable by the current user.
    • 

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

  • role (Role)
    • 

  • skill_memberships (SkillMembership)
    • 

  • skills (Skill)
    • 

  • work_samples (WorkSample) - The list of all portfolio items belonging to this user.
    • 



 
optional_fields
Array of strings
Allows you to request one or more optional fields as an array.


Items Enum: "bio" "website" "city" "state" "country" "abbreviated_timezone" "last_site_activity" "classification"  
Request Body schema: application/json
object
 
profile_photo_attachment_file
required
string
The multipart/form-data encoded file contents. This is similar to the data attribute
of the Attachment field.


 
Responses 
200
User has been created.


Response Schema: application/json
count
integer <int32> 
 
object
 
Array of objects
 
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/users/{id}/profile_photo
Request samples 
application/json
{
  • "user": {
    }
}
Response samples 
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "users": {
    },
  • "external_references": {
    },
  • "roles": {
    },
  • "skills": {
    },
  • "skill_memberships": {
    },
  • "account_memberships": {
    },
  • "work_samples": {
    },
  • "custom_field_values": {
    }
}
➔ Next to Currencies