> ## Documentation Index
> Fetch the complete documentation index at: https://help.cloudtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Read and set user status with the API

> See what each CloudTalk user is doing right now, set a user Online or Idle with a note, and list the status types users can pick, from the v1 User status API.

The User status API at `https://api.cloudtalk.io/v1` shows what each user in your company is doing right now and lets you set the status they picked, the way an admin can in the Dashboard. Use it for a wallboard, to pause a user's queue calls from your workforce tool, or to set a note such as "Back at 14:00".

> [!NOTE]
>
> Requests authenticate with an API key, like the rest of the [CloudTalk API](https://help.cloudtalk.io/guides/authentication.md). The key acts as a company admin, and no header names a user. For live updates, subscribe to the [`user.status_changed`](https://help.cloudtalk.io/guides/webhooks/events/users#user-status_changed) webhook rather than polling.

## Quick start

**1. List the status types users can pick**

```bash theme={"system"}
curl -u ACCESS_KEY_ID:ACCESS_KEY_SECRET \
  https://api.cloudtalk.io/v1/user-status-types
```

Each type has an `id` and an `actAs` of `online`, `idle` or `offline`. You can set a type whose `actAs` is `online` or `idle`.

**2. Read who is available**

```bash theme={"system"}
curl -u ACCESS_KEY_ID:ACCESS_KEY_SECRET \
  "https://api.cloudtalk.io/v1/user-statuses?status=online"
```

**3. Set a user Idle with a note**

```bash theme={"system"}
curl -u ACCESS_KEY_ID:ACCESS_KEY_SECRET \
  -X PUT https://api.cloudtalk.io/v1/user-statuses/4207 \
  -H "Content-Type: application/json" \
  -d '{"statusTypeId": "9", "customText": "Back at 14:00"}'
```

The answer is the user's status after the change, with `source: "api"`.

## Operations

| Operation | Request |
| - | - |
| [List user statuses](https://help.cloudtalk.io/api-reference/user-status/list-user-statuses.md) | `GET /user-statuses` |
| [Get a user's status](https://help.cloudtalk.io/api-reference/user-status/get-a-users-status.md) | `GET /user-statuses/{userId}` |
| [Set a user's status](https://help.cloudtalk.io/api-reference/user-status/set-a-users-status.md) | `PUT /user-statuses/{userId}` |
| [List user status types](https://help.cloudtalk.io/api-reference/user-status/list-user-status-types.md) | `GET /user-status-types` |

[List user statuses](https://help.cloudtalk.io/api-reference/user-status/list-user-statuses.md) returns `{ "data": [...], "pagination": { "limit": 20, "next": "..." }, "requestId": "..." }`: pass `pagination.next` as `?cursor=` for the next page. The status types come in one response, `{ "data": [...], "requestId": "..." }`.

## How a status is worked out

Three inputs are checked in this order, and the first that applies wins:

1. Whether the user is signed in on any device. If not, `status` is `offline`.
2. Whether the user is on a call (`on_call`) or in after-call work (`after_call_work`).
3. The status type the user picked, through its `actAs`: `online`, `idle` or `offline`.

`status` shows the result. `statusType` and `customText` show what was picked, which is kept during calls and while the user is signed out.

## Setting a status

* `PUT` replaces the whole picked status. Leaving `customText` out, or sending `null`, clears the note.
* The user must be signed in on at least one device, otherwise `409 USER_STATUS.USER_NOT_SIGNED_IN`. Offline cannot be set: it follows the user's real connection (`422 USER_STATUS.OFFLINE_NOT_ALLOWED`).
* An Idle type pauses the user's queue calls and an Online type resumes them.
* If the user is on a call, `statusType` changes now and `status` stays `on_call` until the call ends.
* The change sends `user.status_changed`. Sending the same values again changes nothing and sends nothing.
* `source` becomes `api` and stays so until the user or an admin picks a status.
* The Phone and the mobile app show the change at once.

The [reference](https://help.cloudtalk.io/api-reference/user-status/set-a-users-status.md) lists every answer, and how the change shows on the user's Phone and mobile app.

## Errors

Requests are [rate limited](https://help.cloudtalk.io/guides/rate-limiting.md) per company. Over the limit you get `429` with `X-CloudTalkAPI-Limit`, `X-CloudTalkAPI-Remaining` and `X-CloudTalkAPI-ResetTime`, and no error body.

Errors from the service share one shape, `{ "error": { "code", "message", "target" }, "requestId" }`. Branch on `code`. A `401` comes from the gateway instead, as `{ "code", "message" }` with no `error` object. `message` is for people and can change. `target` names the field, parameter or header at fault when there is one. Quote `requestId` when you contact support: every answer also carries it in the `X-Transaction-ID` header. A user id that is malformed or belongs to another company gets `404 USER_STATUS.USER_NOT_FOUND`, and so does a user with no status activity on Get.


## Related topics

- [Set a user's status](https://help.cloudtalk.io/api-reference/user-status/set-a-users-status.md)
- [API reference](https://help.cloudtalk.io/api-reference/overview.md)
- [Changelog](https://help.cloudtalk.io/changelog.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.