HeyRik public API
Everything you need to build with voice. Choose a resource to explore its endpoints, parameters and copy-ready examples.
Base URL and authentication
Send one account-scoped key with every request. Keep it on your server because it can place paid calls and access account data.
https://server.heyrik.com/api/v1Authorization: Bearer $HEYRIK_API_KEYNew to HeyRik? Follow the complete Academy course before using the endpoint catalogue.
Agents
6 operationsAn agent is the AI that speaks on a call. You define its behaviour as an ordered Conversation Flow (config.prompt_sections) — the same structured sections the dashboard builder uses — plus a voice, languages and call settings. Create one, then point a phone number at it or dial out with it.
Knowledge base
4 operationsGive an agent documents to answer from — a price list, a policy page, an FAQ. It quotes these instead of improvising.
Phone numbers
5 operationsList your numbers and choose which agent answers each one. Buying a number needs completed KYC and happens in the dashboard.
Calls
4 operationsDial out with an agent, then read back the transcript, recording, outcome and what it cost.
Custom APIs (integrations)
4 operationsRegister your own endpoint as a tool the agent can call mid-conversation — look up an order, check availability, create a ticket.
Voices
3 operationsBrowse the voice library, list your cloned voices, preview one, or clone a new voice from a short recording. A voice's id goes into voice_settings.voice_id on any agent.
Campaigns (bulk calling)
13 operationsCall a list of leads with one agent. Seed from a CSV/XLSX or push leads in live, then start, pause and export results. A campaign is continuous: leads that arrive after it has finished are dialled automatically. Every lead field is matched to the agent's input variables by meaning (AI), so a column called "Decision Maker" fills {{prospect_name}} without renaming. Each finished call can be POSTed to your webhook_url — see the Connect your backend guide.
/campaignsPOSTCreate a campaign/campaignsPOSTPush leads in live/campaigns/{id}/contactsGETOne lead with every call made to it/campaigns/{id}/contacts/{contactId}PATCHFix a lead before it is dialled/campaigns/{id}/contacts/{contactId}GETThe campaign's call log — every lead + its outcome/campaigns/{id}/contactsPOSTStart (or resume) calling/campaigns/{id}/startPOSTPause calling/campaigns/{id}/pausePOSTStop a campaign for good/campaigns/{id}/cancelGETProgress and stats/campaigns/{id}PATCHEdit campaign settings/campaigns/{id}GETExport results with outcomes/campaigns/{id}/exportDELETEDelete a campaign/campaigns/{id}Analytics
3 operationsThe numbers a dashboard is built around — calls made and connected, answer rate, talk time — overall, per agent, and as a daily series.
Agent settings
6 operationsWhat the builder UI fills its pickers from — the supported languages and performance tiers. Read these instead of hardcoding lists, so your dashboard never drifts from ours.
/providersGETLanguages, performance tiers, regions, and the default voice/voice-optionsPOSTRewrite a rough prompt into a better one/agents/enhanceGETAmbient audio clips (office, cafe) for calls/background-audiosGETWhether call recordings will actually be stored/recordings/configGETThe public plan catalogue (for your own pricing page)/plansCRM — leads & folders
13 operationsA lead pipeline you can drive entirely from your own app: import contacts, move them through stages, and dial them.
/leadsPOSTCreate a lead/leadsPOSTImport many leads at once/leads/bulkPOSTCall selected leads with an agent/leads/callGETPipeline totals and win rate/leads/summaryGETOne lead/leads/{id}PATCHUpdate a lead/leads/{id}POSTMove a lead to a pipeline stage/leads/{id}/stageDELETEDelete a lead/leads/{id}GETEvery call made to this lead/leads/{id}/callsGETYour pipeline stages, in order/crm/stagesGETLead folders (segments / lists)/crm/foldersPOSTCreate a folder (optionally with leads in it)/crm/foldersChat (text agents)
8 operationsTalk to an agent over TEXT — no phone call, no speech. Use a one-shot completion for a quick answer, or a stateful session that remembers the whole conversation. Billed per message (much cheaper than a call), so it's ideal for testing an agent's brain or powering a chatbot in your own product. Same agents as your calls — an agent id from POST /agents works here directly.
/chat/configPOSTOne-shot reply (stateless — no memory)/chat/completePOSTStart a stateful conversation/chat/sessionsPOSTSend a message, get the agent's reply/chat/sessions/{id}/messagesGETList conversations/chat/sessionsGETFetch a conversation with its messages/chat/sessions/{id}GETGet a downloadable transcript link/chat/sessions/{id}/transcriptDELETEDelete a conversation/chat/sessions/{id}Chat widgets
5 operationsEmbed a text agent on your own website. Create a widget, drop its snippet in, and those conversations arrive alongside your calls.
Account & balance
3 operationsWho the key belongs to, and how many credits are left — check this before starting a large campaign.
Errors
Failures return { "error": "code", "hint": "…" }. Use the status and hint to decide whether to correct, retry, or escalate.
invalid_requestA required field is missing or malformed. The `hint` says which.
api_key_requiredNo key sent, or it's revoked. Create one in the dashboard → API.
insufficient_creditsNot enough credits to start the call. `need` gives the minimum.
kyc_requiredIdentity verification isn't complete — finish it in the dashboard.
not_foundNo such id ON YOUR ACCOUNT. Keys never see another account's data.
name_already_usedThat name is taken — custom API names are unique per account.
rate_limitedToo many requests for this key. Back off and retry.
server_errorOur side. Safe to retry; contact support if it persists.
Dashboard-only actions
Money and regulated identity workflows stay in the HeyRik dashboard.