# Quickstart (/quickstart)

This guide takes you from no key to a running campaign. You need a manager role in a CallMitra workspace with at least one agent and one connected phone number.

<Steps>
<Step>
### Create an API key [#create-an-api-key]

1. Sign in to the console and open **Settings → Developers**.
2. Choose **Create key**, give it a name (for example `crm-sync`), and pick its access and expiry. See [Authentication](/authentication) for what each option does.
3. Copy the key. It starts with `vk_live_` and is shown **only once**.

Store it as a secret on your server, for example in an environment variable:

```bash
export CALLMITRA_API_KEY="vk_live_..."
```

<Callout type="warn">
Never put an API key in a browser, mobile app or public repository. Anyone with the key can act on your workspace.
</Callout>
</Step>

<Step>
### Make your first request [#make-your-first-request]

List your agents. Every request sends the key in the `X-API-Key` header.

<Tabs groupId="language" persist items={["cURL","Node.js","Python"]}>
<Tab value="cURL">
```bash
curl https://api.callmitra.ai/api/v1/agents/ \
  -H "X-API-Key: $CALLMITRA_API_KEY"
```
</Tab>

<Tab value="Node.js">
```js
const res = await fetch('https://api.callmitra.ai/api/v1/agents/', {
  headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY },
});
const { agents } = await res.json();
console.log(agents.map((agent) => [agent.id, agent.name]));
```
</Tab>

<Tab value="Python">
```python
import os
import requests

res = requests.get(
    "https://api.callmitra.ai/api/v1/agents/",
    headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]},
    timeout=30,
)
res.raise_for_status()
for agent in res.json()["agents"]:
    print(agent["id"], agent["name"])
```
</Tab>
</Tabs>

A `200` response lists your agents. Note the `id` of the agent that should make the calls. Collection paths end with a slash (`/agents/`); without it the API answers with a `307` redirect.

If you get `401`, check the key and the header name. Every error has the same [envelope](/errors) with a stable `error.code`.
</Step>

<Step>
### Pick a caller ID [#pick-a-caller-id]

List the phone numbers connected to your workspace and note the `id` of the number to call from:

```bash
curl https://api.callmitra.ai/api/v1/phone-numbers/ \
  -H "X-API-Key: $CALLMITRA_API_KEY"
```
</Step>

<Step>
### Create a campaign with leads [#create-a-campaign-with-leads]

Create the campaign and its leads in one request. `campaignData.name` and `campaignData.agentId` are required. Phone numbers are E.164 (`+91…`).

<Tabs groupId="language" persist items={["cURL","Node.js","Python"]}>
<Tab value="cURL">
```bash
curl -X POST https://api.callmitra.ai/api/v1/campaigns/create-with-leads \
  -H "X-API-Key: $CALLMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignData": {
      "name": "Demo follow-up",
      "agentId": "AGENT_ID",
      "phoneNumberId": "PHONE_NUMBER_ID"
    },
    "leadSourceType": "bulk_upload",
    "uploadedLeads": [
      { "name": "Asha Rao", "phone": "+919876543210", "attributes": { "city": "Pune" } }
    ]
  }'
```
</Tab>

<Tab value="Node.js">
```js
const res = await fetch('https://api.callmitra.ai/api/v1/campaigns/create-with-leads', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.CALLMITRA_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    campaignData: {
      name: 'Demo follow-up',
      agentId: 'AGENT_ID',
      phoneNumberId: 'PHONE_NUMBER_ID',
    },
    leadSourceType: 'bulk_upload',
    uploadedLeads: [{ name: 'Asha Rao', phone: '+919876543210', attributes: { city: 'Pune' } }],
  }),
});
const { campaignId, processedLeads } = await res.json();
```
</Tab>

<Tab value="Python">
```python
res = requests.post(
    "https://api.callmitra.ai/api/v1/campaigns/create-with-leads",
    headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]},
    json={
        "campaignData": {
            "name": "Demo follow-up",
            "agentId": "AGENT_ID",
            "phoneNumberId": "PHONE_NUMBER_ID",
        },
        "leadSourceType": "bulk_upload",
        "uploadedLeads": [
            {"name": "Asha Rao", "phone": "+919876543210", "attributes": {"city": "Pune"}}
        ],
    },
    timeout=30,
)
res.raise_for_status()
campaign_id = res.json()["campaignId"]
```
</Tab>
</Tabs>

The response contains `campaignId` and `processedLeads`. `attributes` are extra fields your agent can use in the conversation.
</Step>

<Step>
### Start the campaign [#start-the-campaign]

```bash
curl -X POST https://api.callmitra.ai/api/v1/campaigns/CAMPAIGN_ID/start \
  -H "X-API-Key: $CALLMITRA_API_KEY"
```

Calls are placed inside the campaign's calling window, so the first call may not start immediately. Check progress with [`GET /api/v1/campaigns/{campaign_id}/dial-status`](/api-reference/campaigns/getCampaignDialStatus), or list results with `GET /api/v1/calls/?campaignId=CAMPAIGN_ID`.
</Step>

<Step>
### Receive the result [#receive-the-result]

Instead of polling, register a webhook endpoint once, in the console under **Settings → Developers → Webhooks** or with the API. CallMitra then sends a signed `call.completed` event after every call, with the status, transcript, summary and outcome:

```bash
curl -X POST https://api.callmitra.ai/api/v1/webhook-endpoints/ \
  -H "X-API-Key: $CALLMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/webhooks/callmitra", "events": ["call.completed", "call.failed"] }'
```

The response (or the console) shows the signing `secret` (`whsec_...`) only once. Store it on your server. A minimal receiver checks the [Standard Webhooks](https://www.standardwebhooks.com/) signature over the raw body:

```js
import crypto from 'node:crypto';
import express from 'express';

const app = express();
const key = Buffer.from(process.env.CALLMITRA_WEBHOOK_SECRET.split('_')[1], 'base64');

app.post('/webhooks/callmitra', express.raw({ type: 'application/json' }), (req, res) => {
  const id = req.get('webhook-id');
  const timestamp = req.get('webhook-timestamp');
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return res.sendStatus(401);

  const expected = crypto
    .createHmac('sha256', key)
    .update(`${id}.${timestamp}.${req.body.toString('utf8')}`)
    .digest('base64');
  const valid = (req.get('webhook-signature') ?? '')
    .split(' ')
    .some((sig) => {
      const value = sig.split(',')[1] ?? '';
      return value.length === expected.length &&
        crypto.timingSafeEqual(Buffer.from(value), Buffer.from(expected));
    });
  if (!valid) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString('utf8'));
  console.log(event.type, event.data.callId, event.data.merchantOutcome, event.data.summary);
  res.sendStatus(204); // answer 2xx within 10 seconds, then do slow work
});

app.listen(3000);
```

See [Verify signatures](/webhooks/verify-signatures) for Python, PHP and Go, and [Webhooks](/webhooks) for retries, de-duplication and every event.
</Step>
</Steps>

## Next steps [#next-steps]

<Cards>
<Card title="Errors" href="/errors">
Handle failures by `error.code`.
</Card>

<Card title="Rate limits" href="/rate-limits">
Stay inside 300 requests per minute per key.
</Card>

<Card title="Campaigns guide" href="/guides/campaigns">
Lead sources, calling windows, pausing and stopping.
</Card>

<Card title="API reference" href="/api-reference">
Every endpoint with examples.
</Card>
</Cards>