---
title: "Lead API | Ring First"
description: "Send a lead to a Ring First AI phone agent with one POST request. It calls them back in under 60 seconds."
url: https://ring-first.com/docs/api/
---

Docs · Lead API v1

# Lead API

One POST and your AI phone agent calls the lead back in under 60 seconds, day or night. Use it from a website form or from your own server. Machine-readable spec: [openapi.json](https://ring-first.com/openapi.json).

## Endpoint

```
POST https://api.ring-first.com/v1/leads
```

## Authentication

- **From a browser form:** add your public key as `?key=pk_...`. It's safe in page code, but only works from the website addresses we've set up for you.
- **From a server:** send your secret key as `Authorization: Bearer sk_...`. Never put it in browser code.

## Body

JSON, sent as `application/json` (or `text/plain` for `navigator.sendBeacon`).

- `phone` (required): a US or Canadian number, in any common format.
- `name`: the lead's name.
- `message`: what they need.
- `trade`: optional; added in front of the message.
- `consent`: that they agreed to be called. Required if your account requires consent.
- Anything else (like `business`) is kept with the lead.

```
curl -X POST "https://api.ring-first.com/v1/leads" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Pat Lee","phone":"(403) 555-0111","message":"Leaky water heater","consent":true}'
```

## Responses

- `202` `{"ok":true}`: accepted; the agent is calling them back. A repeat for the same number within a few minutes is accepted but not called twice.
- `400` invalid JSON or phone number · `401` unknown key · `403` origin not allowed · `413` body too large · `422` consent required · `429` too many requests or daily limit reached.
- Errors come back as `{"error":"..."}`.

## Status

`GET https://api.ring-first.com/healthz` returns `ok` when the API is up.

## Keys and help

Your keys come with your account. Questions: [hello@ring-first.com](mailto:hello@ring-first.com).

---

Contact: hello@ring-first.com