Quickstart: your first TalaLevel API call

TalaLevel has a REST API, webhooks, an MCP server and a command line. Make a key in Settings, send it as a Bearer token to https://app.talalevel.com/api/v1, and you can read and change leads, lists, notes and deals, and send texts and emails where the key allows it.

View as Markdown

Four ways in

Way in What it is for Where
REST API Your own code, Zapier, Make, a spreadsheet https://app.talalevel.com/api/v1
Webhooks Being told when a lead is made, texts back, a call ends, a deal is won You give us an https address
MCP server Claude, ChatGPT, Cursor and other AI apps working your leads https://app.talalevel.com/mcp
Command line Scripts and coding agents in a terminal npx talalevel

All four work on the same workspace with the same permissions. A key or a connection can do only what its owner allowed, and never more than that person can do in the app.

1. Make a key

In the app, an owner opens Settings → Connections → API and webhooks and makes a key. Pick what it may do:

  • Read only: reads everything, changes nothing.
  • Read and write: also makes and changes leads, notes, lists and deals.
  • Read, write and send: also sends texts and emails and starts batches.
  • Custom: a level for each area. See permissions.

The key starts with tl_live_ and is shown once. Keep it somewhere safe; we keep only a hash of it.

2. Read your leads

Leads come oldest change first. Keep next_cursor and pass it as cursor on the next call to get only what changed since.

cURL
curl "https://app.talalevel.com/api/v1/leads?limit=2" \
  -H "Authorization: Bearer $TALALEVEL_KEY"
JSON
{
  "leads": [
    {
      "id": 123,
      "name": "Reed Auto Repair",
      "status": "Interested",
      "email": "marcus@reedauto.example",
      "city": "Austin",
      "state": "TX",
      "time_zone": "America/Chicago",
      "contacts": [
        { "name": "Marcus Reed", "phones": [{ "phone": "+15125550147", "type": "mobile" }], "emails": [] }
      ],
      "fields": { "Team size": "12" },
      "owner": { "id": 4, "name": "Dana" },
      "starred": false,
      "updated_at": "2026-11-12T09:37:45.678Z",
      "url": "https://app.talalevel.com/leads/123"
    }
  ],
  "next_cursor": "…",
  "has_more": true
}

3. Add a lead

upsert finds the lead with that phone and updates it, or makes a new one. It answers 201 with "created": true for a new lead and 200 with "created": false for one it found. Use it for forms and imports so a lead is never made twice.

cURL
curl -X POST "https://app.talalevel.com/api/v1/leads/upsert" \
  -H "Authorization: Bearer $TALALEVEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "match": "phone", "name": "Reed Auto Repair", "contact_name": "Marcus Reed", "phone": "(512) 555-0147" }'

4. Get told when something happens

In the same Settings screen, add a webhook: an https address and the events you want. When a lead texts back we post this to you within a minute:

Every delivery is signed. See webhooks for the events, the signature and the retries.

JSON
{
  "id": "evt_…",
  "type": "text.received",
  "created_at": "2026-11-12T03:12:09.000Z",
  "workspace_id": 7,
  "data": {
    "lead": { "id": 123, "name": "Reed Auto Repair", "status": "Interested" },
    "text": { "id": 9912, "body": "This week ideally. We decide Friday", "at": "2026-11-12T03:12:07.000Z", "number": "+15125550147", "line": "+15125550100" }
  }
}

5. Or connect an AI app

No code needed. In Claude, ChatGPT or Cursor add a custom connector with this address and sign in:

In Claude Code:

The app then has tools such as search_leads, get_lead, add_note, set_task and send_text. The MCP reference lists every one.

Text
https://app.talalevel.com/mcp
cURL
claude mcp add --transport http talalevel https://app.talalevel.com/mcp

Rules every way in follows

  • A send is checked like a send in the app. Opt-outs, quiet hours in the lead’s time zone, message length and your numbers’ registration all apply. Where a person in the app would see a warning, a key or an AI app is refused, and nothing goes.
  • Batches are previewed first. A text batch, a wave or an AI caller run is a preview call, then a start call with the preview’s id.
  • Phone numbers are US and Canada (the +1 plan), in any common form.
  • Another workspace’s record reads as not found. A key works in one workspace only.

Next

Questions

Does TalaLevel have an API?
Yes. A REST API at https://app.talalevel.com/api/v1 with workspace keys, webhooks for eleven events, an MCP server at https://app.talalevel.com/mcp for AI apps, and a command line, npx talalevel.
Which plans include the API?
The API, webhooks and the MCP server are part of every plan. Sending texts through them needs a plan with texting, and AI caller runs need the Scale plan, the same as in the app.
Is there an OpenAPI file?
Yes, OpenAPI 3.1 at https://talalevel.com/openapi.json. It describes every endpoint on this site's reference page.
Can an AI agent use TalaLevel without writing code?
Yes. Add https://app.talalevel.com/mcp as a connector in Claude, ChatGPT, Cursor or any app that speaks MCP and sign in. The agent then works with tools such as search_leads, get_lead and send_text.

© 2026 TalaLevel · talalevel.com · openapi.json · llms.txt · Privacy · Terms