> For the complete documentation index, see [llms.txt](https://docs.limecall.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.limecall.com/developers.md).

# Developers

The LimeCall REST API, authentication, webhooks and limits.

LimeCall has two separate surfaces with two separate kinds of key. Mixing them up is the single most common integration mistake, so start here:

```mermaid
flowchart LR
    subgraph B["Browser — your website"]
      W["Widget<br/>window.LimeCall"]
    end
    subgraph S["Your server"]
      A["Your backend"]
    end
    W -- "X-Widget-Key<br/>publishable" --> P["/api/public/callback<br/>Request a call"]
    A -- "Authorization: Bearer<br/>sk_live_ — SECRET" --> R["/api/v1<br/>Calls, contacts, numbers"]
```

The **widget key** is already in your page source and is meant to be public. The **secret key** must never reach a browser. They are not interchangeable, and neither surface accepts the other's key.

## Base URL

```
https://app.limecall.com/api/v1
```

## Authentication

Every request carries a bearer token:

```
Authorization: Bearer sk_live_...
```

Create tokens under **Settings → API keys**, or on the **Developers** page in the dashboard. See [API keys](/developers/api-keys.md).

## A first request

```bash
curl https://app.limecall.com/api/v1/calls \
  -H "Authorization: Bearer sk_live_..."
```

## Writing an outcome back

The most valuable single call in the API. When a call turns into a booking or a sale, write that back and it appears on the call and in your totals:

```bash
curl -X PATCH https://app.limecall.com/api/v1/calls/{callId} \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"outcome":"appointment_booked","value":250,"currency":"USD"}'
```

The outcome name is yours — use the same one consistently and calls group by it. Sending `value` is what lets LimeCall report revenue by channel rather than call counts by channel. See [Conversions](/analytics/conversions.md).

Requires a token with write access.

## Content type

Send `Content-Type: application/json` on requests with a body. Responses are JSON.

## This API is not the dashboard's API

The `/api/v1` surface is the customer-facing API, authenticated with `sk_live_` tokens. The dashboard itself uses a separate internal API with session authentication.

Only `/api/v1` is supported for integration. Anything you find by watching the dashboard's network traffic is internal, undocumented and will change without notice.

## Endpoint reference

| Resource                                      | Endpoints | Covers                                                               |
| --------------------------------------------- | --------- | -------------------------------------------------------------------- |
| [Calls](/developers/calls.md)                 | 7         | List, inspect, recordings, transcripts, summaries, outcome writeback |
| [Messages](/developers/messages.md)           | 3         | Send SMS/MMS, list history                                           |
| [Contacts](/developers/contacts.md)           | 5         | Full CRUD                                                            |
| [Phone numbers](/developers/phone-numbers.md) | 3         | List and reconfigure your lines                                      |
| [Voicemails](/developers/voicemails.md)       | 2         | List and mark handled                                                |
| [Users](/developers/users.md)                 | 5         | Your team, and verified caller-ID numbers                            |
| [Webhooks](/developers/webhooks.md)           | 5         | Manage subscriptions                                                 |
| [Analytics](/developers/analytics.md)         | 3         | Usage and breakdowns                                                 |
| [Devices](/developers/devices.md)             | 2         | Push tokens, for your own client                                     |

## Also in this section

* [API keys](/developers/api-keys.md) — creating and scoping tokens
* [Webhook events](/developers/webhook-events.md) — the events and how to handle them
* [Errors, pagination & rate limits](/developers/errors-and-rate-limits.md) — status codes, paging and limits

## Working in the browser instead

The REST API is for your server. To drive the callback widget from your own page — open it on a button, fire it from a form you already have, listen for events — use the browser API, which needs no secret key:

* [JavaScript API](/callback/javascript-api.md)
* [Connect your own form](/callback/connect-your-own-form.md)

## No-code alternatives

If you do not want to write code, Zapier, Make and n8n cover most integration needs. See [Zapier, Make & n8n](/integrations/zapier-and-make.md).