> ## Documentation Index > Fetch the complete documentation index at: https://docs.starleads.co/llms.txt > Use this file to discover all available pages before exploring further. # Create a campaign > Creates a new campaign associated with an AI agent. The campaign is created in an inactive state (`isActive: false`). A phone number is required when the agent's channel is `Phone`. Default values are applied for optional fields not provided. ## OpenAPI ````yaml /api-reference/openapi.json post /Campaign openapi: 3.0.1 info: title: Starleads public API documentation description: > Welcome to the Starleads Public API documentation. This API provides public access to Starleads services, allowing developers and growth-hackers to interact with campaign-related data. *** ### Base endpoint ```https://api.starleads.co``` *** ### Errors The API uses standard HTTP status codes to indicate the success or failure of the API call. In case of failure, the body of the response will be JSON in the following format: ``` { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "No campaign exists with campaignId : 11111111" } ``` The ```type``` property is a link to a general description of the error type. *** ### Authentification Authentication for the API is handled with an API key that must be provided as a ```X-Api-Key``` header for every request.
**API keys are supposed to be a secret that only the client and server know. Please remember to not share them with anyone.**
You can find your API keys when authenticated in your Starleads profile :
![Api key menu option](../images/api-menu-option-screenshot.png) version: v1 x-logo: url: https://api.starleads.co/images/starleads-logo.png servers: [] security: [] tags: - name: Agent description: >- Manage your AI agent's prompt and knowledge base chat connection. These endpoints allow you to read and update the prompt that drives your agent's behavior, and connect or detach a knowledge base chat. - name: Campaign description: >- Manage campaigns. A campaign orchestrates outbound calls or web interactions using an AI agent. Campaigns are created inactive and can be activated separately. - name: CampaignField description: >- CampaignFields enables users to specify customizable fields within their campaigns. These fields serve as placeholders (e.g., ```{lastname}```) that can be dynamically filled with corresponding data when creating prompts, providing flexibility in tailoring campaign content based on specific variables.
**Those are the keys of the ```databag``` field of the request payload to add a new ```CampaignItem``` to a campaign.** - name: CampaignItem description: Represents prospects entries related to a campaign - name: Dataset description: >- Manage datasets for the RAG (Retrieval-Augmented Generation) knowledge base. Datasets are containers for documents that are parsed and used for knowledge retrieval by AI agents. - name: Document description: >- Manage documents within datasets. Upload, list, update, download, and delete documents. Trigger and stop document parsing to extract knowledge from uploaded files. - name: KnowledgeBaseChat description: >- Manage knowledge base chats. A chat connects one or more datasets to provide RAG-powered question answering. Chats can be connected to agents to enhance their capabilities with knowledge retrieval. - name: KnowledgeGraph description: >- Manage knowledge graphs on datasets. Enable, build, query, and delete knowledge graphs to extract structured entity relationships from dataset documents. Available on the Business plan. paths: /Campaign: post: tags: - Campaign summary: Create a campaign description: >- Creates a new campaign associated with an AI agent. The campaign is created in an inactive state (`isActive: false`). A phone number is required when the agent's channel is `Phone`. Default values are applied for optional fields not provided. operationId: CreateCampaign parameters: - name: X-Api-Key in: header description: >- Api key to pass as a ```X-Api-Key``` request header. You can get yours in your profile when authenticated in [Starleads](https://app.starleads.co/) required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCampaignRequest' example: name: My prospecting campaign agentId: agent-123-abc phoneNumber: '+33123456789' maxRetries: 3 delayBetweenRetries: 2 webhookUrl: https://example.com/webhook timezone: Europe/Paris schedule: - day: Monday timeRanges: - startTime: '09:00:00' endTime: '12:00:00' - startTime: '14:00:00' endTime: '17:00:00' responses: '201': description: Campaign created successfully content: application/json: schema: $ref: '#/components/schemas/CreateCampaignResponse' '400': description: >- Bad Request — validation error (missing name, invalid phoneNumber, maxRetries out of range, invalid webhookUrl, or schedule conflict) content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' '401': description: Unauthorized — invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' '404': description: Not Found — agent does not exist or does not belong to your company content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' components: schemas: CreateCampaignRequest: required: - name - agentId type: object description: Request payload to create a new campaign properties: name: type: string description: Name of the campaign agentId: type: string description: ID of the AI agent to associate with the campaign phoneNumber: type: string description: >- Outbound phone number. Required if the agent channel is Phone. Must belong to the company's phone number list nullable: true maxRetries: type: integer format: int32 description: 'Maximum number of call retries (default: 3, min: 1, max: 4)' minimum: 1 maximum: 4 nullable: true delayBetweenRetries: type: number format: double description: 'Delay between retries in hours (default: 2). Must be greater than 0' nullable: true webhookUrl: type: string description: >- Webhook URL to receive campaign events. Must be a valid HTTP/HTTPS URL nullable: true timezone: type: string description: 'Timezone identifier (default: "Europe/Paris")' nullable: true schedule: type: array items: $ref: '#/components/schemas/DaySchedule' description: >- Campaign schedule. Defaults to Monday-Friday 09:00-12:00 / 14:00-17:00 if not provided nullable: true additionalProperties: false CreateCampaignResponse: type: object description: Response returned after a campaign is successfully created properties: id: type: string description: Unique identifier of the created campaign name: type: string description: Name of the campaign agentId: type: string description: ID of the AI agent associated with the campaign phoneNumber: type: string description: Outbound phone number (null for web agents) nullable: true maxRetries: type: integer format: int32 description: Maximum number of retry attempts (between 1 and 4) delayBetweenRetries: type: number format: double description: Delay between retry attempts in hours webhookUrl: type: string description: Webhook URL for campaign event notifications nullable: true country: type: string description: Country code (always FR) timezone: type: string description: Timezone identifier (e.g. Europe/Paris) schedule: type: array items: $ref: '#/components/schemas/DaySchedule' description: Weekly schedule defining the calling time slots isActive: type: boolean description: Whether the campaign is active (always false at creation) additionalProperties: false ProblemDetails: type: object properties: type: type: string nullable: true title: type: string nullable: true status: type: integer format: int32 nullable: true detail: type: string nullable: true instance: type: string nullable: true additionalProperties: {} DaySchedule: required: - day - timeRanges type: object description: Schedule definition for a specific day of the week properties: day: type: string description: Day of the week enum: - Sunday - Monday - Tuesday - Wednesday - Thursday - Friday - Saturday timeRanges: type: array items: $ref: '#/components/schemas/TimeRange' description: >- List of time ranges for this day. At least one time range is required additionalProperties: false TimeRange: required: - startTime - endTime type: object description: A time range defined by a start time and an end time properties: startTime: type: string description: 'Start time of the range (format: HH:mm:ss)' example: '09:00:00' endTime: type: string description: >- End time of the range (format: HH:mm:ss). Must be greater than startTime example: '12:00:00' additionalProperties: false ````