> For the complete documentation index, see [llms.txt](https://help.botpenguin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.botpenguin.com/api-documentation/contacts-and-chats-apis/put-update-user-status.md).

# PUT — Update User Status

### Overview

| Property          | Details                                                   |
| ----------------- | --------------------------------------------------------- |
| **Method**        | `PUT`                                                     |
| **Endpoint**      | `https://api.v7.botpenguin.com/inbox/users/status-update` |
| **Base URL**      | `https://api.v7.botpenguin.com`                           |
| **API Version**   | v7                                                        |
| **Auth Required** | Yes — Bearer Token                                        |
| **Content-Type**  | `application/json`                                        |

***

### Authentication

| Header          | Required | Value                   |
| --------------- | -------- | ----------------------- |
| `Authorization` | ✅ Yes    | `Bearer [MASKED_TOKEN]` |
| `authtype`      | ✅ Yes    | `Key`                   |

***

### How to Get a User ID

User IDs are found in the BotPenguin Inbox:

1. Go to Inbox in your BotPenguin dashboard.
2. Open the contact whose ID you need.
3. Click the three-dot menu (⋮) on the contact.
4. Select Copy User ID.

{% hint style="warning" icon="triangle-exclamation" %}
**Note:** `subscriberIds` is not supported by this endpoint. Pass User IDs only in the `ids` field.
{% endhint %}

***

### Request

#### Headers

| Header          | Required | Value                   |
| --------------- | -------- | ----------------------- |
| `Authorization` | ✅ Yes    | `Bearer [MASKED_TOKEN]` |
| `authtype`      | ✅ Yes    | `Key`                   |
| `Content-Type`  | ✅ Yes    | `application/json`      |

***

#### Request Body

```json
{
  "ids": ["640f472d173951357f08edee"],
  "status": "DELETED"
}
```

**Body Fields**

| Field    | Type     | Required | Description                                                                               |
| -------- | -------- | -------- | ----------------------------------------------------------------------------------------- |
| `ids`    | `array`  | ✅ Yes    | Array of User IDs to update. Obtain from Inbox → contact → three-dot menu → Copy User ID. |
| `status` | `string` | ✅ Yes    | New status to apply. Accepted value: `DELETED`.                                           |

***

#### Example Request

```bash
curl 'https://api.v7.botpenguin.com/inbox/users/status-update' \
  -X PUT \
  -H 'Authorization: Bearer [MASKED_TOKEN]' \
  -H 'authtype: Key' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "ids": ["640f472d173951357f08edee"],
    "status": "DELETED"
  }'
```

***

### Response

#### Success — `200 OK`

```json
{
  "success": true,
  "message": "",
  "code": 200
}
```

**Response Fields**

| Field     | Type      | Description                                           |
| --------- | --------- | ----------------------------------------------------- |
| `success` | `boolean` | `true` if the status update was applied successfully. |
| `message` | `string`  | Status message. Empty string on success.              |
| `code`    | `number`  | HTTP status code echo. `200` on success.              |

***

### HTTP Status Codes

| Code  | Status                | Meaning                                                |
| ----- | --------------------- | ------------------------------------------------------ |
| `200` | OK                    | Status updated successfully.                           |
| `400` | Bad Request           | Malformed request body or missing required fields.     |
| `401` | Unauthorized          | Bearer token is missing, invalid, or expired.          |
| `404` | Not Found             | One or more User IDs not found.                        |
| `429` | Too Many Requests     | Rate limit exceeded. Retry after the indicated window. |
| `500` | Internal Server Error | Server-side error. Contact support if it persists.     |

***

### Error Handling

All errors return a consistent structure:

```json
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Bearer token is invalid or has expired.",
    "statusCode": 401
  }
}
```

***

### Rate Limits

This endpoint is limited to **100 requests per minute** per token, across all plans. Exceeding this returns `429 Too Many Requests`. Use the `Retry-After` response header (in seconds) to schedule your retry.

***

*For questions or issues, contact* [*support@botpenguin.com*](mailto:support@botpenguin.com)