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.

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 "https://api.smartchat.marketing/v1/me" \
  -H "Authorization: Bearer $SMARTCHAT_API_KEY"

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())

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):

{
  "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 "https://api.smartchat.marketing/v1/account/overview?include=setup,credits" \
  -H "Authorization: Bearer $SMARTCHAT_API_KEY"

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())

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):

{
  "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 "https://api.smartchat.marketing/v1/contacts?query=mia&limit=2" \
  -H "Authorization: Bearer $SMARTCHAT_API_KEY"

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())

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):

{
  "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 names the permission it needs. See all 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.
2. A preview shows who would receive a newsletter and sends nothing: get_newsletter_send_preview.
3. Sending messages comes last. Read Sending safely first. Calls that send need the header Idempotency-Key (why).
4. To be told when something happens, set up a webhook.

#If something fails

Every answer has a Request-Id header. Give it to support if you need help.