# 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. Endpoint: GET /users Version: 1.0.0 ## Query parameters: - `account_id` (integer) 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) 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 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). - `by_email_address` (string) Only includes users whose email address exactly matches the specified address. - `by_email_addresses` (string) Return only users whose email addresses exactly match the specified email addresses. You can provide a list of comma-separated email addresses as a query parameter in the request URL or provide an array of email addresses in the request body. You can specify up to 200 email addresses. - `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) 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. The datetime must be in ISO 8601 format. - `created_before` (string) Filter for records created before a specified datetime. The datetime must be in ISO 8601 format. - `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) 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. - `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) - Retrieves the account membership of the user, which represents the relationship of a user to an account. The response will include account_membership_id, which references the data in the account_memberships top-level key. - custom_field_values (CustomFieldValue) - Retrieves the user's custom field values that are viewable for the current user. 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. - manager (User) - Retrieves the user's manager. The response will include manager_id, which references the data in the users top-level key. - role (Role) - Retrieves the user's account role. The response will include role_id, which references the data in the roles top-level key. - skill_memberships (SkillMembership) - Retrieves the skill memberships of the user, which represent skills that have been assigned to a user. The response will include skill_membership_ids, which references the data in the skill_memberships top-level key. The skill_memberships data will include the user's proficiency level (for skills which can be assigned proficiency levels). - skills (Skill) - Retrieves the user's skills. The response will include skill_ids, which references the data in the skills top-level key. The skills data will include the skill description and category ID. - work_samples (WorkSample) - Retrieves the user's portfolio items. The response will include work_sample_ids, which references the data in the work_samples top-level key. - `is_project_lead` (boolean) Only include users who have account level permission of project lead or above. - `managers` (boolean) Only include users who are managers. - `matching` (string) - `not_assigned_to` (integer) Only includes users who are not assigned to a task with specified ID. - `not_following` (integer) 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) 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) 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) Allows you to request one or more optional fields as an array. Enum: "bio", "website", "city", "state", "country", "abbreviated_timezone", "last_site_activity", "classification" - `order` (string) 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) - `participant_in` (integer) Only includes users participating in a project with a specified ID. - `per_page` (integer) - `potential_followers_for_story` (integer) 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) 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. The datetime must be in ISO 8601 format. - `updated_before` (string) Filter for records updated before a specified datetime. The datetime must be in ISO 8601 format. - `with_created_estimates` (boolean) Only include users who have created an estimate. - `with_organizations` (boolean) Only includes users that have an organization (true) or only includes users that do not have an organization (false). - `with_skills` (string) Only includes users with a set of skills at the specified levels (Format: '{'skill_id':[level,level],'skill_id':[level],'operation':''}'). - `with_users` (array) 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) Exclude users for the provided IDs (Format: 'id,id,id'). - `write_access_in` (integer) Only includes users who are participating in a project with a specified ID, and are not read-only in the project. ## Response 200 fields (application/json): - `count` (integer) - `meta` (object) - `meta.count` (integer) - `meta.page_count` (integer) - `meta.page_number` (integer) - `meta.page_size` (integer) - `results` (array) - `results.key` (string) - `results.id` (string) - `users` (object) - `external_references` (object) - `roles` (object) - `skills` (object) - `skill_memberships` (object) - `account_memberships` (object) - `work_samples` (object) - `custom_field_values` (object) ## Response 400 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string)