Create a new campaign. Campaigns measure the impact of a change — promotion, layout shift, staff schedule — by comparing a **test period** against a **control period** across one or more locations.

> **Date format:** campaign endpoints (`testPeriod`, `controlPeriod`) require **full ISO 8601 with timezone**, e.g. `2024-04-14T10:00:00.000Z`. Date-only strings are rejected.

## Body parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | Display name |
| `metric` | object | yes | `{ key, display }` plus optional `type`, `unitType`. `key` is the metric identifier (e.g. `entries`); `display` is the UI label |
| `campaignUplift` | number | yes | Expected uplift as a **proportion** (e.g. `0.1` = 10%), not a percent |
| `taxonomies` | string\[\] | yes | Array of taxonomy path strings (may be `[]`) |
| `lineTaxonomies` | string\[\] | yes | Array of taxonomy path strings (may be `[]`) |
| `testLocations` | string\[\] | yes | Array of location IDs to include in the test group |
| `testPeriod` | object | yes | See **Period shape** below |
| `controlPeriod` | object | no | Same shape as `testPeriod`. When present, `controlPeriod.active: boolean` is required |
| `selectedBreakdowns` | object\[\] | yes | Array of `{ key, values }` objects — see **selectedBreakdowns** below |
| `description` | string | no | Max 1000 characters |
| `controlLocations` | string\[\] | no | Array of location IDs for the control group |

### Period shape (`testPeriod` / `controlPeriod`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `selectedPreset` | string | yes | Opaque label (e.g. "custom", "last-30-days"). Validated only as a string — not against a closed list |
| `selectedDates` | `{ start, end }` | yes | ISO 8601 timestamps with timezone |
| `customPeriodDates` | `{ start, end }` | no | Optional alongside `selectedDates` |
| `active` | boolean | yes (control only) | Required on `controlPeriod` |

### Taxonomies and line taxonomies

`taxonomies` is an array of zone-path strings (e.g. `Service:Checkout`, `Products:Clothing`) the campaign should track on area-based metrics. `lineTaxonomies` does the same for line-based metrics (entries, passers-by, capture rate, etc.). Both arrays may be empty (`[]`) for location-wide metrics that don’t filter by zone.

These values map onto the zones and lines you’ve configured for each recording. To enumerate what’s available for your locations, query: Area definitions and Line definitions. The full list of metric routes is in the Metrics API overview.

### `selectedBreakdowns`

An array of `{ key, values }` objects — **not** a flat string array.

| `key` | Valid `values` |
| --- | --- |
| `"ages"` | `"0-15"`, `"16-24"`, `"25-34"`, `"35-44"`, `"45-54"`, `"55-64"`, `"65-100"` |
| `"genders"` | `"male"`, `"female"` |
| `"roles"` | `"customer"`, `"staff"`, `"customer-customer"`, `"customer-staff"`, `"staff-staff"` |
| `""` | `"all visitors"` — the “all visitors combined” form |

## Example request

```
POST https://api.auravisionlabs.com/v1/campaign
Authorization: Bearer <your_token>
Content-Type: application/json
```

```
{
  "name": "Summer Promotion",
  "metric": { "key": "entries", "display": "Entries" },
  "campaignUplift": 0.1,
  "taxonomies": [],
  "lineTaxonomies": [],
  "testLocations": ["64a1b2c3d4e5f6a7b8c9d0e3"],
  "testPeriod": {
    "selectedPreset": "custom",
    "selectedDates": {
      "start": "2024-06-01T00:00:00.000Z",
      "end":   "2024-06-30T23:59:59.999Z"
    }
  },
  "controlPeriod": {
    "selectedPreset": "custom",
    "selectedDates": {
      "start": "2024-05-01T00:00:00.000Z",
      "end":   "2024-05-31T23:59:59.999Z"
    },
    "active": true
  },
  "selectedBreakdowns": [
    { "key": "genders", "values": ["male", "female"] }
  ]
}
```

## Example response

Returns `201 Created` with the full campaign object:

```
{
  "id": "64a1b2c3d4e5f6a7b8c9d0e7",
  "organisationId": "64a1b2c3d4e5f6a7b8c9d0e2",
  "name": "Summer Promotion",
  "metric": { "key": "entries", "display": "Entries" },
  "campaignUplift": 0.1,
  "taxonomies": [],
  "lineTaxonomies": [],
  "testLocations": ["64a1b2c3d4e5f6a7b8c9d0e3"],
  "controlLocations": [],
  "testPeriod": {
    "selectedPreset": "custom",
    "selectedDates": { "start": "2024-06-01T00:00:00.000Z", "end": "2024-06-30T23:59:59.999Z" }
  },
  "controlPeriod": {
    "selectedPreset": "custom",
    "selectedDates": { "start": "2024-05-01T00:00:00.000Z", "end": "2024-05-31T23:59:59.999Z" },
    "active": true
  },
  "selectedBreakdowns": [{ "key": "genders", "values": ["male", "female"] }],
  "testLocationsExcluded": false,
  "controlLocationsExcluded": false,
  "created": "2024-04-15T10:30:00.000Z",
  "updatedAt": "2024-04-15T10:30:00.000Z"
}
```