> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pilotstatus.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Labels

> Tag contacts and groups with tenant-scoped labels, via the dashboard or the send API.

## What Labels are

Labels tag destinations (E.164 phone or WhatsApp group `...@g.us`) at the **tenant** scope. Manage them under **Config → Labels** (`/labels`): create labels, import CSV/Excel, edit name/destination, copy a contact from one label to another.

## Public API — send message

On `POST /v1/messages/send`, optionally send:

```json theme={null}
"labels": ["vip", "customers"]
```

* Works with `destinationNumber` or `groupId`.
* Label processing is **asynchronous**: upserts Labels by name and associates the destination.
* The platform may try to fill the contact **display name** from WhatsApp data on the connected instance when still empty.

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
    -H "Content-Type: application/json" \
    -H "x-api-key: ps_your_key_here" \
    -d '{
      "destinationNumber": "+5511999999999",
      "templateId": "order_update",
      "labels": ["vip", "customers"]
    }'
  ```

  ```json Response (202) theme={null}
  {
    "id": "cmm04obm46zz0qv4ycjp8x6r2",
    "correlationId": "b3f1c2a4-9e7d-4c5a-8f21-0a1b2c3d4e5f",
    "status": "QUEUED",
    "createdAt": "2026-07-04T12:00:00.000Z",
    "origin": "api"
  }
  ```
</CodeGroup>

## Retention (PII) and API key

Retention is configured **per API key** (`retentionDays` in `/api-keys`).

* If `retentionDays > 0`: label–contact rows may store destination/metadata according to policy.
* If `retentionDays = 0`: when using the **public API** with `labels`, **Labels are still created**, but **contact rows are not persisted** (no PII storage for that linkage).

## UI import

* Phone columns: same as Messages (`number`, `destinationnumber`, `phone`, etc.).
* Optional group column: `groupId`, `group` — if it ends with `@g.us`, the row is treated as **GROUP**.
* If the same destination already exists in the label with an **empty name** and the import provides a name, the **name is updated**.

## Copy contact

Use **Copy to…** to duplicate the link into another label (dedup by destination; fills name on target when empty).