# Quickstart

This guide takes you from nothing to a scheduled campaign: you send contacts to the API, and the campaign starts for them at the time you choose. The campaign itself, with its messages and calls, is built in Wiraya first.

## Before you start

You need:

- A Wiraya user with **administrator** rights in your organization. Only administrators can see Organizational Settings and create API tokens.
- A campaign in Wiraya that you want to start for the contacts you send.


## Step 1: Create an API token

1. Log in to Wiraya.
2. In the left menu, under **Settings**, click **Organizational Settings**.
3. Open the **Integration** tab.
4. In the **API Tokens** section, click **New API Token**.
5. Give the token a name that tells you where it is used, for example `CRM integration`, and click **Add API Token**.
6. Copy the token and store it somewhere safe, such as your secrets manager. **The token is shown only once.** Then click **Ok, I've copied my API token**.


If a token is lost or leaked, delete it in the same list and create a new one.

### Using your API token

Every API request must include the token in the `Authorization` header:

```http
Authorization: Bearer {API_TOKEN}
```

Example:

```http
Authorization: Bearer 293|eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0
```

## Step 2: Find your group ID

The group ID tells the API which group in your organization the request is for. It is part of the URL path.

1. Stay on **Organizational Settings** → **Integration**.
2. At the top of the tab it says **Your group ID is:** followed by the ID. Click **Copy** next to it.


Put the group ID in the URL where it says `{GROUP_ID}`:

```
https://api.optimized.app/v1/groups/{GROUP_ID}/batches
```

**Example with an actual Group ID:**

```
https://api.optimized.app/v1/groups/cc6cdf44-acf4-4b39-bd17-55b70b769812/batches
```

## Step 3: Find your campaign ID

1. In the left menu, under **Campaigns**, click **View Campaigns**.
2. Find the campaign you want to use and open its menu (⋮).
3. Click **Copy ID**.


Use this ID as `schedule.campaign.uuid` in the next step.

## Step 4: Send contacts and schedule the campaign

One request creates the contacts and schedules the campaign for them. Replace `{GROUP_ID}`, `{API_TOKEN}` and the campaign `uuid` with your own values:

```bash
curl -X POST https://api.optimized.app/v1/groups/{GROUP_ID}/batches \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {API_TOKEN}" \
-d '{
  "profiles": [
    {
      "external_id": "CUST-1001",
      "person": {
        "first_name": "Jane",
        "last_name": "Doe",
        "phone_number": "+35840123456",
        "email_address": "jane.doe@example.com"
      },
      "attributes": [
        {
          "name": "CustomerType",
          "value": "New"
        }
      ]
    }
  ],
  "schedule": {
    "start_at": "2026-12-01 08:00:00",
    "campaign": {
      "uuid": "9e679c93-ff33-4b1e-bfad-1ac77afe1aef"
    }
  }
}'
```

- **`profiles`**: up to 50 contacts per request.
- **`external_id`**: optional, your own ID for the contact. Must be unique in the group. Omit it instead of sending `null`.
- **`phone_number`**: `+` and digits only, no spaces or dashes.
- **`attributes`**: custom attributes on the contact. Attributes that don't exist yet are created.
- **`schedule.start_at`**: start time in UTC as `YYYY-MM-DD HH:MM:SS` (not ISO 8601). A time in the past, or no value, starts the campaign right away.
- **`schedule.calls_per_minute`**: optional, maximum calls per minute (1–60) for campaigns with voice steps.
- **`schedule.campaign.uuid`**: the campaign ID from step 3.


See the [API reference](/api) for every field and its validation rules.

### Response

A successful request returns `201 Created`:

```json
{
  "metadata": [],
  "profiles": [
    {
      "external_id": "CUST-1001",
      "uuid": "9ed85463-4f11-5fa1-8816-38677316e6a0"
    }
  ],
  "uuid": "9ed85463-5763-5983-0edc-de1f2849e543",
  "updated_at": "2026-11-12T09:15:22.000000Z",
  "created_at": "2026-11-12T09:15:22.000000Z",
  "group": {
    "uuid": "9e072d6f-0ed2-486a-baca-58f889f55cd4",
    "name": "My group"
    // Additional group information...
  },
  "campaign": {
    "uuid": "9e679c93-ff33-4b1e-bfad-1ac77afe1aef",
    "name": "Voice with question",
    // Additional campaign information...
  },
  "profile_tag": {
    "name": "Voice with question - 202611120915 - f40a3747",
    "uuid": "9ed85463-4c96-5129-ba98-f5f26004c238"
    // Additional contact list information...
  },
  "schedule": {
    "metadata": [],
    "status": "scheduled",
    "start_at": "2026-12-01T08:00:00.000000Z",
    "paused_at": null,
    "uuid": "9ed85463-564e-5b8e-93be-b82173f55687",
    "updated_at": "2026-11-12T09:15:22.000000Z",
    "created_at": "2026-11-12T09:15:22.000000Z"
  }
}
```

The contacts are created and the campaign is scheduled for them at `start_at`.

## Step 5: Stay within the rate limits

- **250 requests per minute per user.** All of the user's API tokens share this limit.
- **10 requests per minute per group** for `POST /v1/groups/{GROUP_ID}/batches`. Send up to 50 contacts per request rather than one request per contact.


Over a limit you get `429 Too Many Requests`. Wait the number of seconds in the `Retry-After` header, then retry.

## Next steps

- See every endpoint, field and error in the [API reference](/api).
- Get notified when messages are delivered or calls are answered with [webhooks](/guides/webhooks).
- Need help? Visit the [Help Center](https://support.wiraya.com/en/) or email [support@wiraya.com](mailto:support@wiraya.com).