Skip to content
Your AI receptionist

Frontivo.io API and API keys

Takes 5 minutesYou need: Growth (opens soon - reserve it at no charge), or the free trial meanwhile, and the "Manage webhooks and secret keys" permission

The Frontivo.io API lets your developer's code, or tools like Make and n8n, read your leads and bookings, add new leads and subscribe to events. Each request uses an API key: a secret code that works like a password for software.

Create an API key

  1. 1Open Integrations in your dashboard and click For developers.
  2. 2Click the API keys tile, then click Create API key on its card.
  3. 3Type a name that says where you'll use it, for example "Website form".
  4. 4Click Create API key.
  5. 5Click Copy key straight away. For your security, the key is only shown once.
  6. 6Paste the key where your tool or developer needs it.
  7. 7Click I've copied it to hide the key.

Keys start with fk_live_. Account owners have the Manage webhooks and secret keys permission; other team members need it to see this section. A business can have up to 10 keys.

Send the key with each request

The API's address is https://frontivo.io/api/v1. Send your key in an Authorization: Bearer fk_live_... header, or in an X-API-Key header.

Example: list your 5 newest leads.

curl "https://frontivo.io/api/v1/leads?limit=5" -H "Authorization: Bearer fk_live_YOUR_KEY"

Example: add a lead.

curl -X POST https://frontivo.io/api/v1/leads -H "Authorization: Bearer fk_live_YOUR_KEY" -H "Content-Type: application/json" -d '{"name": "Sam Lee", "phone": "+1 555 123 4567", "source": "website_form"}'

Endpoints

  • GET /api/v1/me: the business this key belongs to (name and time zone). A quick way to test a key.
  • GET /api/v1/leads: your leads, newest first. Add limit (1 to 100, default 25) and since (a date and time like 2026-09-30T08:00:00Z) to get only newer ones.
  • POST /api/v1/leads: add a lead. Send JSON with name (required) and, if you have them, phone (with the country code), email, serviceRequested, notes, source and callConsent (true when the person agreed to a phone call, for example by ticking an "OK to call me" box; with Call new website leads on, your AI then calls them within minutes). With callConsent: true you must also send consentText (the exact words they agreed to) and consentSourceUrl (the web address of the form, or where they agreed); without them the lead is refused with an error. The new lead goes to your webhooks, team alerts and CRM like any other lead. Sending exactly the same lead again within 10 minutes (for example when Zapier retries) returns the lead already made instead of adding a copy.
  • GET /api/v1/appointments: your bookings, newest first, with the same limit and since options plus status (for example cancelled).
  • GET /api/v1/events/sample?event=lead.created: a few recent records in the same shape a webhook sends, or one sample marked sample: true if you don't have any yet.
  • POST /api/v1/hooks: subscribe to an event. Send JSON with url (a public https:// address) and event (for example handoff.requested). You get back an id, and the subscription shows in your Webhooks list.
  • DELETE /api/v1/hooks/{id}: remove that subscription.

Test data from the Channel tester is never included. The API can't change or delete leads, bookings or conversations, and it doesn't include conversation transcripts or add knowledge base documents.

Events and signatures

Webhooks and hook subscriptions receive events like {"event": "lead.created", "businessId": "...", "occurredAt": "...", "data": {...}}. Events: lead.created, lead.updated, appointment.created, appointment.updated, appointment.cancelled, call.completed, handoff.requested (a conversation needs a person) and customer.waiting (a customer your team is handling wrote again, or is still waiting).

data has the ids, plus the full lead, appointment and conversation details where they apply (a conversation has its summary, not the full transcript), the reason for a handoff, and a dashboardUrl that opens it in Frontivo.io. customer.waiting also has message (the first 120 characters of what the customer wrote), stillWaiting (true for the reminder) and, for the reminder, waitingMinutes.

Every event is signed. The X-Webhook-Signature header is an HMAC-SHA256 (hex) of the raw request body, made with the endpoint's Signing secret from the Webhooks list. The X-Webhook-Event header names the event. Compare the signature before trusting an event.

Limits

  • Each key can make 120 requests a minute. After that you get a 429 error with Retry-After: 60. Wait a minute and try again.
  • Up to 10 API keys and 50 webhooks (including hook subscriptions) per business.
  • API access comes with Growth. On other plans, keys keep existing but get a 403 error until you upgrade.

Revoke a key

Click Revoke next to the key and confirm. Anything using it stops working right away. Revoke any key you think someone else may have seen, and create a new one.

Troubleshooting

I get a 401 error or "the key isn't valid"

Copy the key again (it starts with fk_live_) and check no spaces were added. Send it as Authorization: Bearer <key> or X-API-Key: <key>. If you no longer have it, revoke it and create a new key.

I get a 403 error about my plan

API keys come with Growth, which opens soon - reserve it at no charge on Plan & Billing. Your existing keys work again once you're on Growth.

I get a 429 error

That key made more than 120 requests in a minute. Wait a minute, then send fewer requests (for example, use since to fetch only new leads, or subscribe to events instead of checking often).

I lost the key

We can't show it again, because we only keep a scrambled version for your security. Click Revoke on the old key, create a new one and use that.

I can't see the API keys section

You need the Manage webhooks and secret keys permission. Ask your account owner to give it to you, or to create the key.

Related articles