# Create a campaign with its leads (/api-reference/campaigns/createCampaignWithLeads)

## POST /api/v1/campaigns/create-with-leads

Operation ID: `createCampaignWithLeads`
Create a campaign with its leads
The usual way to start: one request creates the campaign and adds or creates its leads. Start it with `POST /campaigns/{campaign_id}/start`, or send `campaignData.isActive: true` to start it right away (the same checks as start apply).

### Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `Idempotency-Key` | header | no | Any unique string up to 255 characters. Retrying with the same key and body within 24 hours returns the first result instead of acting twice. |

### Request body

`application/json` (required)

```json
{
  "additionalProperties": true,
  "description": "A new campaign plus the leads to put on it.",
  "properties": {
    "campaignData": {
      "anyOf": [
        {
          "additionalProperties": true,
          "description": "Campaign fields to create or change. On update, send only the fields to change.",
          "properties": {
            "agentId": {
              "description": "The agent that makes the calls.",
              "format": "uuid",
              "title": "Agentid",
              "type": "string"
            },
            "crmWebhookSecret": {
              "description": "Secret used to sign those webhooks. Never returned.",
              "title": "Crmwebhooksecret",
              "type": "string"
            },
            "crmWebhookUrl": {
              "description": "Public HTTPS URL that receives this campaign's call results; empty clears it.",
              "format": "uri",
              "title": "Crmwebhookurl",
              "type": "string"
            },
            "description": {
              "description": "Free-text description.",
              "title": "Description",
              "type": "string"
            },
            "direction": {
              "default": "outbound",
              "description": "`outbound` (call leads) or `inbound` (answer calls).",
              "enum": [
                "outbound",
                "inbound"
              ],
              "title": "Direction",
              "type": "string"
            },
            "endDate": {
              "description": "Planned end date, free text.",
              "title": "Enddate",
              "type": "string"
            },
            "isActive": {
              "description": "Update only: `true` starts the campaign, `false` stops it (same checks as start and stop).",
              "title": "Isactive",
              "type": "boolean"
            },
            "isDefaultInbound": {
              "description": "Inbound only: take calls to the number that no other campaign matches.",
              "title": "Isdefaultinbound",
              "type": "boolean"
            },
            "name": {
              "description": "Campaign name. Defaults to `Untitled`.",
              "title": "Name",
              "type": "string"
            },
            "phoneNumberId": {
              "description": "Caller ID. Required for inbound campaigns. Defaults to the agent's assigned number.",
              "format": "uuid",
              "title": "Phonenumberid",
              "type": "string"
            },
            "phoneNumberIds": {
              "description": "Every number to call from, in order; the first is the primary caller ID.",
              "items": {
                "format": "uuid",
                "type": "string"
              },
              "title": "Phonenumberids",
              "type": "array"
            },
            "settings": {
              "anyOf": [
                {
                  "$ref": "#/components/schemas/CampaignSettings"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Dialing rules; merged into the current ones."
            },
            "startDate": {
              "description": "Planned start date, free text (for example `2026-12-01`).",
              "title": "Startdate",
              "type": "string"
            },
            "status": {
              "description": "Display status to set, for example `draft`.",
              "title": "Status",
              "type": "string"
            }
          },
          "title": "CampaignInput",
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "description": "The campaign. `name` and `agentId` are required."
    },
    "copySettingsFromCampaignId": {
      "description": "Start from another campaign's settings and webhook; `campaignData.settings` overrides them.",
      "format": "uuid",
      "title": "Copysettingsfromcampaignid",
      "type": "string"
    },
    "leadSourceType": {
      "description": "`bulk_upload` creates the leads in `uploadedLeads`; `existing_leads` adds leads you already have. Optional only for a catch-all inbound campaign.",
      "enum": [
        "bulk_upload",
        "existing_leads"
      ],
      "title": "Leadsourcetype",
      "type": "string"
    },
    "selectedLeadIds": {
      "description": "With `existing_leads`: IDs of leads to add.",
      "items": {
        "format": "uuid",
        "type": "string"
      },
      "title": "Selectedleadids",
      "type": "array"
    },
    "selectedLeadSourceIds": {
      "description": "With `existing_leads`: add every lead of these sources (used when no lead IDs are given).",
      "items": {
        "format": "uuid",
        "type": "string"
      },
      "title": "Selectedleadsourceids",
      "type": "array"
    },
    "uploadedLeads": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "description": "One lead to create (or match by phone) while creating a campaign.",
            "properties": {
              "attributes": {
                "additionalProperties": true,
                "description": "Extra fields the agent can use, for example `{\"city\": \"Pune\"}`.",
                "title": "Attributes",
                "type": "object"
              },
              "company": {
                "description": "Company.",
                "title": "Company",
                "type": "string"
              },
              "email": {
                "description": "Email address.",
                "title": "Email",
                "type": "string"
              },
              "externalId": {
                "description": "Your ID for this person.",
                "title": "Externalid",
                "type": "string"
              },
              "name": {
                "description": "Lead name.",
                "title": "Name",
                "type": "string"
              },
              "notes": {
                "description": "Added as one imported note; never replaces existing notes.",
                "title": "Notes",
                "type": "string"
              },
              "phone": {
                "description": "Phone number. Saved in E.164 form when it parses (no country code means India); otherwise saved as sent. A lead you already have with the same number is reused.",
                "title": "Phone",
                "type": "string"
              },
              "title": {
                "description": "Job title.",
                "title": "Title",
                "type": "string"
              }
            },
            "title": "CampaignLeadInput",
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "description": "With `bulk_upload`: the leads to create. Repeated numbers are added once.",
      "title": "Uploadedleads"
    }
  },
  "title": "CampaignWithLeadsInput",
  "type": "object"
}
```

Example:

```json
{
  "campaignData": {
    "agentId": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "name": "December renewals",
    "settings": {
      "maxCallsPerDay": 200
    }
  },
  "leadSourceType": "bulk_upload",
  "uploadedLeads": [
    {
      "attributes": {
        "city": "Pune"
      },
      "name": "Asha Rao",
      "phone": "+919876543210"
    }
  ]
}
```

### Responses

#### 200 OK

Example (example):

```json
{
  "campaignId": "3f6c1b2a-7d4e-4a1b-9c2d-5e6f7a8b9c0d",
  "message": "Campaign created",
  "processedLeads": 1,
  "success": true
}
```

#### 400 Bad request: `bad_request`.

Example (The request could not be processed.):

```json
{
  "detail": "The request could not be processed.",
  "error": {
    "code": "bad_request",
    "docUrl": "https://docs.callmitra.ai/errors/bad_request",
    "message": "The request could not be processed.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

#### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`.

Example (The API key has expired.):

```json
{
  "detail": "The API key has expired.",
  "error": {
    "code": "api_key_expired",
    "docUrl": "https://docs.callmitra.ai/errors/api_key_expired",
    "message": "The API key has expired.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

Example (The API key is invalid or has been revoked.):

```json
{
  "detail": "The API key is invalid or has been revoked.",
  "error": {
    "code": "invalid_api_key",
    "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key",
    "message": "The API key is invalid or has been revoked.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

Example (Authentication required.):

```json
{
  "detail": "Authentication required.",
  "error": {
    "code": "unauthenticated",
    "docUrl": "https://docs.callmitra.ai/errors/unauthenticated",
    "message": "Authentication required.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

#### 402 Payment required: `payment_required`.

Example (Your account does not have enough balance or an active plan for this request.):

```json
{
  "detail": "Your account does not have enough balance or an active plan for this request.",
  "error": {
    "code": "payment_required",
    "docUrl": "https://docs.callmitra.ai/errors/payment_required",
    "message": "Your account does not have enough balance or an active plan for this request.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "billing_error"
  }
}
```

#### 403 Forbidden: `api_key_scope_denied`, `permission_denied`.

Example (The API key does not have the scope required for this request.):

```json
{
  "detail": "The API key does not have the scope required for this request.",
  "error": {
    "code": "api_key_scope_denied",
    "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied",
    "message": "The API key does not have the scope required for this request.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

Example (You do not have permission to perform this action.):

```json
{
  "detail": "You do not have permission to perform this action.",
  "error": {
    "code": "permission_denied",
    "docUrl": "https://docs.callmitra.ai/errors/permission_denied",
    "message": "You do not have permission to perform this action.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

#### 404 Not found: `campaign_not_found`, `resource_not_found`.

Example (Campaign not found.):

```json
{
  "detail": "Campaign not found.",
  "error": {
    "code": "campaign_not_found",
    "docUrl": "https://docs.callmitra.ai/errors/campaign_not_found",
    "message": "Campaign not found.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "not_found_error"
  }
}
```

Example (The requested resource was not found.):

```json
{
  "detail": "The requested resource was not found.",
  "error": {
    "code": "resource_not_found",
    "docUrl": "https://docs.callmitra.ai/errors/resource_not_found",
    "message": "The requested resource was not found.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "not_found_error"
  }
}
```

#### 409 Conflict: `campaign_default_inbound_exists`, `idempotency_key_reused`, `idempotency_request_in_progress`.

Example (Another default inbound campaign already exists for this phone number.):

```json
{
  "detail": "Another default inbound campaign already exists for this phone number.",
  "error": {
    "code": "campaign_default_inbound_exists",
    "docUrl": "https://docs.callmitra.ai/errors/campaign_default_inbound_exists",
    "message": "Another default inbound campaign already exists for this phone number.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "conflict_error"
  }
}
```

Example (This Idempotency-Key was already used with a different request body.):

```json
{
  "detail": "This Idempotency-Key was already used with a different request body.",
  "error": {
    "code": "idempotency_key_reused",
    "docUrl": "https://docs.callmitra.ai/errors/idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request body.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "idempotency_error"
  }
}
```

Example (A request with this Idempotency-Key is still being processed.):

```json
{
  "detail": "A request with this Idempotency-Key is still being processed.",
  "error": {
    "code": "idempotency_request_in_progress",
    "docUrl": "https://docs.callmitra.ai/errors/idempotency_request_in_progress",
    "message": "A request with this Idempotency-Key is still being processed.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "idempotency_error"
  }
}
```

#### 422 Invalid parameters: `campaign_not_ready`, `parameter_invalid`.

Example (The campaign is not ready to start.):

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "phone"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ],
  "error": {
    "code": "campaign_not_ready",
    "docUrl": "https://docs.callmitra.ai/errors/campaign_not_ready",
    "message": "The campaign is not ready to start.",
    "param": "phone",
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

Example (One or more parameters are invalid.):

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "phone"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ],
  "error": {
    "code": "parameter_invalid",
    "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid",
    "message": "One or more parameters are invalid.",
    "param": "phone",
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

#### 429 Too many requests: `rate_limit_exceeded`.

Example (Too many requests. Slow down and retry later.):

```json
{
  "detail": "Too many requests. Slow down and retry later.",
  "error": {
    "code": "rate_limit_exceeded",
    "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded",
    "message": "Too many requests. Slow down and retry later.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "rate_limit_error"
  }
}
```

#### 500 Server error: `internal_error`.

Example (Something went wrong on our side.):

```json
{
  "detail": "Something went wrong on our side.",
  "error": {
    "code": "internal_error",
    "docUrl": "https://docs.callmitra.ai/errors/internal_error",
    "message": "Something went wrong on our side.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "api_error"
  }
}
```

### Error codes

- [`bad_request`](/errors/bad_request)
- [`api_key_expired`](/errors/api_key_expired)
- [`invalid_api_key`](/errors/invalid_api_key)
- [`unauthenticated`](/errors/unauthenticated)
- [`payment_required`](/errors/payment_required)
- [`api_key_scope_denied`](/errors/api_key_scope_denied)
- [`permission_denied`](/errors/permission_denied)
- [`campaign_not_found`](/errors/campaign_not_found)
- [`resource_not_found`](/errors/resource_not_found)
- [`campaign_default_inbound_exists`](/errors/campaign_default_inbound_exists)
- [`idempotency_key_reused`](/errors/idempotency_key_reused)
- [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress)
- [`campaign_not_ready`](/errors/campaign_not_ready)
- [`parameter_invalid`](/errors/parameter_invalid)
- [`rate_limit_exceeded`](/errors/rate_limit_exceeded)
- [`internal_error`](/errors/internal_error)
