> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getvoxai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getvoxai.com/_mcp/server.

# Create campaign

POST https://api.getvoxai.com/v1/campaigns
Content-Type: application/json

Creates a campaign in `draft` with its own empty list of contacts and returns it. Nothing is dialed yet: add the contacts with `POST /campaigns/{campaign_id}/contacts`, then start it with `POST /campaigns/{campaign_id}/start`. You must declare in `contact_origin` where the right to call these people comes from; it is recorded once with the key and the time and cannot be replaced. The calling window is the intersection of `calling_hours` (default 09:00-18:00) and the window of the organization, in Italian time. With a test key nothing is created: the response has `status: simulated` and an id that does not exist. Required scope: `campaigns:write`. With a test key (`vx_test_`) it is simulated: nothing real happens and nothing is billed. Requires an `Idempotency-Key` header. NOT retriable: when the operation itself fails with a `429`, a `5xx` or a temporary `409`, the outcome is uncertain and the key becomes "unknown" (the same key gives 409 `idempotency_outcome_unknown`); with no response at all, the same key returns the first outcome or that same 409. After `idempotency_outcome_unknown`, read the state of the resource and retry with a new key only if the operation did not happen. A `429 rate_limited` from the request limit and `409 request_in_progress` come before the operation and leave the key as it is: retry with the same key.

Reference: https://docs.getvoxai.com/api-reference/campaigns/create

## Authentication

- `Authorization` header (bearer token, required) — API key created by an Owner or Admin of the organization. Never in the query string.

## Request

### Headers

- `VoxAI-Version` (enum, optional) — API version for this request; defaults to the version the key is pinned to.
  - Allowed values: `2026-10-01`
- `Idempotency-Key` (string, required) — A unique value you generate for each new operation (16 to 64 letters, digits, hyphen or underscore; a UUID works). Repeating the same request with the same key within 24 hours returns the first response and does nothing again, when that response was a success or a `4xx` error the same request would always get again (not `429`, and not the temporary `409` codes `request_in_progress`, `caller_has_active_call` and `caller_request_in_progress`: for those, and for a `5xx`, see the note on retrying in the operation); the same key with a different request is refused with `idempotency_key_reused`.

### Body (application/json)

This endpoint expects an object.

- `name` (string, required) — The name of the campaign, from 1 to 200 characters.
- `agent_id` (string, required) — The agent that makes the calls, as returned by `GET /agents`. To start the campaign it needs an Italian phone line and must not be suspended.
- `max_concurrency` (integer, optional) — Calls at the same time for this campaign, from 1 to 50 (default 1). The plan limit of concurrent calls still applies.
- `calling_hours` (CampaignsPostRequestBodyContentApplicationJsonSchemaCallingHours, optional) — The campaign window (default 09:00-18:00). The effective window is its intersection with the organization window. An `end` that is not after `start` gives `400 invalid_request`.
- `contact_origin` (CampaignsPostRequestBodyContentApplicationJsonSchemaContactOrigin, optional) — Required (without it the answer is `422 contact_origin_required`): your declaration of where the right to call comes from. VoxAI records it with the key and the time, so you can show it if asked; it does not verify it and does not check the Register of Oppositions for you. `basis` and `purpose` are required inside it.

## Response

### 201

Created.

- `object` ("campaign", required) — Always `campaign`.
- `id` (string, required) — Id of the campaign: use it in `GET /campaigns/{campaign_id}` and in the other campaign operations.
- `name` (string, required) — The name given to the campaign.
- `status` (enum, required) — `draft`: created and not started yet. `running`: the campaign is calling its contacts. `paused`: stopped, it can be started again with `POST /campaigns/{campaign_id}/start`. `completed`: finished, it cannot be started or paused again. `simulated`: only with a test key, nothing was changed.
  - Allowed values: `draft`, `running`, `paused`, `completed`, `simulated`
- `paused_reason` (enum, required) — Set when the platform, and not you, paused the campaign; `null` otherwise. `feature_not_available`: the platform paused the campaign because the plan no longer includes outbound campaigns. `agent_suspended`: the agent was suspended; resuming it restarts the campaign.
  - Allowed values: `feature_not_available`, `agent_suspended`
- `agent` (CampaignsPostResponsesContentApplicationJsonSchemaAgent, required) — The agent that makes the calls of the campaign.
- `max_concurrency` (integer, required) — Calls the campaign can make at the same time. The plan limit of concurrent calls still applies.
- `calling_hours` (CampaignsPostResponsesContentApplicationJsonSchemaCallingHours, required) — The daily window of the campaign. The effective window is its intersection with the organization window.
- `contact_origin` (CampaignsPostResponsesContentApplicationJsonSchemaContactOrigin, required, nullable) — The declaration made when the campaign was created; `null` for a campaign created in the app without one (it cannot be started through the API).
- `stats` (CampaignsPostResponsesContentApplicationJsonSchemaStats, required) — Counts of the contacts of the campaign, updated as the calls proceed.
- `simulated` (boolean, required) — `true` with a test key: the operation was only checked and nothing was changed. After `POST /campaigns` with a test key the id does not exist.
- `created_at` (datetime, required) — When the campaign was created, ISO 8601 UTC.

## Errors

### 400 Bad Request Error

Possible errors: * `invalid_api_version`: The `VoxAI-Version` header names a version that does not exist. Use one of the versions listed in the `VoxAI-Version` parameter, or omit the header to use the version the key is pinned to. * `invalid_request`: The path, query or body does not match the schema of the operation: a missing or unknown field, a wrong type, a value out of range. Fix the request. `details` lists each problem as `{ location, path, message }`: `location` is `params`, `query` or `body` and `path` points to the field.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 401 Unauthorized Error

Possible errors: - `invalid_api_key`: The `Authorization` header is missing, malformed, or carries a key that does not exist, was revoked or has expired. Send `Authorization: Bearer vx_live_…` (or `vx_test_…`) with an active key. Create a new key in the app if this one expired.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 403 Forbidden Error

Possible errors: - `feature_not_available`: The plan of the organization does not include the API, or the feature this operation needs. Upgrade the plan in the app. Reads and deletions stay available after a downgrade. - `insufficient_scope`: The key does not have the scope this operation requires (written in the description of the operation). Create a key with the required scope (an Owner or Admin can do it in the app), or ask for the scope to be added. - `ip_not_allowed`: The key has an IP allow-list and the request comes from an address that is not on it. Call from an allowed address, or add this address to the key in the app. - `organization_suspended`: The organization that owns the key is suspended. Contact the organization Owner: nothing can be done through the API until the organization is active again.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 404 Not Found Error

Possible errors: - `not_found`: The resource does not exist, or it belongs to another organization: the two cases give the same answer on purpose. Check the id. Ids come from the list operations of the same organization.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 409 Conflict Error

Possible errors: * `idempotency_outcome_unknown`: A previous request with this `Idempotency-Key` failed with a `429`, a `5xx` or a temporary `409` inside a NOT retriable operation, or was interrupted with no response, so its outcome is not known and it is never run again with the same key. Read the state of the resource (for example `GET /outbound-calls/{outbound_call_id}` or the list) and retry with a NEW key only if the operation did not happen. * `request_in_progress`: A request with the same `Idempotency-Key` is still running. Wait a few seconds and retry with the same key: you will get the outcome of the first request.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 422 Unprocessable Entity Error

Possible errors: * `contact_origin_invalid`: `contact_origin` is present but not valid: `basis` or `purpose` missing or unknown, `reference` longer than 120 characters, `opposition_register_checked_on` not a valid date, in the future, or missing when `purpose` is `marketing` and `basis` is not `consent`. Fix the fields in `details`: each item is `{ field, code }`, with `code` one of `missing`, `invalid`, `unknown_value`, `too_long`, `in_the_future`, `invalid_format`. * `contact_origin_required`: The body has no `contact_origin` at all. Declare where the right to call comes from in `contact_origin` (see the field description). * `idempotency_key_reused`: The same `Idempotency-Key` was already used in the last 24 hours with a different request (other operation, path or body). Use a new key for a new request. Reuse a key only to repeat exactly the same request.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 429 Too Many Requests Error

Possible errors: - `rate_limited`: Too many requests: over the per-minute limit of this key or of the whole organization (see `rate_limits` in `GET /me`), or over a limit of the operation itself, such as the hourly limit on webhook tests and resends. Wait for the number of seconds in the `Retry-After` header, then retry. Spread requests over time.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 500 Internal Server Error

Possible errors: - `internal_error`: An unexpected error on our side. Retry once after a few seconds. For writes marked as retriable, retry with the same `Idempotency-Key`, so the operation is never done twice; for the other writes, first read the state of the resource, then retry with a NEW key only if the operation did not happen. If it persists, contact support with the `requestId`.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 503 Service Unavailable Error

Possible errors: - `api_not_configured`: The API is not enabled on this service. Contact support. - `service_unavailable`: A component the operation depends on is temporarily unavailable. Retry after a few seconds. For writes marked as retriable, use the same `Idempotency-Key`; for the other writes, first read the state of the resource, then retry with a NEW key only if the operation did not happen.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

## Types

### CampaignsPostRequestBodyContentApplicationJsonSchemaCallingHours

The campaign window (default 09:00-18:00). The effective window is its intersection with the organization window. An `end` that is not after `start` gives `400 invalid_request`.

- `start` (string, required) — When calls may start each day, HH:MM in Italian time. It must be before `end`.
- `end` (string, required) — When calls stop each day, HH:MM in Italian time. It must be after `start`.

### CampaignsPostRequestBodyContentApplicationJsonSchemaContactOrigin

Required (without it the answer is `422 contact_origin_required`): your declaration of where the right to call comes from. VoxAI records it with the key and the time, so you can show it if asked; it does not verify it and does not check the Register of Oppositions for you. `basis` and `purpose` are required inside it.

- `basis` (string, optional) — Required. Why you may call these people. `contract`, `callback_request`, `consent`, `legitimate_interest`. `contract`: they are your customers and the call is about the contract. `callback_request`: they asked to be called back. `consent`: they gave you consent to be called. `legitimate_interest`: you rely on a legitimate interest you have assessed. Any other value gives `422 contact_origin_invalid`.
- `purpose` (string, optional) — Required. What the call is for. `service`, `marketing`. `service`: about something the person already has with you (an appointment, an order, a reminder). `marketing`: to promote or sell. Any other value gives `422 contact_origin_invalid`.
- `reference` (string, optional) — Optional. A reference in your own system (a list, a request, a contract), at most 120 characters. It must not be personal data.
- `opposition_register_checked_on` (string, optional) — The day (YYYY-MM-DD, not in the future) you last checked the numbers against the public Register of Oppositions. Required when `purpose` is `marketing` and `basis` is not `consent`; optional otherwise.

### CampaignsPostResponsesContentApplicationJsonSchemaAgent

The agent that makes the calls of the campaign.

- `id` (string, required) — Id of the agent that makes the calls.
- `name` (string, required, nullable) — Name of the agent.

### CampaignsPostResponsesContentApplicationJsonSchemaCallingHours

The daily window of the campaign. The effective window is its intersection with the organization window.

- `start` (string, required) — When calls may start each day, HH:MM in Italian time.
- `end` (string, required) — When calls stop each day, HH:MM in Italian time.

### CampaignsPostResponsesContentApplicationJsonSchemaContactOrigin

The declaration made when the campaign was created; `null` for a campaign created in the app without one (it cannot be started through the API).

- `basis` (string, required) — Why you declared you may call these people, as sent when the campaign was created: `contract`, `callback_request`, `consent` or `legitimate_interest`.
- `purpose` (string, required) — What the calls are for, as declared: `service` or `marketing`.
- `reference` (string, required, nullable) — The reference in your own system sent with the declaration; `null` if none was sent.
- `opposition_register_checked_on` (string, required, nullable) — The day (YYYY-MM-DD) you declared the numbers were last checked against the public Register of Oppositions; `null` if none was sent.
- `declared_at` (datetime, required) — When the declaration was recorded, ISO 8601 UTC.

### CampaignsPostResponsesContentApplicationJsonSchemaStats

Counts of the contacts of the campaign, updated as the calls proceed.

- `total` (integer, required) — Contacts in the campaign.
- `called` (integer, required) — Contacts being dialed or already dialed: those with status `dialing`, `completed` or `failed`.
- `completed` (integer, required) — Contacts with status `completed`.
- `goal_achieved` (integer, required) — Contacts whose call reached the goal of the agent, according to the evaluation of the call.

## Examples

### Service reminders to customers

**Request**

```json
{
  "name": "Appointment reminders November",
  "agent_id": "promemoria-studio-rossi",
  "max_concurrency": 2,
  "calling_hours": {
    "start": "09:00",
    "end": "18:00"
  },
  "contact_origin": {
    "basis": "contract",
    "purpose": "service",
    "reference": "reminders-2026-11"
  }
}
```

**Response**

```json
{
  "object": "campaign",
  "id": "4e7a9c12-8b3d-4f60-a5e1-6d2c0b9f3a71",
  "name": "Appointment reminders November",
  "status": "draft",
  "paused_reason": null,
  "agent": {
    "id": "promemoria-studio-rossi",
    "name": "Promemoria Studio Rossi"
  },
  "max_concurrency": 2,
  "calling_hours": {
    "start": "09:00",
    "end": "18:00"
  },
  "contact_origin": {
    "basis": "contract",
    "purpose": "service",
    "reference": "reminders-2026-11",
    "opposition_register_checked_on": null,
    "declared_at": "2026-11-16T08:55:12Z"
  },
  "stats": {
    "total": 0,
    "called": 0,
    "completed": 0,
    "goal_achieved": 0
  },
  "simulated": false,
  "created_at": "2026-11-16T08:55:12Z"
}
```

**SDK Code**

```python Service reminders to customers
import requests

url = "https://api.getvoxai.com/v1/campaigns"

payload = {
    "name": "Appointment reminders November",
    "agent_id": "promemoria-studio-rossi",
    "max_concurrency": 2,
    "calling_hours": {
        "start": "09:00",
        "end": "18:00"
    },
    "contact_origin": {
        "basis": "contract",
        "purpose": "service",
        "reference": "reminders-2026-11"
    }
}
headers = {
    "Idempotency-Key": "3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Service reminders to customers
const url = 'https://api.getvoxai.com/v1/campaigns';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"name":"Appointment reminders November","agent_id":"promemoria-studio-rossi","max_concurrency":2,"calling_hours":{"start":"09:00","end":"18:00"},"contact_origin":{"basis":"contract","purpose":"service","reference":"reminders-2026-11"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Service reminders to customers
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.getvoxai.com/v1/campaigns"

	payload := strings.NewReader("{\n  \"name\": \"Appointment reminders November\",\n  \"agent_id\": \"promemoria-studio-rossi\",\n  \"max_concurrency\": 2,\n  \"calling_hours\": {\n    \"start\": \"09:00\",\n    \"end\": \"18:00\"\n  },\n  \"contact_origin\": {\n    \"basis\": \"contract\",\n    \"purpose\": \"service\",\n    \"reference\": \"reminders-2026-11\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Service reminders to customers
require 'uri'
require 'net/http'

url = URI("https://api.getvoxai.com/v1/campaigns")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Appointment reminders November\",\n  \"agent_id\": \"promemoria-studio-rossi\",\n  \"max_concurrency\": 2,\n  \"calling_hours\": {\n    \"start\": \"09:00\",\n    \"end\": \"18:00\"\n  },\n  \"contact_origin\": {\n    \"basis\": \"contract\",\n    \"purpose\": \"service\",\n    \"reference\": \"reminders-2026-11\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java Service reminders to customers
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.getvoxai.com/v1/campaigns")
  .header("Idempotency-Key", "3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Appointment reminders November\",\n  \"agent_id\": \"promemoria-studio-rossi\",\n  \"max_concurrency\": 2,\n  \"calling_hours\": {\n    \"start\": \"09:00\",\n    \"end\": \"18:00\"\n  },\n  \"contact_origin\": {\n    \"basis\": \"contract\",\n    \"purpose\": \"service\",\n    \"reference\": \"reminders-2026-11\"\n  }\n}")
  .asString();
```

```php Service reminders to customers
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.getvoxai.com/v1/campaigns', [
  'body' => '{
  "name": "Appointment reminders November",
  "agent_id": "promemoria-studio-rossi",
  "max_concurrency": 2,
  "calling_hours": {
    "start": "09:00",
    "end": "18:00"
  },
  "contact_origin": {
    "basis": "contract",
    "purpose": "service",
    "reference": "reminders-2026-11"
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'Idempotency-Key' => '3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58',
  ],
]);

echo $response->getBody();
```

```csharp Service reminders to customers
using RestSharp;

var client = new RestClient("https://api.getvoxai.com/v1/campaigns");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"Appointment reminders November\",\n  \"agent_id\": \"promemoria-studio-rossi\",\n  \"max_concurrency\": 2,\n  \"calling_hours\": {\n    \"start\": \"09:00\",\n    \"end\": \"18:00\"\n  },\n  \"contact_origin\": {\n    \"basis\": \"contract\",\n    \"purpose\": \"service\",\n    \"reference\": \"reminders-2026-11\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Service reminders to customers
import Foundation

let headers = [
  "Idempotency-Key": "3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "name": "Appointment reminders November",
  "agent_id": "promemoria-studio-rossi",
  "max_concurrency": 2,
  "calling_hours": [
    "start": "09:00",
    "end": "18:00"
  ],
  "contact_origin": [
    "basis": "contract",
    "purpose": "service",
    "reference": "reminders-2026-11"
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.getvoxai.com/v1/campaigns")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Marketing campaign checked against the Register of Oppositions

**Request**

```json
{
  "name": "Winter offer",
  "agent_id": "promemoria-studio-rossi",
  "contact_origin": {
    "basis": "legitimate_interest",
    "purpose": "marketing",
    "opposition_register_checked_on": "2026-11-10"
  }
}
```

**Response**

```json
{
  "object": "campaign",
  "id": "b83d5f07-2c19-4a6e-9d4b-7e1f0a8c5d23",
  "name": "Winter offer",
  "status": "draft",
  "paused_reason": null,
  "agent": {
    "id": "promemoria-studio-rossi",
    "name": "Promemoria Studio Rossi"
  },
  "max_concurrency": 1,
  "calling_hours": {
    "start": "09:00",
    "end": "18:00"
  },
  "contact_origin": {
    "basis": "legitimate_interest",
    "purpose": "marketing",
    "reference": null,
    "opposition_register_checked_on": "2026-11-10",
    "declared_at": "2026-11-16T09:02:40Z"
  },
  "stats": {
    "total": 0,
    "called": 0,
    "completed": 0,
    "goal_achieved": 0
  },
  "simulated": false,
  "created_at": "2026-11-16T09:02:40Z"
}
```

**SDK Code**

```python Marketing campaign checked against the Register of Oppositions
import requests

url = "https://api.getvoxai.com/v1/campaigns"

payload = {
    "name": "Winter offer",
    "agent_id": "promemoria-studio-rossi",
    "contact_origin": {
        "basis": "legitimate_interest",
        "purpose": "marketing",
        "opposition_register_checked_on": "2026-11-10"
    }
}
headers = {
    "Idempotency-Key": "3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Marketing campaign checked against the Register of Oppositions
const url = 'https://api.getvoxai.com/v1/campaigns';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"name":"Winter offer","agent_id":"promemoria-studio-rossi","contact_origin":{"basis":"legitimate_interest","purpose":"marketing","opposition_register_checked_on":"2026-11-10"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Marketing campaign checked against the Register of Oppositions
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.getvoxai.com/v1/campaigns"

	payload := strings.NewReader("{\n  \"name\": \"Winter offer\",\n  \"agent_id\": \"promemoria-studio-rossi\",\n  \"contact_origin\": {\n    \"basis\": \"legitimate_interest\",\n    \"purpose\": \"marketing\",\n    \"opposition_register_checked_on\": \"2026-11-10\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Marketing campaign checked against the Register of Oppositions
require 'uri'
require 'net/http'

url = URI("https://api.getvoxai.com/v1/campaigns")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Winter offer\",\n  \"agent_id\": \"promemoria-studio-rossi\",\n  \"contact_origin\": {\n    \"basis\": \"legitimate_interest\",\n    \"purpose\": \"marketing\",\n    \"opposition_register_checked_on\": \"2026-11-10\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java Marketing campaign checked against the Register of Oppositions
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.getvoxai.com/v1/campaigns")
  .header("Idempotency-Key", "3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Winter offer\",\n  \"agent_id\": \"promemoria-studio-rossi\",\n  \"contact_origin\": {\n    \"basis\": \"legitimate_interest\",\n    \"purpose\": \"marketing\",\n    \"opposition_register_checked_on\": \"2026-11-10\"\n  }\n}")
  .asString();
```

```php Marketing campaign checked against the Register of Oppositions
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.getvoxai.com/v1/campaigns', [
  'body' => '{
  "name": "Winter offer",
  "agent_id": "promemoria-studio-rossi",
  "contact_origin": {
    "basis": "legitimate_interest",
    "purpose": "marketing",
    "opposition_register_checked_on": "2026-11-10"
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'Idempotency-Key' => '3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58',
  ],
]);

echo $response->getBody();
```

```csharp Marketing campaign checked against the Register of Oppositions
using RestSharp;

var client = new RestClient("https://api.getvoxai.com/v1/campaigns");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"Winter offer\",\n  \"agent_id\": \"promemoria-studio-rossi\",\n  \"contact_origin\": {\n    \"basis\": \"legitimate_interest\",\n    \"purpose\": \"marketing\",\n    \"opposition_register_checked_on\": \"2026-11-10\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Marketing campaign checked against the Register of Oppositions
import Foundation

let headers = [
  "Idempotency-Key": "3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "name": "Winter offer",
  "agent_id": "promemoria-studio-rossi",
  "contact_origin": [
    "basis": "legitimate_interest",
    "purpose": "marketing",
    "opposition_register_checked_on": "2026-11-10"
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.getvoxai.com/v1/campaigns")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```