# Create a new marketing campaign

`POST /api/configuration/consent/marketing-campaigns`

- **Products:** Operator (`FOH`)
- **Features:** Front of House Generic Access (`FOHGENERIC`)

HTML version: [Create a new marketing campaign](https://support.gladstonesoftware.cloud/reference/configuration/create-a-new-marketing-campaign)

## Overview

Creates a marketing campaign — a named purpose that members can grant or refuse consent for, covering promotional communications. Consent is recorded per member as a campaign and channel pair, so you also need at least one [communication channel](create-a-new-communication-channel.md).

**A successful call answers `201` with the generated campaign identifier as the response body.** You cannot choose the identifier; it is derived from `name` with random digits appended, so it differs on every call.

**Campaign names must be unique across marketing and data-processing campaigns together.** The name check covers both kinds, so a marketing campaign called `Newsletter` blocks a data-processing campaign of the same name, and vice versa. A clash returns `400`, not `409`.

Because the identifier is generated and the name is checked for uniqueness, a retry after a timeout is safe: if the first attempt succeeded, the retry fails with the duplicate-name `400` rather than creating a second campaign.

One side effect to plan for: on success, consent records for existing members are created against the new campaign asynchronously. Their outcome is not reported, so member consent may take a moment to appear and a failure there will not fail this call.

## Endpoint

`POST {base_url}/api/configuration/consent/marketing-campaigns`

`{base_url}` is the environment URL issued to your integration. See [Authenticating with Gladstone APIs](../../guides/authenticating-with-gladstone-apis.md).

## Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | The campaign name shown to members when they set their preferences. Maximum 50 characters, and it must be unique across **both** marketing and data-processing campaigns — a clash returns `400` with `AgencyName {name} or Agency {id} already exists`. It also seeds the generated identifier: the name is upper-cased, spaces are stripped, the first characters form a prefix, and an underscore plus random digits are appended. Although the field is not validated as required, omitting it is not safe — the call fails with `500`. Single-character names fail the same way. |
| `description` | string | No | Longer explanatory text about what members are consenting to, shown alongside the name. Maximum 1024 characters. Omit it, or send null, to store no description. |
| `expiryDate` | string (date-time) | No | When consent given for this campaign lapses, as an ISO 8601 date-time. It is rejected with `400` if it falls in the past. Omit it, or send null, for a campaign whose consent does not expire. |
| `isActive` | boolean | No | Whether the campaign is offered to members for consent straight away. Defaults to `false` when omitted, so send `true` explicitly if the campaign should be live on creation — a campaign created inactive exists but is not presented for consent. |

## Sample request

```bash title="cURL"
curl -X POST '{base_url}/api/configuration/consent/marketing-campaigns' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "description": "string",
  "expiryDate": "2026-08-14T19:00:00Z",
  "isActive": true
}'
```

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `400` | Bad request | `name` is longer than 50 characters, `description` is longer than 1024, or `expiryDate` is in the past. The body is a validation error object keyed by field name. |
| `400` | Bad request | A campaign — marketing **or** data-processing — already uses this name: `AgencyName {name} or Agency {id} already exists`. |
| `409` | Conflict | The entry clashes with one that already exists — `This entry already exists in the database`. |
| `500` | Internal server error | `name` was omitted, was null, or was a single character, because no identifier can be generated from it. Also any other unexpected server-side failure. The body is empty. |