---
title: "Create An Outbound Campaign"
method: POST
path: "/v1/convai/outbound-campaigns/campaigns/submit"
tags: ["Agents Platform"]
---

# Create An Outbound Campaign

`POST /v1/convai/outbound-campaigns/campaigns/submit`

## Request

- Base URL: `https://api.elevenlabs.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.elevenlabs.io/v1/convai/outbound-campaigns/campaigns/submit`
- Auth: none declared
- TypeScript: <https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation/docs/v1/convai/outbound-campaigns/campaigns/submit/post.ts> (a function with typed inputs; its response is checked against the schema)

Create an outbound campaign that calls or messages each recipient with the agent, within the policy's calling windows, retrying and following up as it allows. Returns `201` for a new campaign. A repeated request, matched by `idempotency_key` or else by its body, returns the existing campaign with `created` false.

## Headers

- `xi-api-key` string, nullable: Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.

## Request body

- SubmitCampaignRequest
  - `call_name` string, required: The campaign's name.
  - `agent_id` string, required: The agent that places the calls.
  - `recipients` SubmitCampaignRecipient[], required: Who to call. Each recipient becomes a lead of the campaign.
    - `phone_number` string, nullable: The number to call, in E.164 format such as `+14155550100`.
    - `phone_numbers` string[], nullable: More numbers to call, in order after `phone_number`. The lead moves on to the next one when calls to its current number keep failing.
    - `whatsapp_user_id` string, nullable: The contact's WhatsApp user ID. WhatsApp campaigns use it instead of the phone numbers.
    - `id` string, nullable: Your identifier for the recipient, returned as its lead's `recipient_id`.
    - `conversation_initiation_client_data` ConversationInitiationClientDataRequestInput
      - `conversation_config_override` ConversationConfigClientOverrideInput
        - `asr` ASRConversationalConfigOverride
          - `keywords` string[], nullable: Keywords to boost prediction probability for
        - `turn` TurnConfigOverride
          - `soft_timeout_config` SoftTimeoutConfigOverride
            - `message` string, nullable: Message to show when the first soft timeout is reached while waiting for LLM response. Supports dynamic variables (e.g., {{system__time}}, {{custom_variable}}).
            - `additional_soft_timeout_messages` string[], nullable: Extra static filler messages for subsequent soft timeouts in the same LLM generation. The first timeout uses `message`. If fewer messages are configured than `max_soft_timeouts_per_generation`, the last configured message is repeated; otherwise a built-in filler is used.
          - `noisy_environment_message` string, nullable: What the agent says when it detects a noisy environment.
        - `tts` TTSConversationalConfigOverride
          - `model_id` 'eleven_turbo_v2' | 'eleven_turbo_v2_5' | 'eleven_flash_v2' | 'eleven_flash_v2_5' | 'eleven_multilingual_v2' | 'eleven_v3_conversational' | 'eleven_v4' | 'eleven_v4_turbo', nullable: The model to use for TTS
          - `voice_id` string, nullable: The voice ID to use for TTS
          - `supported_voices` SupportedVoice[], nullable: Additional supported voices for the agent
            - `label` string, required
            - `voice_id` string, required
            - `description` string, nullable
            - `language` string, nullable
            - `model_family` 'turbo' | 'flash' | 'multilingual' | 'v3_conversational' | 'v4' | 'v4_turbo'
            - `optimize_streaming_latency` 0 | 1 | 2 | 3 | 4
            - `stability` number, nullable
            - `speed` number, nullable
            - `similarity_boost` number, nullable
            - `clone_strength` number, nullable
          - `stability` number, nullable: The stability of generated speech
          - `speed` number, nullable: The speed of generated speech
          - `similarity_boost` number, nullable: The similarity boost for generated speech
          - `clone_strength` number, nullable: The clone strength for generated speech
          - `pronunciation_dictionary_locators` PydanticPronunciationDictionaryVersionLocator[], nullable: The pronunciation dictionary locators
            - `pronunciation_dictionary_id` string, required: The ID of the pronunciation dictionary
            - `version_id` string, nullable, required: The ID of the version of the pronunciation dictionary
        - `conversation` ConversationConfigOverride
          - `text_only` boolean, nullable: If enabled audio will not be processed and only text will be used, use to avoid audio pricing.
          - `max_duration_seconds` integer, nullable: The maximum duration of a conversation in seconds
        - `agent` AgentConfigOverrideInput
          - `first_message` string, nullable: If non-empty, the first message the agent will say. If empty, the agent waits for the user to start the discussion.
          - `language` string, nullable: Language of the agent - used for ASR and TTS
          - `max_conversation_duration_message` string, nullable: If non-empty, the message the agent will send when max conversation duration is reached.
          - `prompt` PromptAgentAPIModelOverrideInput
            - `prompt` string, nullable: The prompt for the agent
            - `llm` 'gpt-4o-mini' | 'gpt-4o' | 'gpt-4' | 'gpt-4-turbo' | 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'gpt-5' | 'gpt-5.1' | 'gpt-5.2' | 'gpt-5.2-chat-latest' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.4-nano' | 'gpt-5.5' | 'gpt-5.6-sol' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gpt-6-astra' | 'gpt-6-sol' | 'gpt-6-luna' | 'gpt-6.1-sol' | 'gpt-6.1-terra' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-3.5-turbo' | 'gemini-1.5-pro' | 'gemini-1.5-flash' | 'gemini-2.0-flash' | 'gemini-2.0-flash-lite' | 'gemini-2.5-flash-lite' | 'gemini-2.5-flash' | 'gemini-3-pro-preview' | 'gemini-3-flash-preview' | 'gemini-3.1-pro-preview' | 'gemini-3.1-flash-lite-preview' | 'gemini-3.1-flash-lite' | 'gemini-3.5-flash' | 'gemini-3.5-flash-lite' | 'gemini-3.6-flash' | 'gemini-3.7-flash' | 'gemini-3.8-flash' | 'gemini-4-argon' | 'claude-sonnet-4-5' | 'claude-opus-4-6' | 'claude-opus-4-7' | 'claude-opus-4-8' | 'claude-opus-5' | 'claude-opus-5-5' | 'claude-sonnet-4-6' | 'claude-sonnet-5' | 'claude-sonnet-5-5' | 'claude-sonnet-4' | 'claude-haiku-4-5' | 'claude-haiku-5-5' | 'claude-3-7-sonnet' | 'claude-3-5-sonnet' | 'claude-3-5-sonnet-v1' | 'claude-3-haiku' | 'grok-beta' | 'custom-llm' | 'qwen3-4b' | 'qwen3-30b-a3b' | 'qwen36-35b-a3b' | 'qwen35-397b-a17b' | 'gpt-oss-20b' | 'gpt-oss-120b' | 'glm-45-air-fp8' | 'glm-52' | 'deepseek-v41-flash' | 'nemotron-35-super-vl-nvfp4' | 'gemini-2.5-flash-preview-09-2025' | 'gemini-2.5-flash-lite-preview-09-2025' | 'gemini-2.5-flash-preview-05-20' | 'gemini-2.5-flash-preview-04-17' | 'gemini-2.5-flash-lite-preview-06-17' | 'gemini-2.0-flash-lite-001' | 'gemini-2.0-flash-001' | 'gemini-1.5-flash-002' | 'gemini-1.5-flash-001' | 'gemini-1.5-pro-002' | 'gemini-1.5-pro-001' | 'claude-sonnet-4@20250514' | 'claude-sonnet-4-5@20250929' | 'claude-haiku-4-5@20251001' | 'claude-3-7-sonnet@20250219' | 'claude-3-5-sonnet@20240620' | 'claude-3-5-sonnet-v2@20241022' | 'claude-3-haiku@20240307' | 'gpt-5-2025-08-07' | 'gpt-5.1-2025-11-13' | 'gpt-5.2-2025-12-11' | 'gpt-5.4-2026-03-05' | 'gpt-5.4-mini-2026-03-17' | 'gpt-5.4-nano-2026-03-17' | 'gpt-5.5-2026-04-23' | 'gpt-5-mini-2025-08-07' | 'gpt-5-nano-2025-08-07' | 'gpt-4.1-2025-04-14' | 'gpt-4.1-mini-2025-04-14' | 'gpt-4.1-nano-2025-04-14' | 'gpt-4o-mini-2024-07-18' | 'gpt-4o-2024-11-20' | 'gpt-4o-2024-08-06' | 'gpt-4o-2024-05-13' | 'gpt-4-0613' | 'gpt-4-0314' | 'gpt-4-turbo-2024-04-09' | 'gpt-3.5-turbo-0125' | 'gpt-3.5-turbo-1106' | 'watt-tool-8b' | 'watt-tool-70b', nullable: The LLM to query with the prompt and the chat history. If using data residency, the LLM must be supported in the data residency environment
            - `reasoning_effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', nullable: Reasoning effort of the model. Only available for some models.
            - `tool_ids` string[], nullable: A list of IDs of tools used by the agent
            - `tool_ids_strict` boolean, nullable: Only applies as a conversation override, allowed whenever tool_ids may be overridden. When true, the overridden tool_ids is the full list of tools allowed in the conversation, including tools on workflow nodes. Ignored when set on the agent.
            - `native_mcp_server_ids` string[], nullable: A list of Native MCP server ids to be used by the agent
            - `knowledge_base` KnowledgeBaseLocator[], nullable: A list of knowledge bases to be used by the agent
              - …
      - `custom_llm_extra_body` object
      - `user_id` string, nullable: ID of the end user participating in this conversation (for agent owner's user identification)
      - `source_info` ConversationInitiationSourceInfo: Information about the source of conversation initiation
        - `source` 'unknown' | 'android_sdk' | 'node_js_sdk' | 'react_native_sdk' | 'react_sdk' | 'js_sdk' | 'python_sdk' | 'widget' | 'sip_trunk' | 'twilio' | 'exotel' | 'genesys' | 'avaya' | 'audiocodes' | 'swift_sdk' | 'whatsapp' | 'twilio_sms' | 'flutter_sdk' | 'zendesk_integration' | 'slack_integration' | 'telegram_integration' | 'intercom_integration' | 'freshdesk_integration' | 'salesforce_integration' | 'template_preview' | 'genesys_bot_connector' | 'subagent_tool': Enum representing the possible sources for conversation initiation.
        - `version` string, nullable: The SDK version number
      - `branch_id` string, nullable: ID of the agent branch to use for this conversation
      - `environment` string, nullable: Environment to use for resolving environment variables
      - `starting_workflow_node_id` string, nullable: If set, start the workflow at this node id instead of the default entry
      - `procedure_ids` string[], nullable: If set, only these procedures are available to the starting agent. Each ID must be attached to that agent; unknown IDs fail conversation start. An empty list disables all of that agent's procedures. Not applied after an agent transfer. Requires enable_procedure_ids_from_client.
      - `start_procedure_ids` string[], nullable: If set, these free-form procedures start when the conversation starts. Accepts at most five IDs. Each ID must be available after procedure_ids is applied. Unknown IDs and structured procedures fail conversation start. Requires enable_procedure_ids_from_client.
      - `dynamic_variables` object
  - `scheduled_time_unix` integer, nullable: When to start calling; omit to start now. Calls still wait for the next calling window.
  - `timezone` string, nullable: IANA timezone to read the calling windows in, overriding the policy's.
  - `branch_id` string, nullable: The agent branch to call with.
  - `environment` string, nullable: The environment to resolve the agent's environment variables in.
  - `target_concurrency_limit` integer, nullable: The most calls to place at once.
  - `idempotency_key` string, nullable: Makes the request safe to retry: a repeat with the same key returns the campaign it created.
  - `policy` PolicyConfigInput
    - `timezone` string: IANA timezone the calling periods are read in.
    - `retry` RetryPolicy
      - `retry_delay_seconds` integer: How long to wait before a short retry.
      - `max_short_retries` integer: Retries a calling window allows after a failed call. Once used up, the next retry waits for the following window, which starts afresh.
      - `max_total_calls` integer: The most calls a lead gets, counting the first.
      - `max_callbacks` integer: The most callbacks to honor for one number.
      - `max_redirects` integer: The most times a lead follows a request to call another number.
      - `interval_placement` 'start' | 'random' | 'rotate'
      - `rotate_step_seconds` integer: How far `rotate` placement moves each call. Only used by `rotate`.
      - `max_consecutive_failures_per_number` integer, nullable: Calls to one number that may fail in a row before the lead moves on to its next listed number, or ends when there is none. An answered call, or a redirect to a new number, restarts the count. Unset leaves only `max_total_calls`.
    - `calling_periods` CallingPeriod[]: The weekly windows calls may be placed in.
      - `weekdays` integer[], required: Days the intervals apply on, from `0` (Monday) to `6` (Sunday).
      - `intervals` CallingIntervalPolicy[], required: Windows on each of those days. They may not overlap on any day.
        - `start` string, required: Local start time, as `HH:MM`.
        - `end` string, required: Local end time, as `HH:MM`; `24:00` ends at midnight.
    - `data_collection` DataCollectionConfig: The agent's data collection items that steer follow-up calls. Each defaults to the built-in item for its purpose; `null` turns it off.
      - `callback_time` string, nullable: The item holding when the contact asked to be called back.
      - `redirect_phone_number` string, nullable: The item holding another number the contact asked to be called on.
      - `stop` string, nullable: The item that is true when the contact asked not to be called again.
      - `mappings` object: Copies data collection results into dynamic variables for later calls: each key is a data collection item ID and its value the variable's name.
    - `followup_context` FollowupContextPolicy: Which `campaign__` dynamic variables follow-up calls get.
      - `call_type` boolean: Pass the call type as `campaign__call_type`.
      - `previous_conversation_id` boolean: Pass the last conversation's ID as `campaign__previous_conversation_id`.
      - `previous_summary` boolean: Pass the last conversation's summary as `campaign__previous_summary`.
      - `previous_transcript` boolean: Pass the last conversation's transcript as `campaign__previous_transcript`.
  - `variant` 'simple' | 'advanced'
  - `channel_config` union, required
    - PhoneChannelConfigInput
      - `channel` 'phone'
      - `agent_phone_number_id` string, required: The phone number to call from.
      - `mode_config` PhoneVoiceConfigInput
        - `ringing_timeout_secs` integer: How long to ring the recipient before giving up, in seconds. Note that this will also be limited by the provider's own constraints.
        - `twilio_call_recording_enabled` boolean: Whether to record the call using Twilio call recording. Ignored for non-Twilio providers. Recordings are stored in your Twilio account.
        - `twilio_machine_detection` TwilioMachineDetectionConfig: How to run Twilio's carrier-level answering machine detection (AMD) on a call.
          - `mode` 'enable' | 'detect_message_end': Which Twilio answering-machine-detection (AMD) mode to request for a call. `enable` returns a verdict as soon as Twilio can tell a human from a machine. `detect_message_end` additionally waits for the greeting to finish, which is what distinguishes the `machine_end_*` verdicts, at the cost of a later result.
          - `actions` TwilioMachineDetectionRule[]: Actions to take on the call per AMD verdict. Each action can appear in at most one rule, so list all of its verdicts together. Verdicts without a rule leave the call running.
            - `action` 'hang_up', required
            - `answered_by` TwilioAnsweredBy[], required: Verdicts that trigger the action.
        - `mode` 'voice'
    - SubmitWhatsAppChannelConfig
      - `channel` 'whatsapp'
      - `whatsapp_phone_number_id` string, required: The WhatsApp phone number to call or message from.
      - `mode_config` union, required
        - WhatsAppVoiceConfig
          - `mode` 'voice'
          - `whatsapp_call_permission_request_template_name` string, required: The approved template that asks the contact for permission to call.
          - `whatsapp_call_permission_request_template_language_code` string, required: The language code of that template.
        - SubmitWhatsAppMessageConfig
          - `mode` 'message'
          - `template` SubmitWhatsAppTemplateRef, required: Names the approved Meta template to send. The server loads the template itself, so the client never supplies its components.
            - `name` string, required
            - `language` string, required: The template's language code, such as `en_US`.

## Response `200`

Successful Response

- SubmitCampaignResponse
  - `campaign` CampaignResponse, required
    - `campaign_id` string, required
    - `call_name` string, required: The campaign's name.
    - `agent_id` string, required
    - `channel_config` union, required
      - PhoneChannelConfigOutput
        - `channel` 'phone'
        - `agent_phone_number_id` string, required: The phone number to call from.
        - `mode_config` PhoneVoiceConfigOutput
          - `ringing_timeout_secs` integer: How long to ring the recipient before giving up, in seconds. Note that this will also be limited by the provider's own constraints.
          - `twilio_call_recording_enabled` boolean: Whether to record the call using Twilio call recording. Ignored for non-Twilio providers. Recordings are stored in your Twilio account.
          - `twilio_machine_detection` TwilioMachineDetectionConfig: How to run Twilio's carrier-level answering machine detection (AMD) on a call.
            - `mode` 'enable' | 'detect_message_end': Which Twilio answering-machine-detection (AMD) mode to request for a call. `enable` returns a verdict as soon as Twilio can tell a human from a machine. `detect_message_end` additionally waits for the greeting to finish, which is what distinguishes the `machine_end_*` verdicts, at the cost of a later result.
            - `actions` TwilioMachineDetectionRule[]: Actions to take on the call per AMD verdict. Each action can appear in at most one rule, so list all of its verdicts together. Verdicts without a rule leave the call running.
              - …
          - `mode` 'voice'
      - WhatsAppChannelConfig
        - `channel` 'whatsapp'
        - `whatsapp_phone_number_id` string, required: The WhatsApp phone number to call or message from.
        - `mode_config` union, required
          - WhatsAppVoiceConfig
            - `mode` 'voice'
            - `whatsapp_call_permission_request_template_name` string, required: The approved template that asks the contact for permission to call.
            - `whatsapp_call_permission_request_template_language_code` string, required: The language code of that template.
          - WhatsAppMessageConfig
            - `mode` 'message'
            - `template` WhatsAppTemplate, required
              - …
    - `status` 'active' | 'paused' | 'stopping' | 'stopped' | 'completed' | 'failed' | 'attention', required
    - `policy` CampaignPolicySnapshot, required: The policy the campaign took when it was created, laid out like a submitted `policy`.
      - `timezone` string, required
      - `retry` RetryPolicy, required
        - `retry_delay_seconds` integer: How long to wait before a short retry.
        - `max_short_retries` integer: Retries a calling window allows after a failed call. Once used up, the next retry waits for the following window, which starts afresh.
        - `max_total_calls` integer: The most calls a lead gets, counting the first.
        - `max_callbacks` integer: The most callbacks to honor for one number.
        - `max_redirects` integer: The most times a lead follows a request to call another number.
        - `interval_placement` 'start' | 'random' | 'rotate'
        - `rotate_step_seconds` integer: How far `rotate` placement moves each call. Only used by `rotate`.
        - `max_consecutive_failures_per_number` integer, nullable: Calls to one number that may fail in a row before the lead moves on to its next listed number, or ends when there is none. An answered call, or a redirect to a new number, restarts the count. Unset leaves only `max_total_calls`.
      - `calling_periods` CallingPeriodPolicy[], required
        - `weekdays` integer[], required
        - `intervals` CallingIntervalPolicy[], required: Windows on each of those days. They may not overlap on any day.
          - `start` string, required: Local start time, as `HH:MM`.
          - `end` string, required: Local end time, as `HH:MM`; `24:00` ends at midnight.
      - `data_collection` DataCollectionPolicy, required
        - `callback_time` string, nullable
        - `redirect_phone_number` string, nullable
        - `stop` string, nullable
        - `mappings` object: Copies data collection results into dynamic variables for later calls: each key is a data collection item ID and its value the variable's name.
      - `followup_context` FollowupContextPolicy, required: Which `campaign__` dynamic variables follow-up calls get.
        - `call_type` boolean: Pass the call type as `campaign__call_type`.
        - `previous_conversation_id` boolean: Pass the last conversation's ID as `campaign__previous_conversation_id`.
        - `previous_summary` boolean: Pass the last conversation's summary as `campaign__previous_summary`.
        - `previous_transcript` boolean: Pass the last conversation's transcript as `campaign__previous_transcript`.
    - `variant` 'simple' | 'advanced', required
    - `source` 'ui' | 'api', required
    - `created_at_unix` integer, required
    - `scheduled_time_unix` integer, nullable, required: When the campaign starts calling; unset to start once created.
    - `updated_at_unix` integer, required
    - `branch_id` string, nullable, required: The agent branch the campaign calls with.
    - `environment` string, nullable, required: The environment the agent's environment variables resolve in.
    - `target_concurrency_limit` integer, nullable, required: The most calls the campaign places at once.
    - `channel` 'phone' | 'whatsapp', required
    - `mode` 'voice' | 'message', required
    - `counts` CampaignSummaryCounts, required
      - `leads` integer, required
      - `terminal_leads` integer, required: Leads that won't be called again.
      - `open_attention` integer, required: Attention items not yet resolved.
      - `delivery` RecipientDeliveryCounts
        - `sent` integer
        - `delivered` integer
        - `read` integer
        - `replied` integer
        - `failed` integer
    - `agent_name` string, required
  - `created` boolean, required: False when the request repeated an earlier one and returned its campaign.
  - `within_calling_window` boolean, required: Whether calling starts right away rather than at the next calling window.

## Other responses

- `422`: Validation Error

## Changes

- **2026-11-10** `5803fbabfb60`: 1 breaking, 1 warning
  - removed the required property `campaign/outcome` from the response with the `200` status
  - removed the request property `outcome`
- **2026-11-10** `49e0431bea4c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation/changes/v1/convai/outbound-campaigns/campaigns/submit/post.md)

---

[API](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation.md) - [All operations](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation/revisions/df388a25226b?raw)