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

Account Memberships

Each user on an account will have an account membership that describes their relationship to the account. When you add a user to an account, create a new account_membership. When you remove a user from an account, delete their account_membership record.

Fetching a list of Account Memberships

You can request either GET /api/v1/account_memberships.json?only=5 or GET /api/v1/account_memberships/5.json. In both cases, default filters will be applied. Unless you provide the is_active:false filter, you won't receive account membership for inactive users, and will get a 404 status on the "show" route.

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

Request
query Parameters
by_full_name
string

Search account memberships by full name of the user.

by_user_id
integer <int32>

Only includes account membership for the specified user ID.

can_log_in
boolean

Return account memberships based on whether or not the member is allowed to login.

created_after
string <date-time>

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

created_before
string <date-time>

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

include
string

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

  • backup_approver_associations (BackupApproverAssociation) - Retrieves the backup approver associations for the user this account membership is for, which represent a backup time approver for a specific date range. The response will include backup_approver_association_ids, which references the data in the backup_approver_associations top-level key.
  • cost_rates (CostRate) - Retrieves all the cost rates in different currencies for the user this account membership is for. The response will include cost_rate_ids, which references the data in the cost_rates top-level key.
  • default_role (Role) - Retrieves the default role, if any, for this account membership. The response will include default_role_id, which references the data in the roles top-level key.
  • effective_workweek (Workweek) - Retrieves the workweek that is in effect today for the user this account membership is for. The response will include effective_workweek_id, which references the data in the workweeks top-level key.
  • future_billable_utilizations (BillableUtilization) - Retrieves the future billable utilizations for the user this account membership is for. The response will include future_billable_utilization_ids, which references the data in the billable_utilizations top-level key.
  • managees (User) - Retrieves the direct reports of the user this account membership is for. The response will include managee_ids, which references the data in the users top-level key.
  • manager (User) - Retrieves the manager of the user this account membership is for. The response will include manager_id, which references the data in the users top-level key.
  • possible_managees (User) - Retrieves a list of users who can become the direct reports of the user this account membership is for. The response will include possible_managee_ids, which references the data in the users top-level key.
  • possible_managers (User) - Retrieves a list of users who can be set as the manager of the user this account membership is for. The response will include possible_manager_ids, which references the data in the users top-level key.
  • skill_memberships (SkillMembership) - Retrieves the skill memberships for the user this account membership is for, which represent skills assigned to a user. The response will include skill_membership_ids, which references the data in the skill_memberships top-level key.
  • user (User) - Retrieves the user for this account membership. The response will include user_id, which references the data in the users top-level key.
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_active
boolean

Only includes users with an active membership (disabled_at is null).

only_inactive
boolean

Only includes users with an inactive membership (disabled_at is not null).

optional_fields
Array of strings

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

Items Value: "non_participant"
order
string
Default: "created_at:desc"

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

Valid values: bill_rate:asc, bill_rate:desc, cost_rate:asc, cost_rate:desc, created_at:asc, created_at:desc, full_name:asc, full_name:desc, permission:asc, permission:desc, role:asc, role:desc, updated_at:asc, and updated_at:desc.

page
integer <int32>
Default: 1
per_page
integer <int32> <= 200
Default: 20
search
string
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.

with_user_ids
string

Only includes account memberships for the specified user IDs. For example, '1,2,3'.

Request Body schema: application/json
required
object

Return account memberships with the requested skills and levels. { '91': [2, 3], '92':[1], 'ids':[91, 92, 93], 'operation': 'and' }.

ids
Array of integers <int32>

IDs of skills to be included.

operation
string

Use and or or to include account memberships with all or any of the skills.

Responses
200

A list of Account Memberships 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/account_memberships
Request samples
application/json
{
  • "with_skills": {
    }
}
Response samples
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "account_memberships": {
    },
  • "users": {
    },
  • "roles": {
    },
  • "workweeks": {
    },
  • "skill_memberships": {
    },
  • "backup_approver_associations": {
    },
  • "cost_rates": {
    },
  • "billable_utilizations": {
    }
}

Fetching a single Account Membership

This endpoint returns structured Account Membership 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 account_memberships 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.

  • backup_approver_associations (BackupApproverAssociation) - Retrieves the backup approver associations for the user this account membership is for, which represent a backup time approver for a specific date range. The response will include backup_approver_association_ids, which references the data in the backup_approver_associations top-level key.
  • cost_rates (CostRate) - Retrieves all the cost rates in different currencies for the user this account membership is for. The response will include cost_rate_ids, which references the data in the cost_rates top-level key.
  • default_role (Role) - Retrieves the default role, if any, for this account membership. The response will include default_role_id, which references the data in the roles top-level key.
  • effective_workweek (Workweek) - Retrieves the workweek that is in effect today for the user this account membership is for. The response will include effective_workweek_id, which references the data in the workweeks top-level key.
  • future_billable_utilizations (BillableUtilization) - Retrieves the future billable utilizations for the user this account membership is for. The response will include future_billable_utilization_ids, which references the data in the billable_utilizations top-level key.
  • managees (User) - Retrieves the direct reports of the user this account membership is for. The response will include managee_ids, which references the data in the users top-level key.
  • manager (User) - Retrieves the manager of the user this account membership is for. The response will include manager_id, which references the data in the users top-level key.
  • possible_managees (User) - Retrieves a list of users who can become the direct reports of the user this account membership is for. The response will include possible_managee_ids, which references the data in the users top-level key.
  • possible_managers (User) - Retrieves a list of users who can be set as the manager of the user this account membership is for. The response will include possible_manager_ids, which references the data in the users top-level key.
  • skill_memberships (SkillMembership) - Retrieves the skill memberships for the user this account membership is for, which represent skills assigned to a user. The response will include skill_membership_ids, which references the data in the skill_memberships top-level key.
  • user (User) - Retrieves the user for this account membership. The response will include user_id, which references the data in the users top-level key.
optional_fields
Array of strings

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

Items Value: "non_participant"
Responses
200

The Account Membership 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/account_memberships/{id}
Request samples 
Response samples 
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "account_memberships": {
    },
  • "users": {
    },
  • "roles": {
    },
  • "workweeks": {
    },
  • "skill_memberships": {
    },
  • "backup_approver_associations": {
    },
  • "cost_rates": {
    },
  • "billable_utilizations": {
    }
}
Updating an existing Account Membership
This endpoint returns structured Account Membership 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 account_memberships 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.


    

  • backup_approver_associations (BackupApproverAssociation) - Retrieves the backup approver associations for the user this account membership is for, which represent a backup time approver for a specific date range. The response will include backup_approver_association_ids, which references the data in the backup_approver_associations top-level key.
    • 

  • cost_rates (CostRate) - Retrieves all the cost rates in different currencies for the user this account membership is for. The response will include cost_rate_ids, which references the data in the cost_rates top-level key.
    • 

  • default_role (Role) - Retrieves the default role, if any, for this account membership. The response will include default_role_id, which references the data in the roles top-level key.
    • 

  • effective_workweek (Workweek) - Retrieves the workweek that is in effect today for the user this account membership is for. The response will include effective_workweek_id, which references the data in the workweeks top-level key.
    • 

  • future_billable_utilizations (BillableUtilization) - Retrieves the future billable utilizations for the user this account membership is for. The response will include future_billable_utilization_ids, which references the data in the billable_utilizations top-level key.
    • 

  • managees (User) - Retrieves the direct reports of the user this account membership is for. The response will include managee_ids, which references the data in the users top-level key.
    • 

  • manager (User) - Retrieves the manager of the user this account membership is for. The response will include manager_id, which references the data in the users top-level key.
    • 

  • possible_managees (User) - Retrieves a list of users who can become the direct reports of the user this account membership is for. The response will include possible_managee_ids, which references the data in the users top-level key.
    • 

  • possible_managers (User) - Retrieves a list of users who can be set as the manager of the user this account membership is for. The response will include possible_manager_ids, which references the data in the users top-level key.
    • 

  • skill_memberships (SkillMembership) - Retrieves the skill memberships for the user this account membership is for, which represent skills assigned to a user. The response will include skill_membership_ids, which references the data in the skill_memberships top-level key.
    • 

  • user (User) - Retrieves the user for this account membership. The response will include user_id, which references the data in the users top-level key.
    • 



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


Items Value: "non_participant"  
Request Body schema: application/json
required
object
 
bill_rate_in_cents
integer <int32> 
The default billing rate, in cents, for the user in a workspace on this account.


 
cost_rate_in_cents
integer <int32> 
The default cost rate, in cents, for the user in a workspace on this account.


 
default_role_id
integer <int32> 
The internal ID for the role of this user on this account.


 
permission
string
The user's permission level on the account. Valid values are 'administrator', 'reports_viewer', 'reports_viewer_with_cost', 'project_lead', 'project_creator', 'punch_clock', 'external_collaborator' or 'collaborator'.


 
billability_target
integer <int32> 
Value for setting the user's billability target.


 
default_read_only
boolean
Whether the user is always read-only in workspaces.


 
manager_id
integer <int32> 
The User ID of the user's manager.


 
manager_can_approve
boolean
Whether the user's named manager can approve their time and expenses.


 
should_show_alert_on_timesheet_submission
boolean
Show an alert on a user's timesheet.


 
change_role_option
string
Select 'update_with_new_role', 'add_another_role', or 'keep_existing_role'. If no option is selected another role will be added.


 
enforce_workweek_minimum_on_timesheet_submission
boolean
If true, the user is required to submit timesheets equal to or greater than their workweek hours.


 
enforce_workweek_maximum_on_timesheet_submission
boolean
If true, the user is required to submit timesheets equal to or less than their workweek hours.


 
Responses 
200
Account Membership 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/account_memberships/{id}
Request samples 
application/json
{
  • "account_membership": {
    }
}
Response samples 
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "account_memberships": {
    },
  • "users": {
    },
  • "roles": {
    },
  • "workweeks": {
    },
  • "skill_memberships": {
    },
  • "backup_approver_associations": {
    },
  • "cost_rates": {
    },
  • "billable_utilizations": {
    }
}
Remove a user from an account
This removes the member from your account and places them on a separate Kantata OX account. It is important
to know that the account owner cannot be removed.


WARNING: Since the removed member gets their on own separate Kantata OX account,
they will remain on existing projects but will be View Only and no
longer be able to create projects in your account.


We suggest disabling an account member over removing them since it revokes their ability to access
your account and they will no longer have access to projects for which they were contributing.


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
Account Membership has been deleted.


400
Bad Request


401
Unauthorized request


403
Forbidden request


404
Page Not Found


422
Unprocessable Entity


503
Service is unavailable


delete/account_memberships/{id}
Request samples 
Response samples 
application/json
{
  • "errors": [
    ]
}
Make a user inactive
Disables a user in an account


This endpoint returns structured Account Membership 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 account_memberships 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.


    

  • backup_approver_associations (BackupApproverAssociation) - Retrieves the backup approver associations for the user this account membership is for, which represent a backup time approver for a specific date range. The response will include backup_approver_association_ids, which references the data in the backup_approver_associations top-level key.
    • 

  • cost_rates (CostRate) - Retrieves all the cost rates in different currencies for the user this account membership is for. The response will include cost_rate_ids, which references the data in the cost_rates top-level key.
    • 

  • default_role (Role) - Retrieves the default role, if any, for this account membership. The response will include default_role_id, which references the data in the roles top-level key.
    • 

  • effective_workweek (Workweek) - Retrieves the workweek that is in effect today for the user this account membership is for. The response will include effective_workweek_id, which references the data in the workweeks top-level key.
    • 

  • future_billable_utilizations (BillableUtilization) - Retrieves the future billable utilizations for the user this account membership is for. The response will include future_billable_utilization_ids, which references the data in the billable_utilizations top-level key.
    • 

  • managees (User) - Retrieves the direct reports of the user this account membership is for. The response will include managee_ids, which references the data in the users top-level key.
    • 

  • manager (User) - Retrieves the manager of the user this account membership is for. The response will include manager_id, which references the data in the users top-level key.
    • 

  • possible_managees (User) - Retrieves a list of users who can become the direct reports of the user this account membership is for. The response will include possible_managee_ids, which references the data in the users top-level key.
    • 

  • possible_managers (User) - Retrieves a list of users who can be set as the manager of the user this account membership is for. The response will include possible_manager_ids, which references the data in the users top-level key.
    • 

  • skill_memberships (SkillMembership) - Retrieves the skill memberships for the user this account membership is for, which represent skills assigned to a user. The response will include skill_membership_ids, which references the data in the skill_memberships top-level key.
    • 

  • user (User) - Retrieves the user for this account membership. The response will include user_id, which references the data in the users top-level key.
    • 



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


Items Value: "non_participant"  
Responses 
200
Account Membership 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/account_memberships/{id}/disable
Request samples 
Response samples 
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "account_memberships": {
    },
  • "users": {
    },
  • "roles": {
    },
  • "workweeks": {
    },
  • "skill_memberships": {
    },
  • "backup_approver_associations": {
    },
  • "cost_rates": {
    },
  • "billable_utilizations": {
    }
}
Make a user active
Enables a user in an account


This endpoint returns structured Account Membership 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 account_memberships 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.


    

  • backup_approver_associations (BackupApproverAssociation) - Retrieves the backup approver associations for the user this account membership is for, which represent a backup time approver for a specific date range. The response will include backup_approver_association_ids, which references the data in the backup_approver_associations top-level key.
    • 

  • cost_rates (CostRate) - Retrieves all the cost rates in different currencies for the user this account membership is for. The response will include cost_rate_ids, which references the data in the cost_rates top-level key.
    • 

  • default_role (Role) - Retrieves the default role, if any, for this account membership. The response will include default_role_id, which references the data in the roles top-level key.
    • 

  • effective_workweek (Workweek) - Retrieves the workweek that is in effect today for the user this account membership is for. The response will include effective_workweek_id, which references the data in the workweeks top-level key.
    • 

  • future_billable_utilizations (BillableUtilization) - Retrieves the future billable utilizations for the user this account membership is for. The response will include future_billable_utilization_ids, which references the data in the billable_utilizations top-level key.
    • 

  • managees (User) - Retrieves the direct reports of the user this account membership is for. The response will include managee_ids, which references the data in the users top-level key.
    • 

  • manager (User) - Retrieves the manager of the user this account membership is for. The response will include manager_id, which references the data in the users top-level key.
    • 

  • possible_managees (User) - Retrieves a list of users who can become the direct reports of the user this account membership is for. The response will include possible_managee_ids, which references the data in the users top-level key.
    • 

  • possible_managers (User) - Retrieves a list of users who can be set as the manager of the user this account membership is for. The response will include possible_manager_ids, which references the data in the users top-level key.
    • 

  • skill_memberships (SkillMembership) - Retrieves the skill memberships for the user this account membership is for, which represent skills assigned to a user. The response will include skill_membership_ids, which references the data in the skill_memberships top-level key.
    • 

  • user (User) - Retrieves the user for this account membership. The response will include user_id, which references the data in the users top-level key.
    • 



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


Items Value: "non_participant"  
Responses 
200
Account Membership 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/account_memberships/{id}/enable
Request samples 
Response samples 
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "account_memberships": {
    },
  • "users": {
    },
  • "roles": {
    },
  • "workweeks": {
    },
  • "skill_memberships": {
    },
  • "backup_approver_associations": {
    },
  • "cost_rates": {
    },
  • "billable_utilizations": {
    }
}
➔ Next to Backup Approver Associations