> ## Documentation Index > Fetch the complete documentation index at: https://docs.support.onclarity.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a campaign > Creates an outbound calling campaign, optionally with its first contacts in `items`. Without a `start_time` the campaign is created as a `draft` and dials nobody until you start it. With a `start_time` it is `scheduled` and starts dialing on its own at that time (and within its `calling_window`, when set). The campaign's agent, and any agent set on a contact, must belong to the project, be a voice agent that can place calls, and have a published version. Phone numbers that cannot be parsed are kept with status `invalid` and are never dialed. ## OpenAPI ````yaml /api-reference/voice-openapi.json post /v1/projects/{projectId}/campaigns openapi: 3.0.3 info: title: Clarity Voice API version: '1.0' description: Voice agents, outbound calls, conversations, campaigns, and evals. servers: - url: https://voice-api.onclarity.com security: - organizationApiKey: [] tags: - name: Projects description: >- The projects your organization owns. Every other resource lives in a project. - name: Agents description: Create, configure, version and publish voice agents. - name: Outbound calls description: Have a published agent phone a number now. - name: Conversations description: >- One record per call session, with its calls, recordings, transcripts and artifacts. - name: Calls description: The calls of a project, with their status, direction, timing and outcome. - name: Campaigns description: Outbound calling campaigns that phone a list of numbers on a schedule. - name: Eval suites description: >- Reusable sets of eval scenarios and test cases to measure an agent against. - name: Eval judges description: The LLM judges that score eval calls against your test cases. - name: Eval scenarios description: The simulated-caller scenarios of your eval suites. - name: Eval test cases description: The checks a judge applies to each eval call. - name: Eval submissions description: Run an eval suite against an agent and read the verdicts. paths: /v1/projects/{projectId}/campaigns: parameters: - $ref: '#/components/parameters/ProjectIdPath' post: tags: - Campaigns summary: Create a campaign description: >- Creates an outbound calling campaign, optionally with its first contacts in `items`. Without a `start_time` the campaign is created as a `draft` and dials nobody until you start it. With a `start_time` it is `scheduled` and starts dialing on its own at that time (and within its `calling_window`, when set). The campaign's agent, and any agent set on a contact, must belong to the project, be a voice agent that can place calls, and have a published version. Phone numbers that cannot be parsed are kept with status `invalid` and are never dialed. operationId: createCampaign requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCampaignRequest' example: name: March renewals agent_id: 5b7e9c1d-2a4f-4c6e-8d0b-1f3a5c7e9b24 from_number: '+14155550100' start_time: '2026-03-02T09:00:00-05:00' retries: 2 retry_delay_seconds: 3600 max_concurrency: 5 calling_window: start: '09:00' end: '18:00' days: - 1 - 2 - 3 - 4 - 5 timezone: America/New_York items: - name: Jane Doe phone_number: '+14155550123' custom_vars: plan: Premium renewal_date: '2026-03-31' responses: '201': description: >- The campaign was created. Returns the campaign and the contacts that were added. content: application/json: schema: $ref: '#/components/schemas/CampaignDetailResponse' example: campaign: id: 3f1c2a8e-6b0d-4f6e-9a51-0d2b7c9e4a10 project_id: 8d2e4b1a-1c3f-4e5a-9b7d-6f0a2c4e8b13 name: March renewals agent_id: 5b7e9c1d-2a4f-4c6e-8d0b-1f3a5c7e9b24 from_number: '+14155550100' start_time: '2026-03-02T14:00:00.000Z' callback: false retries: 2 retry_delay_seconds: 3600 max_concurrency: 5 calling_window: start: '09:00' end: '18:00' days: - 1 - 2 - 3 - 4 - 5 timezone: America/New_York status: scheduled started_at: null canceled_at: null ended_at: null created_at: '2026-02-27T15:12:40.000Z' updated_at: '2026-02-27T15:12:40.000Z' items: - id: 9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d campaign_id: 3f1c2a8e-6b0d-4f6e-9a51-0d2b7c9e4a10 name: Jane Doe phone_number: '+14155550123' channel: voice country: US agent_id: null callback: false custom_vars: plan: Premium renewal_date: '2026-03-31' status: scheduled failed_reason: null attempt_count: 0 conversation_id: null start_time: null next_attempt_at: null callback_requested: false callback_origin_item_id: null callback_target_item_id: null created_at: '2026-02-27T15:12:40.000Z' updated_at: '2026-02-27T15:12:40.000Z' '400': description: >- The request body is not valid JSON, or an agent uses an architecture that is no longer supported. content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '403': description: >- The credential has no access to this project, or it may only manage draft campaigns (`code: PUBLISH_CAPABILITY_REQUIRED`) and the body sets a `start_time`. Organization API keys can schedule campaigns. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: publish_capability_required code: PUBLISH_CAPABILITY_REQUIRED '404': description: The project does not exist or is not visible to this credential. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- `AGENT_NOT_PUBLISHED`: the campaign's agent (or a contact's agent) has never been published. Publish it first. Nothing is created. content: application/json: schema: $ref: '#/components/schemas/AgentNotPublishedError' '422': description: >- The body failed validation (see `issues`), an agent id is not an agent of this project, or an agent cannot place calls (`code: AGENT_TYPE_NOT_DISPATCHABLE`, a Voice Assist agent). content: application/json: schema: $ref: '#/components/schemas/ValidationError' example: error: 'max_concurrency: Number must be greater than or equal to 5' issues: - path: max_concurrency code: too_small message: Number must be greater than or equal to 5 minimum: 5 components: parameters: ProjectIdPath: name: projectId in: path required: true schema: type: string description: Project id schemas: CreateCampaignRequest: type: object required: - name properties: name: type: string minLength: 1 agent_id: type: string minLength: 1 nullable: true description: Agent that places the calls. Must be published. from_number: type: string minLength: 1 nullable: true description: >- Caller id to place the calls from (one of the project's outbound numbers). start_time: type: string format: date-time nullable: true description: >- ISO 8601 with a UTC offset. Setting it schedules the campaign; omit to create a draft. callback: type: boolean default: false description: Call people back when they ask for it during the call. retries: type: integer minimum: 0 default: 0 retry_delay_seconds: type: integer minimum: 0 default: 0 max_concurrency: type: integer minimum: 5 maximum: 20 default: 5 calling_window: allOf: - $ref: '#/components/schemas/CampaignCallingWindow' nullable: true items: type: array description: Contacts to add now. More can be added later. items: $ref: '#/components/schemas/CampaignItemCreate' CampaignDetailResponse: type: object required: - campaign - items properties: campaign: $ref: '#/components/schemas/Campaign' items: type: array items: $ref: '#/components/schemas/CampaignItem' Error: type: object required: - error additionalProperties: true properties: error: type: string description: Error message code: type: string description: >- A stable machine-readable reason, present on the refusals a client may branch on. Among them: `PUBLISH_CAPABILITY_REQUIRED` (403, the credential may not change what is live), `AGENT_NOT_PUBLISHED` (409, the agent has no published version yet), `AGENT_TYPE_NOT_DISPATCHABLE` (422, a Voice Assist agent named where an agent must place or take a call; the body carries `agent_type` and `agent_id`), `NOT_APPLICABLE_TO_AGENT_TYPE` (422, a voice-only setting written on a Voice Assist agent), `AGENT_TYPE_BOUNDARY` (409), `AGENT_TYPE_NOT_SUPPORTED` (400), `VOICE_ASSISTANT_REQUIRED` (403, the organization is not licensed for Voice Assist), `ORGANIZATION_UNAVAILABLE` (503) and `REGION_PROFILE_CONFLICT` (503). AgentNotPublishedError: type: object description: >- Refusal: the agent named where an agent is assigned to take or place calls (dispatch rules, campaigns and their items, outbound caller id, dispatch-call) was never published, so no call could run it. Refused before any side effect; an assignment saved earlier stays. Match on `code`. required: - error - code - agent_id properties: error: type: string example: >- Agent "Billing bot" is not published yet — publish it before it can take calls code: type: string enum: - AGENT_NOT_PUBLISHED agent_id: type: string ValidationError: type: object description: >- A validation failure. `error` is a human-readable summary; `issues` (request validation) or `details` (agent configuration validation) locate each problem. properties: error: type: string message: type: string issues: type: array items: type: object properties: path: type: string description: Dotted path of the offending field code: type: string message: type: string details: type: array items: {} CampaignCallingWindow: type: object description: >- A recurring window in which the campaign may dial. Outside it, contacts wait for the next window. When `end` is not after `start` the window runs past midnight (for example 22:00 to 02:00). required: - start - end - timezone properties: start: type: string pattern: ^([01]\d|2[0-3]):[0-5]\d$ description: Start of the window, 24-hour `HH:MM`, in `timezone`. example: '09:00' end: type: string pattern: ^([01]\d|2[0-3]):[0-5]\d$ description: End of the window (exclusive), 24-hour `HH:MM`, in `timezone`. example: '18:00' days: type: array maxItems: 7 description: >- ISO weekdays on which the window applies (1 = Monday … 7 = Sunday). Omitted or empty means every day. items: type: integer minimum: 1 maximum: 7 example: - 1 - 2 - 3 - 4 - 5 timezone: type: string minLength: 1 description: IANA time zone the window is expressed in. example: America/New_York CampaignItemCreate: type: object required: - phone_number properties: name: type: string minLength: 1 nullable: true phone_number: type: string minLength: 1 description: Number to call, preferably in E.164 format (`+14155550123`). agent_id: type: string minLength: 1 nullable: true description: Agent for this contact; omit to use the campaign's agent. callback: type: boolean description: Defaults to the campaign's `callback`. custom_vars: type: object description: Values the agent can use during the call. String values only. additionalProperties: type: string Campaign: type: object description: An outbound calling campaign. required: - id - project_id - name - callback - retries - retry_delay_seconds - max_concurrency - status - created_at - updated_at properties: id: type: string project_id: type: string name: type: string agent_id: type: string nullable: true description: Agent that places the calls, unless a contact names its own. from_number: type: string nullable: true description: Caller id the calls are placed from. start_time: type: string nullable: true description: When the campaign starts (or started) dialing. `null` for a draft. callback: type: boolean description: >- Default `callback` for new contacts (whether a callback is placed when the person asks to be called back). retries: type: integer description: How many more times an unanswered or failed contact is retried. retry_delay_seconds: type: integer description: Wait between attempts, in seconds. max_concurrency: type: integer description: Maximum simultaneous calls (5–20). calling_window: type: object nullable: true description: >- When the campaign may dial (same shape as `CampaignCallingWindow`). `null` means any time. properties: start: type: string description: 24-hour HH:MM end: type: string description: 24-hour HH:MM days: type: array items: type: integer timezone: type: string status: type: string enum: - draft - scheduled - running - canceled - ended description: >- `draft` (no start time), `scheduled` (will start at `start_time`), `running`, `canceled`, or `ended` (every contact finished). started_at: type: string nullable: true canceled_at: type: string nullable: true ended_at: type: string nullable: true created_at: type: string updated_at: type: string item_counts: type: object description: >- Number of contacts per contact status. Present in the list response only. additionalProperties: type: integer CampaignItem: type: object description: One contact on a campaign and the state of its call. required: - id - campaign_id - phone_number - channel - callback - custom_vars - status - attempt_count - callback_requested - created_at - updated_at properties: id: type: string campaign_id: type: string name: type: string nullable: true phone_number: type: string channel: type: string description: Always `voice`. country: type: string nullable: true description: >- ISO country code derived from the phone number; `null` when the number cannot be parsed. agent_id: type: string nullable: true description: Agent for this contact; `null` uses the campaign's agent. callback: type: boolean custom_vars: type: object description: Values the agent can use during the call, as string pairs. additionalProperties: type: string status: type: string enum: - draft - scheduled - ongoing - failed - ended - rescheduled - invalid description: >- `scheduled` (waiting to be dialed), `ongoing` (call in progress), `ended` (call completed), `failed` (all attempts failed), `rescheduled` (replaced by a callback contact), `invalid` (the number cannot be dialed). failed_reason: type: string nullable: true attempt_count: type: integer conversation_id: type: string nullable: true description: The conversation of the latest call to this contact. start_time: type: string nullable: true next_attempt_at: type: string nullable: true description: When the next retry is due. callback_requested: type: boolean description: The person asked to be called back during the call. callback_origin_item_id: type: string nullable: true description: For a callback contact, the contact whose call asked for it. callback_target_item_id: type: string nullable: true description: The callback contact created from this contact's call. created_at: type: string updated_at: type: string duration_sec: type: number nullable: true description: >- Total call duration in seconds. Returned by the get-campaign operation; `null` before a call. resolution: type: string nullable: true description: >- `resolved` or `unresolved` once the call has been judged; otherwise `null`. Returned by the get-campaign operation. responses: Unauthorized: description: No credential was sent, or the API key is invalid or revoked. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Invalid or revoked token securitySchemes: organizationApiKey: type: http scheme: bearer description: >- Your organization API key (it starts with `anek_org_`). The same key works on the Voice API and the Support API. See [Authentication](/authentication). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.