> For the complete documentation index, see [llms.txt](https://docs.agentalk.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.agentalk.io/api-reference/campaigns.md).

# Campaigns

Manage campaigns and add contacts to campaigns

## List Campaigns

> Get all campaigns for the organization. Optionally filter by status.

````json
{"openapi":"3.0.3","info":{"title":"Agentalk External API","version":"1.0.0"},"tags":[{"name":"Campaigns","description":"Manage campaigns and add contacts to campaigns"}],"servers":[{"url":"https://api.agentalk.io","description":"Agentalk API"}],"security":[{"OrganizationApiToken":[]}],"components":{"securitySchemes":{"OrganizationApiToken":{"type":"http","scheme":"bearer","bearerFormat":"OrgId.SecretToken","description":"**Organization API Token.**\n\nPaste **only** your token in the field below — the `Bearer ` prefix is added automatically by the docs UI and in every generated code sample. The final header sent is:\n\n```\nAuthorization: Bearer {orgId}.{secretToken}\n```\n\nToken format: `{orgId}.{secretToken}` — example: `15c94c3c-1873-4a09-bfbb-03357c29ea50.abc123xyz`.\n\nJWT tokens are NOT accepted."}}},"paths":{"/api/campaigns":{"get":{"operationId":"campaigns_retrieve","description":"Get all campaigns for the organization. Optionally filter by status.","summary":"List Campaigns","parameters":[{"in":"query","name":"limit","schema":{"type":"integer"},"description":"Number of results to return (default: 50)"},{"in":"query","name":"offset","schema":{"type":"integer"},"description":"Offset for pagination (default: 0)"},{"in":"query","name":"status","schema":{"type":"string"},"description":"Filter by status (active, paused, stopped, completed, draft)"}],"tags":["Campaigns"],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}},"description":"List of campaigns"}}}}}}
````

## Create Campaign

> Create a new outbound campaign in \`draft\` status. Activate it afterwards with \`POST /api/campaigns/{campaignId}/start\`, and add contacts with \`POST /api/campaigns/{campaignId}/contacts\`.\
> \
> Only \`name\` is required. The campaign timezone is always taken from the organization settings and cannot be set here. \`maxParallelCalls\` may not exceed the concurrent-call limit of the organization's current plan.

````json
{"openapi":"3.0.3","info":{"title":"Agentalk External API","version":"1.0.0"},"tags":[{"name":"Campaigns","description":"Manage campaigns and add contacts to campaigns"}],"servers":[{"url":"https://api.agentalk.io","description":"Agentalk API"}],"security":[{"OrganizationApiToken":[]}],"components":{"securitySchemes":{"OrganizationApiToken":{"type":"http","scheme":"bearer","bearerFormat":"OrgId.SecretToken","description":"**Organization API Token.**\n\nPaste **only** your token in the field below — the `Bearer ` prefix is added automatically by the docs UI and in every generated code sample. The final header sent is:\n\n```\nAuthorization: Bearer {orgId}.{secretToken}\n```\n\nToken format: `{orgId}.{secretToken}` — example: `15c94c3c-1873-4a09-bfbb-03357c29ea50.abc123xyz`.\n\nJWT tokens are NOT accepted."}}},"paths":{"/api/campaigns":{"post":{"operationId":"campaigns_create","description":"Create a new outbound campaign in `draft` status. Activate it afterwards with `POST /api/campaigns/{campaignId}/start`, and add contacts with `POST /api/campaigns/{campaignId}/contacts`.\n\nOnly `name` is required. The campaign timezone is always taken from the organization settings and cannot be set here. `maxParallelCalls` may not exceed the concurrent-call limit of the organization's current plan.","summary":"Create Campaign","tags":["Campaigns"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Campaign name (required)"},"voicebotId":{"type":"string","format":"uuid","description":"Voicebot UUID used for outbound calls"},"phoneNumberIds":{"type":"array","items":{"type":"integer"},"description":"Phone number integration IDs to dial from (from GET /api/account/phone-numbers). Empty = use all voicebot numbers."},"fromDate":{"type":"string","format":"date-time","description":"Campaign window start (ISO 8601)"},"toDate":{"type":"string","format":"date-time","description":"Campaign window end (ISO 8601)"},"startTime":{"type":"string","description":"Daily call window start time (HH:MM, in the organization timezone)"},"endTime":{"type":"string","description":"Daily call window end time (HH:MM, in the organization timezone)"},"activeDays":{"type":"array","items":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"]},"description":"Weekdays the campaign is allowed to dial. Empty = all days."},"maxParallelCalls":{"type":"integer","description":"Max concurrent calls (must not exceed plan limit)"},"maxAttemptsPerContact":{"type":"integer","description":"Max dial attempts per contact"},"retryIntervalMinutes":{"type":"integer","description":"Minutes to wait before retrying a failed call"},"campaignGoal":{"type":"string","enum":["lead_goal","outreach","birthday"],"description":"Campaign goal (optional)"}},"required":["name"]}}}},"responses":{"201":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}},"description":"Campaign created (draft)"},"400":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}},"description":"Validation error (e.g. maxParallelCalls exceeds plan limit)"}}}}}}
````

## Add Contacts to Campaign

> Add one or more contacts to a campaign. Returns summary of added, reset (already in campaign, status reset), and invalid contacts.\
> \
> Use \`contacts\` to set an optional per-contact follow-up time (\`followUpAt\`, ISO 8601). The dialer will not call the contact before that time. \`contactIds\` (plain ID array, no follow-up) is still supported for backward compatibility; at least one of the two fields is required.

````json
{"openapi":"3.0.3","info":{"title":"Agentalk External API","version":"1.0.0"},"tags":[{"name":"Campaigns","description":"Manage campaigns and add contacts to campaigns"}],"servers":[{"url":"https://api.agentalk.io","description":"Agentalk API"}],"security":[{"OrganizationApiToken":[]}],"components":{"securitySchemes":{"OrganizationApiToken":{"type":"http","scheme":"bearer","bearerFormat":"OrgId.SecretToken","description":"**Organization API Token.**\n\nPaste **only** your token in the field below — the `Bearer ` prefix is added automatically by the docs UI and in every generated code sample. The final header sent is:\n\n```\nAuthorization: Bearer {orgId}.{secretToken}\n```\n\nToken format: `{orgId}.{secretToken}` — example: `15c94c3c-1873-4a09-bfbb-03357c29ea50.abc123xyz`.\n\nJWT tokens are NOT accepted."}}},"paths":{"/api/campaigns/{campaign_id}/contacts":{"post":{"operationId":"campaigns_contacts_create","description":"Add one or more contacts to a campaign. Returns summary of added, reset (already in campaign, status reset), and invalid contacts.\n\nUse `contacts` to set an optional per-contact follow-up time (`followUpAt`, ISO 8601). The dialer will not call the contact before that time. `contactIds` (plain ID array, no follow-up) is still supported for backward compatibility; at least one of the two fields is required.","summary":"Add Contacts to Campaign","parameters":[{"in":"path","name":"campaign_id","schema":{"type":"string","format":"uuid"},"description":"Campaign ID","required":true}],"tags":["Campaigns"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"contacts":{"type":"array","description":"Contacts to add, each with an optional follow-up time","items":{"type":"object","properties":{"contactId":{"type":"string","description":"Contact ID (required)"},"followUpAt":{"type":"string","format":"date-time","description":"Optional follow-up time (ISO 8601). The contact will not be dialed before this time."}},"required":["contactId"]}},"contactIds":{"type":"array","items":{"type":"string"},"description":"Array of contact IDs to add (no follow-up). Provide this or `contacts`."}}}}}},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}},"description":"Summary of operation"}}}}}}
````

## Start Campaign

> Start (activate) a campaign. Optionally schedule it for a future time.

````json
{"openapi":"3.0.3","info":{"title":"Agentalk External API","version":"1.0.0"},"tags":[{"name":"Campaigns","description":"Manage campaigns and add contacts to campaigns"}],"servers":[{"url":"https://api.agentalk.io","description":"Agentalk API"}],"security":[{"OrganizationApiToken":[]}],"components":{"securitySchemes":{"OrganizationApiToken":{"type":"http","scheme":"bearer","bearerFormat":"OrgId.SecretToken","description":"**Organization API Token.**\n\nPaste **only** your token in the field below — the `Bearer ` prefix is added automatically by the docs UI and in every generated code sample. The final header sent is:\n\n```\nAuthorization: Bearer {orgId}.{secretToken}\n```\n\nToken format: `{orgId}.{secretToken}` — example: `15c94c3c-1873-4a09-bfbb-03357c29ea50.abc123xyz`.\n\nJWT tokens are NOT accepted."}}},"paths":{"/api/campaigns/{campaign_id}/start":{"post":{"operationId":"campaigns_start_create","description":"Start (activate) a campaign. Optionally schedule it for a future time.","summary":"Start Campaign","parameters":[{"in":"path","name":"campaign_id","schema":{"type":"string","format":"uuid"},"description":"Campaign ID","required":true}],"tags":["Campaigns"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"startAt":{"type":"string","format":"date-time","description":"ISO 8601 timestamp to schedule start (optional)"}}}}}},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}},"description":"Campaign started successfully"}}}}}}
````


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.agentalk.io/api-reference/campaigns.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.