Users API

A user object creates and acts on other objects. When multiple user records are associated with an individual, due to differences in email or variations in a name, for example, user records can be merged under a single apex user record. Use this endpoint to retrieve and make changes to apex user records in Flow.

This endpoint has the following methods:

GET /users/: Get a list of apex users and their associated information.
POST /users/bulk_delete: Delete or hide apex users from a list of apex user IDs.
POST /users/bulk_toggle_hidden_users: Hide and unhide apex users from a list of apex user IDs.
PATCH /users/bulk_toggle_hidden_users: Hide and unhide apex users from a list of apex user IDs.
POST /users/bulk_unmerge: Unmerge all user aliases from a list of apex users by ID.
GET /users/{id}: Get all information associated with an apex user by ID.
PATCH /users/{id}: Update an apex user’s information by ID.
POST /users/{id}/merge: Merge a list of user aliases by ID into an apex user by ID.

Parameters

Name	Type	Description

Name	Type	Description
`id`	double	User's unique identifier.
`id__in`	double	Multiple user_id values separated by commas.
`name`	string	User’s name.
`name__icontains`	string	User's name contains a specific string.
`name__startswith`	string	User's name starts with a specific string.
`email`	string	User's email address.
`email__icontains`	string	Email contains a specific string.
`email__startswith`	string	Email starts with a specific string.
`hidden_from_reports`	boolean	Returns true to indicate the user's record is excluded.
`org_id`	double	Org's unique identifier
`created_at`	double	Date and time the user record was created.
`created_at__gt`	string	Records greater than date or datetime (yyyy-mm-dd hh:mm:ss).
`created_at__gte`	string	Records greater than or equal to date or datetime (yyyy-mm-dd hh:mm:ss).
`created_at__lt`	string	Records less than the date or datetime (yyyy-mm-dd hh:mm:ss).
`created_at__lte`	string	Records less than or equal to date or datetime (yyyy-mm-dd hh:mm:ss).
`teams`	string	An array of TEAMS associated with the User. Filter-traversable object.
`has_login`	boolean	Returns true if the user has a login.
`pending_invitation`	boolean	Returns true if the user has been invited to the account but has not signed in.
`alias_count`	double	Alias count.
`alias_count__gt`	double	Alias count is greater than the input number.
`alias_count__gte`	double	Alias count is greater than or equal the input number.
`alias_count__lt`	double	Alias count is less than the input number.
`alias_count__lte`	double	Alias count is less than or equal to the input number.
`last_activity_at`	string	User's last activity at date or datetime (yyyy-mm-dd hh:mm:ss)
`last_activity_at__gt`	string	User's last activity greater than date or datetime (yyyy-mm-dd hh:mm:ss)
`last_activity_at__gte`	string	User's last activity greater than or equal to date or datetime (yyyy-mm-dd hh:mm:ss)
`last_activity_at__lt`	string	User's last activity less than date or datetime (yyyy-mm-dd hh:mm:ss)
`last_activity_at__lte`	string	User's last activity less than or equal to date or datetime (yyyy-mm-dd hh:mm:ss)
`first_activity_at`	string	User's first activity at date or datetime (yyyy-mm-dd hh:mm:ss)
`first_activity_at__gt`	string	User's first activity greater than date or datetime (yyyy-mm-dd hh:mm:ss)
`first_activity_at__gte`	string	User's first activity greater than or equal to date or datetime (yyyy-mm-dd hh:mm:ss)
`first_activity_at__lt`	string	User's first activity less than date or datetime (yyyy-mm-dd hh:mm:ss)
`first_activity_at__lte`	string	User's first activity less than or equal to date or datetime (yyyy-mm-dd hh:mm:ss)
`avatar URL`	string	External URL for the user's avatar image.
`avatar_exists`	boolean	Returns true if an avatar exists for a user.
`invitation_id`	string	Unique identifier for invitation.
`login_enabled`	boolean	Returns true if the user's login is enabled.
`is_saml`	boolean	Returns true if the user's login is controlled via SAML Integration.
`ordering`	string	Valid ordering fields are id, name, email, hidden_from_reports, has_login, and alias_count.
`search`	string	A search term

Example response

{
      "id": 86097,
      "name": "Stephanie Ventura",
      "email": "sventura@example.com",
      "hidden_from_reports": false,
      "org_id": 1234,
      "created_at": "2023-03-19T12:07:31.909614",
      "teams": [],
      "has_login": false,
      "pending_invitation": false,
      "alias_count": 1,
      "last_activity_at": "2024-08-28T16:04:09",
      "first_activity_at": "2014-11-11T12:26:34",
      "avatar_url": "https://secure.gravatar.com/avatar/example.jpg",
      "avatar_exists": false,
      "invitation_id": null,
      "login_enabled": false,
      "is_saml": false,
      "is_group_member": false,
      "hidden": false,
      "hidden_by": null,
      "hidden_at": "2020-11-17T04:07:57.948366",
      "login": null
    },

User attribute endpoints

Get user attributes

Users who have the User attributes feature active will receive user attributes in their responses for the following endpoints:

/v3/customer/core/users/{id}/
/v3/customer/core/users/

Example response

{
  <along with all the existing ones>
  "user_metadata": {
    "Timezone": "John/Smith",
    "Employment Type": "Contractor",
    "Seniority Level": "Senior",
    "Engineer Type": "Fullstack",
    "Programming Language": "Python"
  }
}

With the list of apex users endpoint (/v3/customer/core/users/), you can filter users by attribute values using the following query parameter format:

?user_metadata__text__<attribute_name>=<value>.

Example:

For the Programming language attribute:
GET - /api/v3/org/{org}/apex/users/?user_metadata__text__Programming_Language=python

For the Hire date attribute:
GET - /api/v3/org/{org}/apex/users/?user_metadata__date__Hire_Date=2024-01-15

When using the user attribute filter, ensure the attribute name exactly matches the database entry and that you replace any spaces between attribute names with an underscore (_).

Update user attributes

In addition, with the /v3/customer/core/users/{id}/ endpoint, you can also update user attribute values.

Method: PATCH

Example inputs:

{
  <along with all the existing ones>
  "user_attributes": [
    {
      "attribute_id": 948,
      "values": ["Full-Time Employee", "Contractor"]
    }
  ]
}