> ## 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. # Update a campaign contact > Changes one contact on a `draft` or `scheduled` campaign. Send only the fields to change; at least one is required. `custom_vars`, when sent, replaces the contact's variables. Changing the phone number re-checks it: an unparseable number marks the contact `invalid`. ## OpenAPI ````yaml /api-reference/voice-openapi.json put /v1/projects/{projectId}/campaigns/{id}/items/{itemId} 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/{itemId}: parameters: - $ref: '#/components/parameters/ProjectIdPath' - $ref: '#/components/parameters/CampaignId' - name: itemId in: path required: true description: Contact (campaign item) id schema: type: string put: tags: - Campaigns summary: Update a campaign contact description: >- Changes one contact on a `draft` or `scheduled` campaign. Send only the fields to change; at least one is required. `custom_vars`, when sent, replaces the contact's variables. Changing the phone number re-checks it: an unparseable number marks the contact `invalid`. operationId: updateCampaignItem requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateCampaignItemRequest' example: phone_number: '+447700900456' custom_vars: plan: Premium responses: '200': description: The updated contact content: application/json: schema: $ref: '#/components/schemas/CampaignItemResponse' example: item: id: 1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e campaign_id: 3f1c2a8e-6b0d-4f6e-9a51-0d2b7c9e4a10 name: John Smith phone_number: '+447700900456' channel: voice country: GB agent_id: null callback: false custom_vars: plan: Premium 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:07:30.000Z' '400': description: >- The request body is not valid JSON, or the 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, or no such contact on it. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Campaign item not found '409': description: >- The campaign is running, canceled or ended, or (`AGENT_NOT_PUBLISHED`) the contact's agent has never been published. content: application/json: schema: anyOf: - $ref: '#/components/schemas/AgentNotPublishedError' - $ref: '#/components/schemas/Error' '422': description: >- The body failed validation (see `issues`), the agent id is not an agent of this project, or the 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: UpdateCampaignItemRequest: type: object minProperties: 1 description: Send only the fields to change. properties: name: type: string minLength: 1 nullable: true phone_number: type: string minLength: 1 agent_id: type: string minLength: 1 nullable: true callback: type: boolean custom_vars: type: object description: Replaces the contact's variables. additionalProperties: type: string CampaignItemResponse: type: object required: - item properties: item: $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: {} 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.