---
title: "Users API"
canonical: "https://support.appfire.com/space/FD/1802404091/Users%20API"
format: markdown
---
> Macro (aura-html)

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 |
| --- | --- | --- |
| `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

```json
{
      "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 parameter

### Get user attributes

Users can also receive [user attributes](https://appfire.atlassian.net/wiki/spaces/FD/pages/3045031988) in their responses for the following endpoints:

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

Example response

```json
{
  <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 query for **Programming Language** (attribute name) and **Python** (attribute value):  
GET - `/api/v3/org/{org}/apex/users/?user_metadata__text__Programming_Language=python`

- Example query for **Hire Date** (attribute name) and **01/15/2024** (attribute value):  
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 (`_`).
> 📝 
> 📝 Attribute names and their value names can be found in **Settings** > **User Management** > **[User attributes](https://appfire.atlassian.net/wiki/spaces/FD/pages/3044311307)** (the **Manage Users & Teams** permission is required).

### Update user attributes

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

Example inputs:

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