Getting started

Make a key, call the API, and learn the five rules that differ from most APIs.

1. Make a key

In the app: Settings, Developers, API keys, Create key. You pick three things:

Workspaces. A key never reaches further than the person who made it.
Scopes. Start from a preset, then trim. See Scopes.
Expiry. 365 days is a good default.

The secret is shown once. It is hashed, so nobody can read it back. Lost it? Make a new key, move the integration, revoke the old one.

What a key looks like

text

lak_live_k7m2p9qh_9fK2mQ7pL4vX8nT3bY6cZ1sD5fG0jH2k
│   │    │        └ the secret, 32 characters. Hashed on write and never stored
│   │    └ public lookup handle, 8 characters. Safe to log
│   └ environment. test keys are reserved and rejected in v1
└ fixed prefix, so one secret-scanner rule matches every key

Treat the whole string as the secret. Keep it in a secret manager.

2. Your first request

Call /v1/me first. It tells you what the key can reach right now.

bash

curl -sS https://api.leadarc.io/v1/me -H "Authorization: Bearer $LEADARC_API_KEY"

json

{
  "object": "me",
  "key": {
    "id": "k7m2p9qh",
    "name": "Claude inbox agent",
    "all_workspaces": false
  },
  "owner": {
    "email": "leon@leadarc.io",
    "role": "admin"
  },
  "scopes": [
    "leads:read",
    "leads:write",
    "notes:write",
    "tasks:read",
    "workspaces:read"
  ],
  "scopes_withheld": [],
  "workspaces": [
    {
      "object": "workspace",
      "slug": "airpay",
      "name": "AirPay"
    },
    {
      "object": "workspace",
      "slug": "cliniconex",
      "name": "Cliniconex"
    }
  ]
}

Check scopes_withheld before you debug a 403.

It lists scopes the key holds but its owner's role no longer allows. A key shrinks the moment its owner is demoted or offboarded.

3. Ask what the API accepts

GET /v1/capabilities needs no scope. It returns the live enum values, filters, limits and error codes. Fetch it at startup instead of hardcoding them.

bash

curl -sS https://api.leadarc.io/v1/capabilities -H "Authorization: Bearer $LEADARC_API_KEY"

4. A real job

Get interested leads nobody has handled, read one conversation, leave a note.

bash

WS=airpay
AUTH="Authorization: Bearer $LEADARC_API_KEY"

# leads a human has not handled yet
curl -sS "https://api.leadarc.io/v1/workspaces/$WS/leads?status=interested&responded=false&limit=25" -H "$AUTH"

# the full conversation for one of them
curl -sS "https://api.leadarc.io/v1/workspaces/$WS/leads/lead_2k8fq3a91c4e/messages" -H "$AUTH"

# leave a note for the rep who picks it up
curl -sS "https://api.leadarc.io/v1/workspaces/$WS/notes" -X POST -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"lead_id":"lead_2k8fq3a91c4e","body":"Wants a walkthrough before their board meeting."}'

Scope presets

Three starting points in the create dialog. No preset grants everything.

Preset	For	Scopes

Five rules

Ids are opaque. Never parse, sort or build one. A task id cannot be used as a lead id.
A wrong query parameter is a 400. The error names the parameter. Nothing is ignored.
Page with the cursor we return. Never an offset. See Pagination.
Read effects on every write. Some writes also close other people's tasks.
Accept unknown enum values on read. New status values can appear. Only writes are strict.