---
title: "Create a new status"
description: "POST /statuses — Creates a contact status. text (max 20 characters) and color are required, description (max 33) is optional. Admin only. color must be one of the allowed palette values; the system id is…"
canonical_url: https://developer.onepagecrm.com/api/reference/statuses/post-statuses/
source: Markdown mirror of https://developer.onepagecrm.com/api/reference/statuses/post-statuses/
---

`POST /statuses`

Creates a contact status. text (max 20 characters) and color are required, description (max 33) is optional. Admin only. color must be one of the allowed palette values; the system id is server-assigned.

Resource: [Statuses](https://developer.onepagecrm.com/api/reference/statuses/) · [API Reference](https://developer.onepagecrm.com/api/reference/)

## Request

```bash
curl -X POST "https://app.onepagecrm.com/api/v3/statuses" \
  -u $user_id:$api_key \
  -H "Content-Type: application/json" \
  -d '{
    "id": "5aead4809007ba56ffca942e",
    "status": "prospect",
    "text": "Prospect",
    "description": "Actively selling to these people",
    "color": "f96600",
    "counts": 3,
    "total_count": 3,
    "action_stream_count": 2,
    "team_counts": [
      {
        "user_id": "5aba31e99007ba0f570c12f7",
        "counts": 4
      }
    ]
  }'
```

Authentication is HTTP Basic — `user_id` as username, `api_key` as password.
See https://developer.onepagecrm.com/api/authentication/.

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (bson-id) |  | ID of the status |
| `status` | string |  | Type of the status |
| `text` | string | yes | Display text of the status |
| `description` | string |  | Longer description of what the status is for |
| `color` | string (hex-color) | yes | The color of the status (six character hex value) |
| `counts` | integer (int32) |  | Number of contacts the (logged API) user owns, with the status |
| `total_count` | integer (int32) |  | Number of contacts the entire team owns, with the status |
| `action_stream_count` | integer (int32) |  | Number of contacts the (logged API) user has actions with, who also have the status |
| `team_counts` | array<object> |  | Number of contacts, with the status (for each team member) |

## Responses

### 201

Created

```json
{
  "status": 0,
  "message": "OK",
  "timestamp": 1528373119,
  "data": {
    "status": {
      "id": "5aead4809007ba56ffca942e",
      "status": "prospect",
      "text": "Prospect",
      "description": "Actively selling to these people",
      "color": "f96600",
      "counts": 3,
      "total_count": 3,
      "action_stream_count": 2,
      "team_counts": [
        {
          "user_id": "5aba31e99007ba0f570c12f7",
          "counts": 4
        }
      ]
    }
  }
}
```

Standard error responses: 400, 401, 403, 404, 409, 500 — shared across the API. See https://developer.onepagecrm.com/api/errors/.

## Related guides

- [Authentication](https://developer.onepagecrm.com/api/authentication/)
- [Errors](https://developer.onepagecrm.com/api/errors/)
- [Rate limits](https://developer.onepagecrm.com/api/rate-limits/)