# Assign tag

Assign a tag to an email address or phone number.

Source: https://statusdashboard.com/docs/api/subscriptions/segments/registry-create

`POST /app/segments/registry`

Creates a registry assignment. Does not create or modify dashboard subscribers. A contact may be tagged before, during, or after subscribing.

The request body is a **discriminated union** on `channel`. Each assignment requires a **display name** — a human-readable label for the registry (e.g. `Jane Doe, CEO`). It is for admin display only; matching and DELETE still use the normalized email or phone.

Phone numbers are validated with [libphonenumber-js](https://www.npmjs.com/package/libphonenumber-js) and stored in **E.164** format (e.g. `+14155552671`).

***

## Request
See [API Basics](/docs/api) for required headers.

### Body (email)
| Field         | Type   | Required | Description                             |
| ------------- | ------ | -------- | --------------------------------------- |
| `channel`     | string | Yes      | Must be `email`.                        |
| `tagId`       | uuid   | Yes      | Existing tag UUID.                      |
| `displayName` | string | Yes      | Human-readable label. 1–100 characters. |
| `email`       | string | Yes      | Valid email address. Stored lowercased. |

### Body (SMS)
| Field         | Type   | Required | Description                               |
| ------------- | ------ | -------- | ----------------------------------------- |
| `channel`     | string | Yes      | Must be `sms`.                            |
| `tagId`       | uuid   | Yes      | Existing tag UUID.                        |
| `displayName` | string | Yes      | Human-readable label. 1–100 characters.   |
| `phone`       | string | Yes      | E.164 phone number (e.g. `+14155552671`). |

### Body (WhatsApp)
| Field         | Type   | Required | Description                                        |
| ------------- | ------ | -------- | -------------------------------------------------- |
| `channel`     | string | Yes      | Must be `whatsapp`.                                |
| `tagId`       | uuid   | Yes      | Existing tag UUID.                                 |
| `displayName` | string | Yes      | Human-readable label. 1–100 characters.            |
| `phone`       | string | Yes      | E.164 phone number (same validation rules as SMS). |

The same E.164 number may be assigned to the same tag independently for **SMS** and **WhatsApp** — each channel is stored as a separate registry row.

***

## Sample request (email)
```bash
curl -X POST https://api.statusdashboard.com/app/segments/registry \
  -H "Authorization: Bearer bcf847abf5c6:def456" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "tagId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "displayName": "Jane Doe, CEO",
    "email": "ceo@acme.com"
  }'
```

## Sample request (SMS)
```bash
curl -X POST https://api.statusdashboard.com/app/segments/registry \
  -H "Authorization: Bearer bcf847abf5c6:def456" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "tagId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "displayName": "Jane Doe, CEO",
    "phone": "+14155552671"
  }'
```

## Sample request (WhatsApp)
```bash
curl -X POST https://api.statusdashboard.com/app/segments/registry \
  -H "Authorization: Bearer bcf847abf5c6:def456" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "tagId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "displayName": "Jane Doe, CEO",
    "phone": "+14155552671"
  }'
```

## Sample response
**Status: `201 Created`**

```json
{
  "entry": {
    "tagId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tagName": "Executive",
    "channel": "email",
    "displayName": "Jane Doe, CEO",
    "contact": "ceo@acme.com",
    "normalizedContact": "ceo@acme.com",
    "createdAt": "2026-06-02T09:00:00.000Z"
  }
}
```

SMS and WhatsApp entries return `contact` as a formatted display value and `normalizedContact` as E.164 (e.g. `+14155552671`).

***

## Error responses
| Status | When                                                                  |
| ------ | --------------------------------------------------------------------- |
| `400`  | Validation error, invalid phone number, or tag not found.             |
| `403`  | Not admin, feature not enabled, or `subscribersPerTag` limit reached. |
| `409`  | Contact is already assigned to this tag.                              |