# Quickstart

> Create an API key, check it, list your leads, import contacts and create a webhook: your first WhatSetter integration in five minutes.

Source: https://docs.whatsetter.com/developers/quickstart/

Five requests, shown in cURL, JavaScript and Python. At the end you have a key, a list of contacts and a webhook that tells you when a lead is qualified.

## Before you start

- You are **owner** or **admin** of your WhatSetter workspace. The API page says it: **Only owners and admins can manage API keys.**
- You have `curl`, Node.js 18 or newer, or Python 3 with `requests`.
- The base URL is `https://app.whatsetter.com/api/v1`.

## 1. Create an API key

1. Open **Settings**, then **API & MCP**.
2. Click **Create a key**.
3. Fill in **Key name** (for example `CRM sync`) and choose the **Permissions**: **Full access**, or **Custom** to pick scopes one by one.
4. Click **Create the key**.
5. Copy the key. The dialog reads **Copy your key now. It will never be shown again.** Then click **I saved my key**.

Store it in an environment variable, never in your code:

```bash
export WHATSETTER_API_KEY="ws_live_…"
```

> **Lost the key?**
WhatSetter only stores a fingerprint of the key. If you lose it, click **Revoke** on that key and create a new one.

## 2. Check the key

[GET /me](/api-reference/operations/getme/) needs no scope. It tells you which workspace and which permissions the key has.

**cURL**

```bash
curl https://app.whatsetter.com/api/v1/me \
  -H "Authorization: Bearer $WHATSETTER_API_KEY"
```

**JavaScript**

```js
const res = await fetch('https://app.whatsetter.com/api/v1/me', {
  headers: { Authorization: `Bearer ${process.env.WHATSETTER_API_KEY}` },
});
console.log(await res.json());
```

**Python**

```python
import os, requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/me",
    headers={"Authorization": f"Bearer {os.environ['WHATSETTER_API_KEY']}"},
)
print(r.json())
```

```json
{
  "data": {
    "team_id": "6b0c1d2e3f405162738a",
    "key": {
      "id": "66f1a2b3c4d5e6f7a8b9c0d1",
      "name": "CRM sync",
      "scopes": ["leads:read", "leads:write", "lists:write", "webhooks:manage"]
    }
  }
}
```

A `401 invalid_api_key` means the key was mistyped or revoked. A `401 missing_api_key` means the header did not reach us.

## 3. List your leads

[GET /leads](/api-reference/operations/listleads/) needs `leads:read`. Filter by `status`, `campaign_id`, `phone`, `source` or `since`, and page with `limit` (1 to 100) and `cursor`.

**cURL**

```bash
curl "https://app.whatsetter.com/api/v1/leads?status=qualified&limit=10" \
  -H "Authorization: Bearer $WHATSETTER_API_KEY"
```

**JavaScript**

```js
const url = new URL('https://app.whatsetter.com/api/v1/leads');
url.searchParams.set('status', 'qualified');
url.searchParams.set('limit', '10');

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.WHATSETTER_API_KEY}` },
});
const { data, pagination } = await res.json();
console.log(data.length, pagination.next_cursor);
```

**Python**

```python
import os, requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/leads",
    params={"status": "qualified", "limit": 10},
    headers={"Authorization": f"Bearer {os.environ['WHATSETTER_API_KEY']}"},
)
body = r.json()
print(len(body["data"]), body["pagination"]["next_cursor"])
```

```json
{
  "data": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0d1",
      "phone": "33612345678",
      "name": "Julien",
      "status": "qualified",
      "qualified": true,
      "qualified_at": "2026-09-18T09:12:41.000Z",
      "campaign_id": "acme-france-1-ab12",
      "source": "list",
      "tags": ["hot"],
      "messages_count": 14,
      "last_message_at": "2026-09-18T09:12:00.000Z",
      "last_message_direction": "inbound"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": null }
}
```

The lead object is shortened here. When `has_more` is `true`, send `next_cursor` back as `cursor` to get the next page.

## 4. Import a list of contacts

Two calls: [POST /lists](/api-reference/operations/createlist/) creates an empty list, then [`POST /lists/{id}/leads`](/api-reference/operations/importleads/) pushes up to 500 contacts per call. Both need `lists:write`. Phones are deduplicated inside the batch and against the list.

**cURL**

```bash
# 1. Create the list
curl -X POST https://app.whatsetter.com/api/v1/lists \
  -H "Authorization: Bearer $WHATSETTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"CRM sync, hot leads"}'

# 2. Push contacts into it (replace LIST_ID with the id from step 1)
curl -X POST https://app.whatsetter.com/api/v1/lists/LIST_ID/leads \
  -H "Authorization: Bearer $WHATSETTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"leads":[{"phone":"+33612345678","name":"Julien","custom_variables":{"city":"Lyon"}}]}'
```

**JavaScript**

```js
const headers = {
  Authorization: `Bearer ${process.env.WHATSETTER_API_KEY}`,
  'Content-Type': 'application/json',
};

// 1. Create the list
const created = await fetch('https://app.whatsetter.com/api/v1/lists', {
  method: 'POST',
  headers,
  body: JSON.stringify({ name: 'CRM sync, hot leads' }),
});
const { data: list } = await created.json();

// 2. Push contacts into it
const imported = await fetch(`https://app.whatsetter.com/api/v1/lists/${list.id}/leads`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    leads: [{ phone: '+33612345678', name: 'Julien', custom_variables: { city: 'Lyon' } }],
  }),
});
console.log(await imported.json());
```

**Python**

```python
import os, requests

headers = {"Authorization": f"Bearer {os.environ['WHATSETTER_API_KEY']}"}
base = "https://app.whatsetter.com/api/v1"

# 1. Create the list
lst = requests.post(f"{base}/lists", headers=headers,
                    json={"name": "CRM sync, hot leads"}).json()["data"]

# 2. Push contacts into it
r = requests.post(
    f"{base}/lists/{lst['id']}/leads",
    headers=headers,
    json={"leads": [{"phone": "+33612345678", "name": "Julien",
                     "custom_variables": {"city": "Lyon"}}]},
)
print(r.json())
```

```json
{
  "data": {
    "imported": 1,
    "duplicates_in_list": 0,
    "rejected": [],
    "lead_ids": ["66f1a2b3c4d5e6f7a8b9c0d2"]
  }
}
```

> **Importing does not message anyone yet**
A list is a pool of contacts. The first message goes out when the list is attached to a campaign, at the pace of the [anti-ban engine](/dashboard/anti-ban/). To add a single opt-in lead and message them right away, use [`POST /campaigns/{id}/leads`](/api-reference/operations/addcampaignlead/) instead.

## 5. Create a webhook

[POST /webhooks](/api-reference/operations/createwebhook/) needs `webhooks:manage`. The endpoint must be HTTPS.

**cURL**

```bash
curl -X POST https://app.whatsetter.com/api/v1/webhooks \
  -H "Authorization: Bearer $WHATSETTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-server.com/webhooks/whatsetter","events":["contact.qualified","contact.not_qualified"]}'
```

**JavaScript**

```js
const res = await fetch('https://app.whatsetter.com/api/v1/webhooks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WHATSETTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://your-server.com/webhooks/whatsetter',
    events: ['contact.qualified', 'contact.not_qualified'],
  }),
});
const { data } = await res.json();
console.log(data.secret); // whsec_… shown once, store it now
```

**Python**

```python
import os, requests

r = requests.post(
    "https://app.whatsetter.com/api/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['WHATSETTER_API_KEY']}"},
    json={"url": "https://your-server.com/webhooks/whatsetter",
          "events": ["contact.qualified", "contact.not_qualified"]},
)
print(r.json()["data"]["secret"])  # whsec_… shown once, store it now
```

```json
{
  "data": {
    "id": "66f1c0ffee00000000000abc",
    "url": "https://your-server.com/webhooks/whatsetter",
    "events": ["contact.qualified", "contact.not_qualified"],
    "active": true,
    "description": null,
    "secret_prefix": "whsec_3f9a",
    "secret": "whsec_3f9a…",
    "last_delivery_at": null,
    "last_delivery_status": null,
    "created_at": "2026-09-19T10:00:00.000Z"
  }
}
```

The `secret` is shown only in this response. Store it: you need it to [verify the signature](/developers/webhooks/) of every delivery. Then send yourself a signed test event with [`POST /webhooks/{id}/test`](/api-reference/operations/testwebhook/).

## Next steps

- [Authentication and permissions](/developers/authentication/): scopes, rate limits, key rotation.
- [Errors, limits and idempotency](/developers/errors/): every `code`, and how to retry safely.
- [Guides by resource](/developers/): leads, campaigns, messages, groups, blocked contacts, links.
- [MCP server](/developers/mcp/): give the same key to Claude, Cursor or ChatGPT.
- [Use these docs with AI assistants](/developers/ai-assistants/): let an assistant build the integration for you.
