How do I authenticate to the TalaLevel API?

With a workspace key in the Authorization header: Authorization: Bearer tl_live_…. An owner makes the key in Settings → Connections → API and webhooks.

What is the TalaLevel API rate limit?

600 calls a minute for each key. Over it the answer is 429 with a retry-after header that says when to try again.

Can I limit what an API key may do?

Yes. Each key holds a level for each area: none, read, write, or send. A key that only reads leads cannot text anyone.

Authentication, permissions, errors and limits

Send the key as Authorization: Bearer tl_live_… on every call. A key holds a level (none, read, write or send) for each area such as leads, texts and pipeline. Errors are JSON with an error sentence; the limit is 600 calls a minute for each key.

View as Markdown

The key

Every call carries a workspace key:

An owner makes a key in Settings → Connections → API and webhooks, names it and picks what it may do.
The key is shown once. We keep a hash of it and its last four characters, so two keys can be told apart.
A key belongs to one workspace and acts as the owner who made it. If that person leaves the workspace or is put on hold, the key stops working.
A revoked key stops at once.
The base address is https://app.talalevel.com/api/v1. Requests and answers are JSON.

The same key also works on the MCP server and the command line.

Text

Authorization: Bearer tl_live_…

Permissions

A key holds one level for each area. Write includes read, and send includes both.

Area	Levels	What it covers
`leads`	none, read, write	Leads, their contacts, fields and status
`lists`	none, read, write	Saved lists and who is on them
`notes`	none, read, write	Notes on a lead
`tasks`	none, read, write	A lead’s task and callbacks
`pipeline`	none, read, write	Pipelines, stages and deals
`calls`	none, read, send	Calls and transcripts; send starts and stops AI caller runs
`texts`	none, read, write, send	Text threads; write drafts, send sends
`emails`	none, read, write, send	Emails on a lead; write drafts, send sends
`calendar`	none, read	Booked calls and calendar events
`reports`	none, read	Activity figures
`team`	none, read	The people in the workspace

The presets set every area at once:

Preset	Every area at
Read only	read
Read and write	its highest level short of send
Read, write and send	its highest level
Custom	whatever you pick; a key that allows nothing is refused

A call the key’s level does not cover is a 403 that names what is missing:

JSON

{ "error": "This key may not send texts.", "area": "texts", "needs": "send" }

Errors

An error is a status code and a sentence. Some carry more, such as the lead a duplicate phone belongs to.

Code	Meaning	What to do
400	The body could not be read, has a field we do not know, or a bad value	Fix the request. Nothing was written.
401	No valid key	Check the `Authorization` header.
403	The key’s permissions do not cover this call	The answer names the `area` and the level it `needs`.
404	No such record, or it is another workspace’s	The two are never told apart.
409	A duplicate, an ambiguous match, or a change the record cannot take	The answer says which; a duplicate carries `lead_id` or `lead_ids`.
422	A send or a tool was refused: an opt-out, quiet hours, the day cap, a stale preview	Read the sentence. Nothing was sent.
429	Too many calls	Wait for the time in the `retry-after` header.
500	Our fault	Try again.

A body is checked whole before anything is written. One bad field is a 400 and no part of the request is applied.

JSON

{ "error": "That phone is on a lead here already. Update it, or upsert by phone.", "lead_id": 123 }

Rate limits

Limit	Value
Calls for each key	600 a minute
Calls with no valid key, for each address	60 a minute
Texts and emails a key may send	20 in 24 hours unless the owner changes it; at most 500
Rows a key may read through tools	5,000 in 24 hours
Leads in one batch or run preview	5,000

The owner sets the daily send limit in Settings → AI apps. Batches, waves and AI caller runs keep their own limits and do not count against it.

Paging

List calls take cursor and limit and answer with next_cursor and has_more.

/leads and /deals list the oldest change first. Call again at once while has_more is true. When it is false, keep next_cursor and use it on your next poll to get only what changed since.
A change is listed 30 seconds after it happens, so a record that is still being saved is never skipped.
Notes, texts, calls and emails on a lead list the newest first, and the cursor is the last row’s id.

cURL

curl "https://app.talalevel.com/api/v1/leads?cursor=$CURSOR&limit=50" \
  -H "Authorization: Bearer $TALALEVEL_KEY"

Questions

How do I authenticate to the TalaLevel API?: With a workspace key in the Authorization header: Authorization: Bearer tl_live_…. An owner makes the key in Settings → Connections → API and webhooks.
What is the TalaLevel API rate limit?: 600 calls a minute for each key. Over it the answer is 429 with a retry-after header that says when to try again.
Can I limit what an API key may do?: Yes. Each key holds a level for each area: none, read, write, or send. A key that only reads leads cannot text anyone.