> ## 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. # Add contacts to a campaign > Adds one or more contacts to a `draft` or `scheduled` campaign. Each contact may override the campaign's agent and callback setting, and carries `custom_vars` the agent can use during the call. Numbers that cannot be parsed are stored with status `invalid` and never dialed. ## OpenAPI ````yaml /api-reference/voice-openapi.json post /v1/projects/{projectId}/campaigns/{id}/items 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/{id}/items: parameters: - $ref: '#/components/parameters/ProjectIdPath' - $ref: '#/components/parameters/CampaignId' post: tags: - Campaigns summary: Add contacts to a campaign description: >- Adds one or more contacts to a `draft` or `scheduled` campaign. Each contact may override the campaign's agent and callback setting, and carries `custom_vars` the agent can use during the call. Numbers that cannot be parsed are stored with status `invalid` and never dialed. operationId: addCampaignItems requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AddCampaignItemsRequest' example: items: - name: John Smith phone_number: '+447700900123' custom_vars: plan: Basic - phone_number: '+14155550199' responses: '201': description: The contacts that were added content: application/json: schema: $ref: '#/components/schemas/CampaignItemsResponse' example: items: - id: 1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e campaign_id: 3f1c2a8e-6b0d-4f6e-9a51-0d2b7c9e4a10 name: John Smith phone_number: '+447700900123' channel: voice country: GB agent_id: null callback: false custom_vars: plan: Basic 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-28T10:05:00.000Z' updated_at: '2026-02-28T10:05:00.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 campaign is scheduled. Organization API keys can. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: No such campaign in this project. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- The campaign is running, canceled or ended, so its contacts can no longer change, or (`AGENT_NOT_PUBLISHED`) a contact's agent has never been published. content: application/json: schema: anyOf: - $ref: '#/components/schemas/AgentNotPublishedError' - $ref: '#/components/schemas/Error' example: error: >- Items can only be edited while a campaign is draft or scheduled (status: running) '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`). content: application/json: schema: $ref: '#/components/schemas/ValidationError' components: parameters: ProjectIdPath: name: projectId in: path required: true schema: type: string description: Project id CampaignId: name: id in: path required: true schema: type: string description: Campaign id schemas: AddCampaignItemsRequest: type: object required: - items properties: items: type: array minItems: 1 items: $ref: '#/components/schemas/CampaignItemCreate' CampaignItemsResponse: type: object required: - items properties: 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: {} 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 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.