# Subscription API - Insert

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

---

## Endpoint

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

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 subscription name. |
| `group` | string or integer | No | Group name or group ID to assign the subscription to. The group must be of type `subscription`. |
| `prefpage_access` | string | No | Preference page visibility: `"public"` (default) or `"private"`. Setting to `"private"` requires the private subscriptions feature. |
| `display_names` | object | No | Translated display labels keyed by ISO language code (e.g. `{ "en": "...", "fr": "..." }`). |
| `display_descriptions` | object | No | Translated descriptions keyed by ISO language code (e.g. `{ "en": "...", "fr": "..." }`). |

---

## Response

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

```json
{
  "success": true,
  "result_text": "Created",
  "result_data": {
    "id": "12",
    "external_id": "a1b2c3d4e5f6",
    "name": "Campus Weekly Newsletter",
    "group": "Student Communications",
    "prefpage_access": "public",
    "display_names": { "en": "Campus Weekly Newsletter", "fr": "" },
    "display_descriptions": { "en": "A weekly roundup of campus news and events.", "fr": "" }
  }
}
```

`result_data.id` is the Envoke subscription ID. Store this if you need to update, delete, or assign contacts to the subscription 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 `subscription`. |
| `'prefpage_access' must be 'public' or 'private'` | An unrecognised value was provided for `prefpage_access`. |
| `Setting 'prefpage_access' to 'private' requires the private subscriptions feature` | The account does not have the private subscriptions feature enabled. |

---

## Examples

### Create a basic subscription

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

### Create with a group

```bash
curl -X POST -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Alumni Quarterly", "group": "Alumni Relations"}' \
  "https://e1.envoke.com/v2/subscriptions"
```

### Create with translated display names and descriptions

```bash
curl -X POST -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Campus Weekly Newsletter",
    "group": "Student Communications",
    "display_names": {"en": "Campus Weekly Newsletter", "fr": "Bulletin hebdomadaire du campus"},
    "display_descriptions": {"en": "A weekly roundup of campus news and events.", "fr": "Un résumé hebdomadaire des nouvelles et événements du campus."}
  }' \
  "https://e1.envoke.com/v2/subscriptions"
```

---

*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).*