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.

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.