--- title: "Quickstart: your first TalaLevel API call" description: "Make a TalaLevel API key, read your leads, add one, and get a webhook when a lead texts back. Five minutes, with curl examples you can paste." url: https://talalevel.com/docs/quickstart/ date: 2026-11-12 updated: 2026-11-12 --- # 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. ## 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](https://talalevel.com/docs/authentication/#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 ```sh 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 } ``` Leads come oldest change first. Keep `next_cursor` and pass it as `cursor` on the next call to get only what changed since. ## 3. Add a lead ```sh 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" }' ``` `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. ## 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: ```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" } } } ``` Every delivery is signed. See [webhooks](https://talalevel.com/docs/webhooks/) for the events, the signature and the retries. ## 5. Or connect an AI app No code needed. In Claude, ChatGPT or Cursor add a custom connector with this address and sign in: ``` https://app.talalevel.com/mcp ``` In Claude Code: ```sh claude mcp add --transport http talalevel https://app.talalevel.com/mcp ``` The app then has tools such as `search_leads`, `get_lead`, `add_note`, `set_task` and `send_text`. The [MCP reference](https://talalevel.com/docs/mcp/) lists every one. ## 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 - [Authentication, permissions, errors and limits](https://talalevel.com/docs/authentication/) - [REST API reference](https://talalevel.com/docs/api/) - [Webhooks](https://talalevel.com/docs/webhooks/) - [MCP server](https://talalevel.com/docs/mcp/) - [Command line and Claude Code plugin](https://talalevel.com/docs/cli/) ## 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.