> ## Documentation Index > Fetch the complete documentation index at: https://docs.vocobase.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a campaign > Creates an outbound campaign in `draft` status. Nothing dials until you add contacts and call `POST /campaigns/{id}/start`. Supply caller IDs with `phone_number_ids` (preferred — the campaign rotates through them in order) **or** a single legacy `provider`. Sending both fails unless they agree. ## OpenAPI ````yaml /openapi.json post /campaigns openapi: 3.1.0 info: title: Vocobase API version: '2.0' description: >- API for managing voice AI agents, documents, and calls on the Vocobase platform. servers: - url: https://api.vocobase.com/api/v2 description: Production security: - bearerAuth: [] tags: - name: Config description: >- Read and update account configuration, webhook settings, and telephony credentials. - name: Agents description: Create, read, update, and delete voice AI agents. - name: Voices description: >- List voice tiers, available voices, and stream preview audio for agent configuration. - name: Documents description: Upload, manage, and delete knowledge base documents. - name: Agent Documents description: Link and unlink documents to agents for knowledge base integration. - name: Calls description: Initiate outbound calls and view call history. - name: Phone Numbers description: >- Import DIDs, assign agents for inbound routing, and re-sync carrier Application bindings. - name: Inbound Routing Policies description: >- Define pre-answer routing decisions for inbound calls before AI sessions are created. - name: Telephony Connections description: Create, list, rename, and disconnect named V2 telephony connections. - name: VoiceLink Management description: Manage VoiceLink reseller clients, DID mapping, and readiness sync. - name: Projects description: Organize agents into projects. Every agent belongs to exactly one project. - name: Dictionaries description: Speech-recognition dictionary CRUD and agent attachment. - name: Sessions description: Browser-initiated WebRTC voice sessions for in-app voice agents. - name: Campaigns description: Batch outbound calling. - name: Billing description: Balance, transactions, and usage summaries. - name: Custom Functions description: HTTP endpoints the agent can call mid-conversation. - name: Extraction Sets description: Reusable sets of post-call extraction fields. - name: Lifecycle Hooks description: Automatic pre-call and post-call integration steps. - name: Messaging description: Bring-your-own WhatsApp sending. - name: Integration Logs description: Audit trail for integration calls. - name: Connectors description: Catalog of tools an agent can be connected to. - name: Customers description: B2B2B sub-tenants and their tool connections. - name: Agent Tools description: Binding connectors and connections to an agent. paths: /campaigns: post: tags: - Campaigns summary: Create a campaign description: >- Creates an outbound campaign in `draft` status. Nothing dials until you add contacts and call `POST /campaigns/{id}/start`. Supply caller IDs with `phone_number_ids` (preferred — the campaign rotates through them in order) **or** a single legacy `provider`. Sending both fails unless they agree. operationId: createCampaign requestBody: required: true content: application/json: schema: type: object required: - name - agent_id properties: name: type: string description: Required. Non-empty. description: type: string nullable: true agent_id: type: string format: uuid description: Required. Must be an active agent on your account. type: type: string enum: - OUTBOUND default: OUTBOUND description: '`INBOUND` campaigns are not available on the API yet.' phone_number_ids: type: array items: type: string format: uuid description: >- Imported numbers to dial from. Each must be active, owned by you, and voice-capable. provider: type: string enum: - twilio - exotel - mcube - tata_smartflo description: >- Legacy alternative to `phone_number_ids`. Required when `phone_number_ids` is omitted. `tata_smartflo` is rejected — Smartflo does not support streaming voice bots on campaigns. concurrency_limit: type: integer description: Simultaneous first-attempt calls. retry_concurrency: type: integer description: Simultaneous retry calls. retry_count: type: integer description: Retries per contact after the first call. cooldown_minutes: type: integer description: Fixed wait between retries. retry_delays_minutes: type: array items: type: integer description: Per-attempt waits. Overrides `cooldown_minutes`. callback_enabled: type: boolean default: true description: Set `false` to stop calls asking for a callback time. example: name: March renewals agent_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 phone_number_ids: - pn_1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f concurrency_limit: 10 retry_count: 2 retry_delays_minutes: - 30 - 240 responses: '201': description: Campaign created in draft status. content: application/json: schema: type: object properties: success: type: boolean const: true data: $ref: '#/components/schemas/Campaign' example: success: true data: campaign_id: cmp_7f3a1b02-4d5e-4c11-9a88-2e6f0c4d1a90 name: March renewals description: Outbound renewal reminders agent_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 agent_name: Renewals Agent provider: null type: outbound phone_numbers: - phone_number_id: pn_1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f phone_number: '+918065480085' concurrency_limit: 10 retry_concurrency: 3 retry_count: 2 cooldown_minutes: 60 retry_delays_minutes: - 30 - 240 callback_enabled: true status: draft total_contacts: 0 completed_count: 0 failed_count: 0 skipped_count: 0 started_at: null paused_at: null completed_at: null created_at: '2026-08-19T16:41:00.000Z' '400': description: >- `VALIDATION_ERROR` for a missing or malformed field, a provider that does not match the supplied numbers, or a number that is inactive or not voice-capable. `PROVIDER_NOT_CONFIGURED` when the account has no credentials for the chosen provider. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: PROVIDER_NOT_CONFIGURED message: >- Twilio telephony is not configured for this partner. Contact support. '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimitExceeded' '500': $ref: '#/components/responses/InternalError' components: schemas: Campaign: type: object properties: campaign_id: type: string format: uuid name: type: string description: type: string nullable: true agent_id: type: string format: uuid agent_name: type: string nullable: true provider: type: string nullable: true description: >- Legacy single-provider value. `null` on campaigns created with `phone_number_ids`. type: type: string enum: - outbound description: Only `outbound` is available on the API today. phone_numbers: type: array description: Caller IDs this campaign dials from, in dial order. items: type: object properties: phone_number_id: type: string format: uuid phone_number: type: string nullable: true concurrency_limit: type: integer description: Maximum simultaneous first-attempt calls. retry_concurrency: type: integer description: Maximum simultaneous retry calls. retry_count: type: integer description: Retries attempted per contact after the first call. cooldown_minutes: type: integer description: Fixed wait between retries, when `retry_delays_minutes` is not set. retry_delays_minutes: type: array nullable: true items: type: integer description: Per-attempt wait times. Overrides `cooldown_minutes` when present. callback_enabled: type: boolean description: >- Whether calls ask the lead for a callback time and re-queue them for it. Defaults to `true`; this is the opt-out. status: type: string enum: - draft - running - paused - completed - cancelled - credit_exhausted total_contacts: type: integer completed_count: type: integer failed_count: type: integer skipped_count: type: integer started_at: type: string format: date-time nullable: true paused_at: type: string format: date-time nullable: true completed_at: type: string format: date-time nullable: true created_at: type: string format: date-time ErrorResponse: type: object properties: success: type: boolean const: false error: type: object properties: code: type: string message: type: string required: - code - message required: - success - error responses: Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing API key NotFound: description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: NOT_FOUND message: Resource not found RateLimitExceeded: description: Per-account rate limit exceeded. Retry after a short backoff. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: RATE_LIMITED message: Rate limit exceeded. Retry after 60 seconds. InternalError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INTERNAL_ERROR message: An unexpected error occurred securitySchemes: bearerAuth: type: http scheme: bearer description: >- API key in format: `rg_live_xxxx`. Pass as a Bearer token in the Authorization header. ````