API Reference

API reference — core endpoints

A usage-level reference for the main HeyMello API endpoints, grouped by domain. All paths are relative to the base URL and require a bearer token unless noted.

Base URL:  https://<your-heymello-api-host>/api/v1
Auth:      Authorization: Bearer <access_token>

Admin-only and internal service endpoints are omitted from this reference.

Agents

Method & Path	Purpose
`GET /agents/`	List active agents in your organization.
`POST /agents/`	Create a new agent.
`GET /agents/{agent_id}`	Get an agent’s configuration.
`PUT /agents/{agent_id}`	Update agent fields.
`DELETE /agents/{agent_id}`	Delete an agent (and release its number).
`PATCH /agents/{agent_id}/prompt`	Update only the agent’s instructions.
`GET /agents/{agent_id}/versions`	List the agent’s change history.
`GET /agents/{agent_id}/versions/{version}`	View a historical version.
`POST /agents/{agent_id}/versions/{version}/restore`	Roll back to a prior version.
`GET /agents/meta/industries`	List selectable industries.
`GET /agents/meta/use-cases`	List selectable use cases (optionally by industry).

Voices

Method & Path	Purpose
`GET /voices/`	List the voice catalog (id, name, gender, preview audio).

Knowledge base

Method & Path	Purpose
`POST /knowledge-base/upload`	Upload a document.
`GET /knowledge-base/documents`	List uploaded documents.
`GET /knowledge-base/document/{kb_id}`	Get a document’s details.
`PUT /knowledge-base/document/{kb_id}`	Rename a document.
`DELETE /knowledge-base/document/{kb_id}`	Delete a document.
`GET /agents/{agent_id}/knowledge-base`	List documents attached to an agent.
`POST /agents/{agent_id}/knowledge-base/assign`	Attach documents to an agent.
`POST /agents/{agent_id}/knowledge-base/unassign`	Detach documents from an agent.

Tools & custom functions

Built-in tools

Method & Path	Purpose
`GET /builtin-tools/`	List available built-in tools.
`GET /builtin-tools/agent/{agent_id}`	List an agent’s built-in tool states.
`PUT /builtin-tools/agent/{agent_id}/{tool_id}`	Enable/disable and configure a built-in tool for an agent.
`DELETE /builtin-tools/agent/{agent_id}/{tool_id}`	Remove a built-in tool from an agent.

Custom functions (your own webhook integrations)

Method & Path	Purpose
`POST /agents/{agent_id}/custom-functions/`	Create a custom function for an agent.
`GET /agents/{agent_id}/custom-functions/`	List an agent’s custom functions.
`GET /agents/{agent_id}/custom-functions/{id}`	Get a custom function.
`PUT /agents/{agent_id}/custom-functions/{id}`	Update a custom function.
`DELETE /agents/{agent_id}/custom-functions/{id}`	Delete a custom function.

Calls

Method & Path	Purpose
`POST /calls/make-call`	Place a single outbound call (needs positive credit balance).
`GET /calls`	List call history (filter by call id / from / to).
`GET /calls/{call_id}`	Get full call detail (transcript + analysis).
`GET /calls/session/{session_id}`	Get call detail by session id.
`GET /calls/decrypt-transcript/{session_id}`	Retrieve a call transcript.
`GET /calls/recording/{session_id}`	Stream/download a call recording.

POST /calls/make-call body: agent_id, to_number, optional first_name/last_name, optional variables (custom placeholders for the prompt).

Phone numbers

Method & Path	Purpose
`GET /phone-numbers`	List phone numbers (filter by status/agent).
`GET /phone-numbers/org-numbers`	List all numbers your org owns.
`GET /phone-numbers/org-unassigned`	List org numbers ready to assign.
`GET /phone-numbers/pricing`	Current credit pricing per country/currency.
`POST /phone-numbers/purchase`	Buy a number and assign it to an agent.
`POST /phone-numbers/buy`	Buy a number into your org pool.
`POST /phone-numbers/{id}/assign`	Assign an owned number to an agent.
`POST /phone-numbers/{id}/unlink`	Detach a number from its agent.
`GET /phone-numbers/subscriptions`	List number subscriptions.
`POST /phone-numbers/subscriptions/{id}/cancel`	Cancel a number subscription.
`POST /phone-numbers/subscriptions/{id}/resume`	Resume a cancelled subscription.

Campaigns

Method & Path	Purpose
`GET /campaigns/`	List campaigns.
`POST /campaigns/`	Create a campaign from a JSON contact list.
`POST /campaigns/upload`	Create a campaign from an uploaded file (XLSX/CSV).
`POST /campaigns/validate-excel`	Dry-run validate a contact file before saving.
`GET /campaigns/{id}`	Get campaign details and progress.
`PUT /campaigns/{id}`	Update campaign settings.
`DELETE /campaigns/{id}`	Cancel a campaign.
`PATCH /campaigns/{id}/start`	Start dialing a pending campaign.
`PATCH /campaigns/{id}/pause`	Pause an active campaign.
`PATCH /campaigns/{id}/resume`	Resume a paused campaign.
`POST /campaigns/{id}/rerun`	Clone a finished campaign into a new one.
`POST /campaigns/{id}/contacts`	Append contacts (JSON).
`POST /campaigns/{id}/upload`	Append contacts (file).
`GET /campaigns/{id}/numbers`	List contacts/calls in a campaign.
`GET /campaigns/{id}/analytics`	Campaign metrics (connect rate, outcomes, avg duration).
`GET /campaigns/{id}/export`	Export campaign + call results.

Callbacks

Method & Path	Purpose
`POST /callbacks/`	Register a callback request.
`GET /callbacks/`	List upcoming callbacks.
`PATCH /callbacks/{id}/reschedule`	Reschedule a callback.
`DELETE /callbacks/{id}`	Cancel a callback.

Bookings

Method & Path	Purpose
`GET /bookings`	List all appointments booked across your org.
`GET /agents/{agent_id}/bookings`	List appointments booked by one agent.

Post-call analysis

Method & Path	Purpose
`GET /agents/{agent_id}/post-call-analysis`	Get an agent’s analysis configuration.
`PUT /agents/{agent_id}/post-call-analysis`	Update analysis config (prompt, outcomes, success outcomes, notification emails).

Analytics

Method & Path	Purpose
`GET /analytics/calls/summary`	Totals, success rate, duration, inbound/outbound split.
`GET /analytics/calls/attempts`	Dial-attempt breakdown + best-time-to-call heatmap.
`GET /analytics/calls/sentiment`	Sentiment distribution.
`GET /analytics/calls/outcomes`	Outcome funnel per agent.
`GET /analytics/calls/time-trends`	Calls per day and busiest hours.
`GET /analytics/calls/agents`	Per-agent performance metrics.
`GET /analytics/calls/list`	Filterable, paginated call list (drill-through).
`GET /analytics/custom-fields/keys`	Discover extracted custom fields.
`GET /analytics/custom-fields/distribution`	Value distribution for a custom field.

Most analytics endpoints accept a days window or start_date/end_date, plus optional agent_id / campaign_id filters.

Transfer events

Method & Path	Purpose
`GET /transfer-events`	List call transfers across your org.
`GET /agents/{agent_id}/transfer-events`	List transfers for one agent.

Billing

Method & Path	Purpose
`GET /billing/balance`	Current credit balance.
`GET /billing/pricing`	Currencies and price per credit.
`GET /billing/plans`	Credit bundle plans for a country.
`GET /billing/transactions`	Credit ledger history.
`GET /billing/usage-summary`	Credits used, grouped by feature.
`GET /billing/invoices`	List invoices.
`GET /billing/invoices/{id}/pdf`	Get an invoice PDF link.
`POST /billing/topup/initiate`	Start a credit purchase (Stripe/Razorpay).
`PATCH /organisations/me/billing`	Update billing country / VAT-GST number.

Organizations & users

Method & Path	Purpose
`GET /organisations/`	List your organizations.
`GET /organisations/{id}`	Get organization details.
`PATCH /organisations/{id}`	Update organization profile.
`GET /users/`	List users in your organization.
`GET /users/{user_id}`	Get a user profile.
`PATCH /users/{user_id}`	Update a user (role/status/profile).
`POST /auth/invite` (via auth)	Invite a teammate to your org.
`GET /users/me/data-export`	Export your personal data (GDPR).
`DELETE /users/me/erase`	Erase/anonymize your personal data (GDPR).
`GET /login-history/{user_id}`	Review sign-in history.

Looking for something not listed here? It may be admin-only or handled in the dashboard. Contact your account team.