# Quickstart

> Make your first API call in under 5 minutes. You only read, so nothing can be changed or sent by mistake, and an empty account works.

Last updated: 2026-10-30. Source: https://docs.smartchat.marketing/en/quickstart/

This page takes less than 5 minutes. You only **read** data. Nothing is changed and no message is sent. It works with an empty account.

## Before you start

- You have a SmartChat account and you can sign in to the app at https://app.smartchat.marketing.
- You are the **owner** or an **admin** of the account. Only these two roles can create API keys. If you are not, ask one of them.
- You have a terminal with `curl`. For the Python examples you need Python 3 and the package `requests` (`pip install requests`). For the TypeScript examples you need Node.js 18 or newer.

## 1. Create a key with the level Read

1. Sign in to the app at https://app.smartchat.marketing.
2. Open **Settings**, then **Integrations**, then **API keys**, and choose **Create new key**.
3. Give the key a name, for example `Quickstart`. Choose the level **Read** (it is ticked by default).
4. Choose **Create key** and copy the key. You see it only once. A key starts with `sc_live_`.

You can also create a key in the SmartChat AI chat: the AI chooses the permissions for you.

Save the key in an environment variable. Never put a key into code, a chat or a public file.

```bash norun
export SMARTCHAT_API_KEY="paste-your-key-here"
```

Paste the whole line you copied in place of `paste-your-key-here`. The line must now start with `sc_live_`. If you get "401" later, check this first.

The examples on this page call `https://api.smartchat.marketing/v1`. If you work against a different address, replace it.

## 2. Check the connection

This call needs no permission. It shows your account, your key and its permissions.

**curl**

```bash
curl "https://api.smartchat.marketing/v1/me" \
  -H "Authorization: Bearer $SMARTCHAT_API_KEY"
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://api.smartchat.marketing/v1/me",
    headers={"Authorization": "Bearer " + os.environ["SMARTCHAT_API_KEY"]},
)
response.raise_for_status()
print(response.json())
```

**TypeScript**

```typescript
const response = await fetch("https://api.smartchat.marketing/v1/me", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SMARTCHAT_API_KEY}`,
  },
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

Response (200):


```json
{
  "object": "me",
  "id": "acc_0f8c1a2e4b7d4c3e9a5b6d7e8f901234",
  "account": {
    "object": "account",
    "id": "acc_0f8c1a2e4b7d4c3e9a5b6d7e8f901234",
    "name": "Casa Olivo"
  },
  "key": {
    "object": "api_key",
    "id": "key_1a2b3c4d5e6f47a8b9c0d1e2f3a4b5c6",
    "name": "Quickstart",
    "prefix": "sc_live_ab12"
  },
  "auth_type": "api_key",
  "environment": "live",
  "scopes": [
    "contacts:read",
    "sends:read",
    "inbox:read",
    "templates:read",
    "newsletters:read",
    "followups:read",
    "automations:read",
    "landing:read",
    "ai:settings_read",
    "knowledge:read",
    "media:read",
    "settings:read",
    "webhooks:read",
    "connections:read",
    "stats:read",
    "team:read",
    "account:read"
  ],
  "rate_limits": {
    "read": 120,
    "write": 120,
    "send": 120,
    "bulk": 120,
    "upload": 120
  },
  "api_version": "2026-10-25"
}
```

If you see your account name, the key works. If you get an error, look at the table at the end of this page.

## 3. Look at your account

This call needs the permission `account:read` (part of the level **Read**).

**curl**

```bash
curl "https://api.smartchat.marketing/v1/account/overview?include=setup,credits" \
  -H "Authorization: Bearer $SMARTCHAT_API_KEY"
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://api.smartchat.marketing/v1/account/overview",
    headers={"Authorization": "Bearer " + os.environ["SMARTCHAT_API_KEY"]},
    params={
        "include": "setup,credits",
    },
)
response.raise_for_status()
print(response.json())
```

**TypeScript**

```typescript
const response = await fetch("https://api.smartchat.marketing/v1/account/overview?include=setup,credits", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SMARTCHAT_API_KEY}`,
  },
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

Response (200):


```json
{
  "object": "account_overview",
  "id": "acc_0f8c1a2e4b7d4c3e9a5b6d7e8f901234",
  "name": "Casa Olivo",
  "language": "en",
  "created_at": "2026-10-25T09:41:07Z",
  "setup": {
    "whatsapp_connected": true,
    "whatsapp_display_number": "+39 06 1234 5678",
    "test_phone_set": true,
    "business_profile_present": true
  },
  "credits": {
    "balance": 2400
  }
}
```

## 4. Read your contacts

This call needs the permission `contacts:read` (part of the level **Read**).

**curl**

```bash
curl "https://api.smartchat.marketing/v1/contacts?query=mia&limit=2" \
  -H "Authorization: Bearer $SMARTCHAT_API_KEY"
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://api.smartchat.marketing/v1/contacts",
    headers={"Authorization": "Bearer " + os.environ["SMARTCHAT_API_KEY"]},
    params={
        "query": "mia",
        "limit": "2",
    },
)
response.raise_for_status()
print(response.json())
```

**TypeScript**

```typescript
const response = await fetch("https://api.smartchat.marketing/v1/contacts?query=mia&limit=2", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SMARTCHAT_API_KEY}`,
  },
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

Response (200):


```json
{
  "object": "list",
  "data": [
    {
      "object": "contact",
      "id": "con_0f8c1a2e4b7d4c3e9a5b6d7e8f901234",
      "name": "Mia Muster",
      "phone": "+4915112345678",
      "email": "mia@example.com",
      "language": "en",
      "status": "unconfirmed",
      "optin_whatsapp": "none",
      "optin_whatsapp_at": null,
      "purpose": "marketing",
      "source": "api",
      "tags": [],
      "tag_details": [],
      "created_at": "2026-10-25T09:41:07Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "url": "/v1/contacts"
}
```

An empty list (`"data": []`) is a correct answer for a new account. Nothing is wrong. The example above searches for the name `mia`; your account answers with your own contacts.

If steps 3 or 4 answer 403, your key was created with single permissions instead of the level Read. Add `account:read` and `contacts:read`, or create a new key with the level Read.

## 5. Look at what your key may do

The `scopes` list in the answer of step 2 shows the permissions of the key. Every call in the [API reference](https://docs.smartchat.marketing/en/api/) names the permission it needs. See [all permissions](https://docs.smartchat.marketing/en/api/permissions/).

## Next: write, preview, then send

1. To create or change things you need a key with the level **Draft** or higher. Try [Create a contact](https://docs.smartchat.marketing/en/guides/create-a-contact/).
2. A **preview** shows who would receive a newsletter and sends nothing: [`get_newsletter_send_preview`](https://docs.smartchat.marketing/en/api/reference/newsletters/get_newsletter_send_preview/).
3. Sending messages comes last. Read [Sending safely](https://docs.smartchat.marketing/en/security/) first. Calls that send need the header `Idempotency-Key` ([why](https://docs.smartchat.marketing/en/concepts/idempotency/)).
4. To be told when something happens, set up a [webhook](https://docs.smartchat.marketing/en/guides/set-up-a-webhook/).

## If something fails

| You see | Code | What to do |
|---|---|---|
| 401 | [`authentication_required`](https://docs.smartchat.marketing/en/errors/#authentication_required) | Send the header `Authorization: Bearer <key>`. |
| 401 | [`api_key_invalid`](https://docs.smartchat.marketing/en/errors/#api_key_invalid) | Check that you copied the whole key. |
| 403 | [`insufficient_scope`](https://docs.smartchat.marketing/en/errors/#insufficient_scope) | The key lacks a permission. The answer names it in `required_scope`. Create a new key with more permissions. |
| 404 | [`not_found`](https://docs.smartchat.marketing/en/errors/#not_found) | Check the address. |
| 429 | [`rate_limited`](https://docs.smartchat.marketing/en/errors/#rate_limited) | Wait for the seconds in the `Retry-After` header. |

Every answer has a `Request-Id` header. Give it to [support](https://docs.smartchat.marketing/en/support/) if you need help.