> ## Documentation Index
> Fetch the complete documentation index at: https://api.scalysis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an Outbound Campaign — POST /api/v1/campaigns

> Create a bulk AI calling campaign by supplying a contact list or CSV data, a script ID, and optional scheduling and concurrency settings.

Use this endpoint to create a bulk outbound calling campaign that will dial multiple contacts using the Scalysis AI engine. You can supply contacts either as a structured JSON array or as a raw CSV string — whichever fits your workflow. Campaigns are created in a paused state by default, giving you the opportunity to review settings before starting, unless you explicitly set `startImmediately` to `true`.

**Endpoint**

```text theme={null}
POST https://app.scalysis.com/api/v1/campaigns
```

**Authentication**

Include your API key in the request using either the `Authorization` header as a Bearer token or the `X-API-Key` header.

```text theme={null}
Authorization: Bearer <your_api_key>
```

```text theme={null}
X-API-Key: <your_api_key>
```

***

## Request Body

<ParamField body="scriptId" type="number" required>
  The numeric ID of the AI agent script to use for every call in this campaign.
</ParamField>

<ParamField body="contacts" type="array">
  An array of contact objects to dial. Required if you are not providing `csvText`. Each object represents one outbound call.

  <Expandable title="contact object fields">
    <ParamField body="customerPhone" type="string" required>
      The contact's phone number, including country code (e.g. `+14155550123`).
    </ParamField>

    <ParamField body="customerName" type="string">
      The contact's full name. Used by the agent to personalise the conversation.
    </ParamField>

    <ParamField body="orderNumber" type="string">
      Your internal order or reference number for this contact.
    </ParamField>

    <ParamField body="orderNotes" type="string">
      Free-text notes about the contact or order that the agent should reference during the call.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="csvText" type="string">
  A raw CSV string containing your contact list. Required if you are not providing a `contacts` array. The CSV must include a header row. By default, Scalysis reads phone numbers from a column named `phone_number`; use `phoneColumn` to specify a different column name.
</ParamField>

<ParamField body="phoneColumn" type="string">
  The name of the CSV column that contains phone numbers. Defaults to `"phone_number"` when using `csvText`.
</ParamField>

<ParamField body="name" type="string">
  A human-readable label for the campaign, also accepted as `campaignName`. Shown in your Scalysis dashboard and included in reports.
</ParamField>

<ParamField body="kind" type="string">
  The campaign type. Accepted values are `"cod"`, `"list"`, and `"ndr"`. Defaults to `"cod"` (cash-on-delivery confirmation).
</ParamField>

<ParamField body="startImmediately" type="boolean">
  When `true`, the campaign begins dialling as soon as it is created. Defaults to `false`, which leaves the campaign in a `not_started` state until you call the [Control](/api-reference/campaigns/control) endpoint.
</ParamField>

<ParamField body="maxConcurrency" type="number">
  The maximum number of simultaneous outbound calls the campaign may place at any one time. Leave unset to use your account's default concurrency limit.
</ParamField>

***

## Example Requests

<CodeGroup>
  ```bash Contacts Array theme={null}
  curl --request POST \
    --url https://app.scalysis.com/api/v1/campaigns \
    --header 'Authorization: Bearer <your_api_key>' \
    --header 'Content-Type: application/json' \
    --data '{
      "scriptId": 2207,
      "name": "evening-demo",
      "kind": "cod",
      "startImmediately": false,
      "maxConcurrency": 5,
      "contacts": [
        {
          "customerPhone": "+14155550123",
          "customerName": "Jane Smith",
          "orderNumber": "ORD-001",
          "orderNotes": "Fragile items — handle with care"
        },
        {
          "customerPhone": "+14155550456",
          "customerName": "Bob Jones",
          "orderNumber": "ORD-002"
        }
      ]
    }'
  ```

  ```bash CSV String theme={null}
  curl --request POST \
    --url https://app.scalysis.com/api/v1/campaigns \
    --header 'Authorization: Bearer <your_api_key>' \
    --header 'Content-Type: application/json' \
    --data '{
      "scriptId": 2207,
      "name": "evening-demo",
      "kind": "cod",
      "phoneColumn": "mobile",
      "csvText": "mobile,name,order\n+14155550123,Jane Smith,ORD-001\n+14155550456,Bob Jones,ORD-002"
    }'
  ```
</CodeGroup>

***

## Response Fields

<ResponseField name="success" type="boolean">
  `true` when the campaign was successfully created.
</ResponseField>

<ResponseField name="action" type="string">
  The action performed. Always `"create_campaign"` for this endpoint.
</ResponseField>

<ResponseField name="kind" type="string">
  The campaign type that was created (e.g. `"cod"`, `"list"`, or `"ndr"`).
</ResponseField>

<ResponseField name="campaign_id" type="number">
  The unique identifier assigned to the new campaign. Save this value — you will need it to start, pause, or resume the campaign via the [Control](/api-reference/campaigns/control) endpoint.
</ResponseField>

<ResponseField name="name" type="string">
  The name assigned to the campaign.
</ResponseField>

<ResponseField name="state" type="string">
  The initial state of the campaign. Returns `"not_started"` unless `startImmediately` was `true`, in which case it returns `"running"`.
</ResponseField>

<ResponseField name="contact_count" type="number">
  The number of contacts successfully loaded into the campaign.
</ResponseField>

<ResponseField name="started" type="boolean">
  `true` if the campaign began dialling immediately upon creation.
</ResponseField>

<ResponseField name="message" type="string">
  A human-readable status message describing the outcome of the request.
</ResponseField>

***

## Example Success Response

```json theme={null}
{
  "success": true,
  "action": "create_campaign",
  "kind": "cod",
  "campaign_id": 42,
  "name": "evening-demo",
  "state": "not_started",
  "contact_count": 2,
  "started": false,
  "message": "Campaign created (paused until start)"
}
```

***

<Note>
  **2,000 contact limit per request.** A single create request supports up to approximately 2,000 contacts. If your list is larger, split it across multiple campaigns or contact Scalysis support about bulk import options.
</Note>

<Tip>
  **Save your `campaign_id`.** You will need this value to start, pause, or resume the campaign. Store it in your system as soon as you receive the creation response.
</Tip>