# Campaign settings

The team's contact frequency cap.

## Endpoints

- `GET /platform/campaign-settings`: [Get campaign settings](https://docs.polymorfa.com/api/campaign-settings/get-campaign-settings)
- `GET /platform/campaign-settings/frequency-cap`: [Get campaign frequency cap](https://docs.polymorfa.com/api/campaign-settings/get-campaign-frequency-cap)
- `PUT /platform/campaign-settings/frequency-cap`: [Update campaign frequency cap](https://docs.polymorfa.com/api/campaign-settings/update-campaign-frequency-cap)

## The campaign settings object

### Attributes

- `launchApproval` (object, required). Structured launch approval values for this management campaign setting.
  - `recipientThreshold` (integer, required, nullable, range 1–1000000). Launches that would send to more recipients than this need a team owner or admin. Null turns approval off.
```json
{
  "launchApproval": {
    "recipientThreshold": 1
  }
}
```

## The frequency cap settings object

The team's contact frequency cap.

### Attributes

- `teamId` (string (uuid), required, format uuid). Identifier for the team.
- `maxPer24Hours` (integer, required, nullable, range 1–50). Most campaign messages one phone number receives from the team in any rolling 24 hours, 1 to 50. `null` sets no 24-hour limit.
- `maxPer7Days` (integer, required, nullable, range 1–200). Most campaign messages one phone number receives from the team in any rolling 7 days, 1 to 200. `null` sets no 7-day limit. Must not be lower than `maxPer24Hours`.
- `revision` (integer, required, min 0). Send this value back to change the cap. 0 until the team first saves.
- `updatedAt` (integer, required, nullable, format int64). Unix time in milliseconds of the last change; null until the team first saves.
```json
{
  "teamId": "00000000-0000-4000-8000-000000000000",
  "maxPer24Hours": 1,
  "maxPer7Days": 1,
  "revision": 0,
  "updatedAt": 0
}
```

## Get campaign settings

`GET https://api.polymorfa.com/platform/campaign-settings` (Platform API)

Required permission: `campaigns:read`

Returns the team's campaign settings. `launchApproval.recipientThreshold` is the number of recipients above which a launch needs a team owner or admin; null means no launch needs approval. A team that never saved settings receives `launchApproval.recipientThreshold: null`.

Team keys require `campaigns:read`. Project tokens are not accepted.

### Request

```bash
curl "https://api.polymorfa.com/platform/campaign-settings" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `launchApproval` (object, required). Structured launch approval values for this management campaign setting.
    - `recipientThreshold` (integer, required, nullable, range 1–1000000). Launches that would send to more recipients than this need a team owner or admin. Null turns approval off.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "launchApproval": {
      "recipientThreshold": 1
    }
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

## Get campaign frequency cap

`GET https://api.polymorfa.com/platform/campaign-settings/frequency-cap` (Platform API)

Required permission: `campaigns:read`

Returns the team's contact frequency cap: the most campaign messages one phone number receives from the team in any rolling 24 hours and any rolling 7 days. Every campaign message counts, first messages and later messages of a sequence, from every campaign, project and number in the team. Test sends and messages sent outside campaigns do not count. `null` means no limit for that window. A team that never saved a cap receives both limits `null` and `revision` 0. A campaign can set its own, stricter cap with `frequencyCap`. Accepts a team API key or a live signed-in team member.

Team keys require `campaigns:read`. Project tokens are not accepted.

### Request

```bash
curl "https://api.polymorfa.com/platform/campaign-settings/frequency-cap" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `teamId` (string (uuid), required, format uuid). Identifier for the team.
  - `maxPer24Hours` (integer, required, nullable, range 1–50). Most campaign messages one phone number receives from the team in any rolling 24 hours, 1 to 50. `null` sets no 24-hour limit.
  - `maxPer7Days` (integer, required, nullable, range 1–200). Most campaign messages one phone number receives from the team in any rolling 7 days, 1 to 200. `null` sets no 7-day limit. Must not be lower than `maxPer24Hours`.
  - `revision` (integer, required, min 0). Send this value back to change the cap. 0 until the team first saves.
  - `updatedAt` (integer, required, nullable, format int64). Unix time in milliseconds of the last change; null until the team first saves.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "teamId": "00000000-0000-4000-8000-000000000000",
    "maxPer24Hours": 1,
    "maxPer7Days": 1,
    "revision": 0,
    "updatedAt": 0
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

## Update campaign frequency cap

`PUT https://api.polymorfa.com/platform/campaign-settings/frequency-cap` (Platform API)

Required permission: `campaigns:manage`

Replaces the team's contact frequency cap using the `revision` you read; a changed revision answers `409`. Send `null` for a window to remove its limit, or both `null` to remove the cap. Setting a limit requires the contact frequency caps beta and otherwise answers `403 feature_unavailable`; removing the cap does not. Requires a team API key or a signed-in team owner or admin; project tokens answer `403`. A message over the cap is skipped with `frequency_cap_exceeded`; a later sequence message stops that recipient's remaining sequence. Settled skips are never retried when a cap changes.

Team keys require `campaigns:manage`. Project tokens are not accepted.

### Body

- `maxPer24Hours` (integer, required, nullable, range 1–50). Most campaign messages one phone number receives from the team in any rolling 24 hours, 1 to 50. `null` sets no 24-hour limit.
- `maxPer7Days` (integer, required, nullable, range 1–200). Most campaign messages one phone number receives from the team in any rolling 7 days, 1 to 200. `null` sets no 7-day limit. Must not be lower than `maxPer24Hours`.
- `revision` (integer, required, range 0–2147483646). The `revision` from your last read.

### Request

```bash
curl -X PUT "https://api.polymorfa.com/platform/campaign-settings/frequency-cap" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "maxPer24Hours": 1,
  "maxPer7Days": 1,
  "revision": 0
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `teamId` (string (uuid), required, format uuid). Identifier for the team.
  - `maxPer24Hours` (integer, required, nullable, range 1–50). Most campaign messages one phone number receives from the team in any rolling 24 hours, 1 to 50. `null` sets no 24-hour limit.
  - `maxPer7Days` (integer, required, nullable, range 1–200). Most campaign messages one phone number receives from the team in any rolling 7 days, 1 to 200. `null` sets no 7-day limit. Must not be lower than `maxPer24Hours`.
  - `revision` (integer, required, min 0). Send this value back to change the cap. 0 until the team first saves.
  - `updatedAt` (integer, required, nullable, format int64). Unix time in milliseconds of the last change; null until the team first saves.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "teamId": "00000000-0000-4000-8000-000000000000",
    "maxPer24Hours": 1,
    "maxPer7Days": 1,
    "revision": 0,
    "updatedAt": 0
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```
