> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinnest.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Campaign
> Create a new outbound campaign.
```bash cURL theme={null}
curl -X POST https://api.thinnest.ai/campaigns \
-H "Authorization: Bearer $THINNESTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Follow-up Campaign",
"agent_id": "ag_c47e7c97_b2f2",
"type": "voice",
"contacts": [
"+1234567890",
"+0987654321"
],
"message_template": "Hi {{name}}, this is a follow-up from our conversation about {{topic}}.",
"schedule": "2026-03-10T09:00:00Z",
"max_concurrent": 5
}'
```
```python Python theme={null}
import requests
url = "https://api.thinnest.ai/campaigns"
headers = {
"Authorization": "Bearer " + "YOUR_THINNESTAI_API_KEY",
"Content-Type": "application/json",
}
payload = {
"name": "Follow-up Campaign",
"agent_id": "ag_c47e7c97_b2f2",
"type": "voice",
"contacts": [
"+1234567890",
"+0987654321"
],
"message_template": "Hi {{name}}, this is a follow-up from our conversation about {{topic}}.",
"schedule": "2026-03-10T09:00:00Z",
"max_concurrent": 5
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
```javascript JavaScript theme={null}
const response = await fetch("https://api.thinnest.ai/campaigns", {
method: "POST",
headers: {
"Authorization": "Bearer " + "YOUR_THINNESTAI_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
"name": "Follow-up Campaign",
"agent_id": "ag_c47e7c97_b2f2",
"type": "voice",
"contacts": [
"+1234567890",
"+0987654321"
],
"message_template": "Hi {{name}}, this is a follow-up from our conversation about {{topic}}.",
"schedule": "2026-03-10T09:00:00Z",
"max_concurrent": 5
}),
});
const data = await response.json();
console.log(data);
```
```go Go theme={null}
package main
import (
"bytes"
"fmt"
"io"
"net/http"
)
func main() {
payload := []byte(`{
"name": "Follow-up Campaign",
"agent_id": "ag_c47e7c97_b2f2",
"type": "voice",
"contacts": [
"+1234567890",
"+0987654321"
],
"message_template": "Hi {{name}}, this is a follow-up from our conversation about {{topic}}.",
"schedule": "2026-03-10T09:00:00Z",
"max_concurrent": 5
}`)
req, _ := http.NewRequest("POST", "https://api.thinnest.ai/campaigns", bytes.NewBuffer(payload))
req.Header.Set("Authorization", "Bearer YOUR_THINNESTAI_API_KEY")
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
```
***
## Request Body
Campaign display name
Voice-enabled agent to use (ag\_\*)
Campaign type: voice, sms
List of phone numbers in E.164 format (+1234567890)
Message template with {{variable}} placeholders
ISO 8601 datetime to start the campaign
Maximum concurrent calls/messages
Outbound caller ID (must be verified)
***
## Response `201`
```json 200 theme={null}
{
"id": "camp_a1b2c3d4",
"name": "Follow-up Campaign",
"status": "draft",
"type": "voice",
"agent_id": "ag_c47e7c97_b2f2",
"total_contacts": 2,
"completed": 0,
"failed": 0,
"scheduled_at": "2026-03-10T09:00:00Z",
"created_at": "2026-03-07T14:00:00Z"
}
```
***
## Campaign Lifecycle
```
draft → launched → running → completed
↕
paused
```
Use [Launch](/api-reference/campaigns/launch), [Pause](/api-reference/campaigns/pause), and [Resume](/api-reference/campaigns/resume) to control execution.
***
## Errors
| Code | Description |
| ----- | --------------------------------- |
| `401` | Missing or invalid authentication |
| `402` | Insufficient balance for campaign |
| `404` | Agent not found |
| `422` | Invalid contacts or configuration |
## OpenAPI
````yaml POST /campaigns
openapi: 3.1.0
info:
title: ThinnestAI API
description: REST API for ThinnestAI — build, deploy, and manage AI agents.
version: 1.0.0
servers: []
security: []
tags:
- name: Agents
description: Create, configure, and manage AI agents
- name: Chat
description: Send messages and get AI responses from agents
- name: Knowledge
description: Upload files, URLs, and text to agent knowledge bases
- name: Sessions
description: View and manage chat sessions and message history
- name: Voice
description: Start and manage voice call sessions
- name: Recordings
description: Manage voice call recordings
- name: Campaigns
description: Create and run automated outreach campaigns
- name: Webhooks
description: Register webhook endpoints for real-time event notifications
- name: Evaluations
description: Run and track agent evaluation benchmarks
- name: Analytics
description: Query agent performance metrics and usage data
- name: Agent Tools
description: View and manage tools attached to agents
- name: BYOK
description: >-
Bring Your Own Key — manage credentials for LLM/STT/TTS providers,
telephony BYOK (Vobiz/Twilio/Plivo/Exotel/Telnyx), and tool-specific BYOK
(Razorpay UPI Payment, Surepass Aadhaar eKYC)
paths:
/campaigns:
post:
tags:
- Campaigns
summary: Create Campaign
description: Create a new campaign. Optionally requires KYC verification.
operationId: create_campaign_campaigns_post
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignCreateRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
CampaignCreateRequest:
properties:
name:
type: string
maxLength: 200
title: Name
description:
anyOf:
- type: string
- type: 'null'
title: Description
agent_id:
anyOf:
- type: integer
- type: string
title: Agent Id
channel:
type: string
title: Channel
default: voice
template_id:
anyOf:
- type: integer
- type: 'null'
title: Template Id
contact_group_ids:
items:
type: integer
type: array
title: Contact Group Ids
config:
anyOf:
- $ref: '#/components/schemas/CampaignConfig'
- type: 'null'
scheduled_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Scheduled At
timezone:
type: string
title: Timezone
default: Asia/Kolkata
status:
anyOf:
- type: string
- type: 'null'
title: Status
type: object
required:
- name
- agent_id
title: CampaignCreateRequest
description: Request to create a new campaign.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
CampaignConfig:
properties:
retry:
additionalProperties: true
type: object
title: Retry
voicemail:
additionalProperties: true
type: object
title: Voicemail
escalation:
additionalProperties: true
type: object
title: Escalation
calling:
additionalProperties: true
type: object
title: Calling
dndCheck:
type: boolean
title: Dndcheck
default: true
type: object
title: CampaignConfig
description: Campaign configuration options.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
````