# Tag API - Insert

Use this endpoint to create a new tag in your account.

---

## Endpoint

```
POST https://e1.envoke.com/v2/tags
```

Authentication is via HTTP Basic Auth using your API ID and API Key. The request body must be JSON.

---

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | Yes | The tag name. |
| `group` | string or integer | No | Group name or group ID to assign the tag to. The group must be of type `interest`. |
| `description` | string | No | Internal description of the tag. |
| `display_names` | object | No | Translated display labels keyed by ISO language code (e.g. `{ "en": "...", "fr": "..." }`). |

---

## Response

On success, the API returns the newly created tag object:

```json
{
  "success": true,
  "result_text": "Created",
  "result_data": {
    "id": "42",
    "external_id": "a1b2c3d4e5f6",
    "name": "Newsletter Subscribers",
    "group": "Engagement",
    "description": "Contacts who opted in to the monthly newsletter",
    "display_names": { "en": "Newsletter" }
  }
}
```

`result_data.id` is the Envoke tag ID. Store this if you need to update, delete, or assign contacts to the tag later.

---

## Validation Errors

```json
{
  "success": false,
  "result_text": "Validation failed, see 'result_data' -> 'errors'",
  "result_data": {
    "errors": [
      "The field 'name' is required"
    ]
  }
}
```

Common validation errors:

| Error | Cause |
|---|---|
| `Request body may not be empty` | No JSON body was provided. |
| `The field 'name' is required` | `name` was missing or blank. |
| `Invalid 'group': '{value}'` | The group name or ID was not found, or is not of type `interest`. |

---

## Examples

### Create a basic tag

```bash
curl -X POST -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Newsletter Subscribers"}' \
  "https://e1.envoke.com/v2/tags"
```

### Create with a group and description

```bash
curl -X POST -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Annual Conference Attendees", "group": "Events", "description": "Members who attend our annual conference"}' \
  "https://e1.envoke.com/v2/tags"
```

### Create with translated display names

```bash
curl -X POST -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Newsletter Subscribers", "display_names": {"en": "Newsletter", "fr": "Infolettre"}}' \
  "https://e1.envoke.com/v2/tags"
```

---

*Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.*

*Full reference, OpenAPI description, and Postman collection: [developers.envoke.com](https://developers.envoke.com).*