Skip to main content
Webhooks and API

API Reference Overview and Rate Limits

Every VoiceAIWrapper API endpoint group at a glance, the plan feature each needs, the rate limits, and the error responses to handle.

Written By voiceaiwrapper

Last updated 26 days ago

The VoiceAIWrapper API lets your own systems do from code what you'd otherwise do in the webapp: create campaigns, push leads, set up clients and workspaces, create web widgets, read form submissions and run external billing. This article lists every endpoint group, the plan feature each needs, how many requests you can send and the errors to handle.

To make your first call, start with Leads API Quick Start.

The basics

Base URLhttps://api.voiceaiwrapper.app/api/v2
On your own domainhttps://your-portal-domain/api/v2. See Use the API on Your White-Label Domain.
AuthenticationAuthorization: Bearer YOUR_API_KEY on every request. See Create and Manage API Keys.
FormatJSON request and response bodies, with Content-Type: application/json
IDsUse IDs exactly as the API or the webapp gives them to you.

One key works for your whole organization. The request URL picks the campaign, client or form.

Endpoint groups

All paths are relative to the base URL. Where a path shows {id}, put the ID of that campaign, workspace, form, agent or client.

Campaigns and leads

Method and pathWhat it does
POST /voice-campaignsCreate a campaign.
PATCH /voice-campaigns/{id}Update a campaign's settings.
PATCH /voice-campaigns/{id}/statusChange a campaign's status.
GET /voice-campaigns/{id}/leads/listList a campaign's leads, a page at a time.
POST /voice-campaigns/{id}/leadsAdd one lead.
POST /voice-campaigns/{id}/leads/bulkAdd many leads (processed in the background).
PATCH /voice-campaigns/{id}/lead/updateUpdate one lead.
PATCH /voice-campaigns/{id}/leads/update/bulkUpdate many leads.
DELETE /voice-campaigns/{id}/lead/removeRemove one lead.
DELETE /voice-campaigns/{id}/leads/remove/bulkRemove many leads.

Creating a campaign counts toward your plan's campaign limit. At the limit, the API returns status 403 with Campaign limit reached in its errors list.

Clients and workspaces

Method and pathWhat it does
GET /clientsList your clients.
GET /clients/{id}Get one client's details.
POST /clients/createCreate a client account.
GET /agents/{id}/clientsList the clients an agent is assigned to.
GET /client-account-configurations/{id}/resourcesList what's assigned to a workspace: agents, phone numbers, knowledge bases, tools and campaigns.
POST /client-account-configurations/{id}/resources/assignAssign resources to a workspace. This replaces everything you've assigned to it, so send the full set. Items the client added itself are kept.

In the API, a workspace is called a client account configuration.

Widgets, forms and Pods

Method and pathWhat it does
POST /web-widgetsCreate a web widget.
GET /client-forms/{id}/submissionsGet a form's submissions. Add ?client_id= to limit them to one client.
POST /voiceai-podConnect a provider account as a new Pod (an engine or provider connection).

External billing

These endpoints live under /external-billing. They let your billing system read clients' subscriptions and usage and mark payment requests as paid. See Automate External Billing with the API.

Method and pathWhat it does
GET /external-billing/subscriptionsList subscriptions.
GET /external-billing/subscriptions/{id}/Get one subscription.
GET /external-billing/payment-requestsList payment requests.
GET /external-billing/payment-requests/{id}/Get one payment request.
PATCH /external-billing/payment-requests/{id}/updateUpdate a payment request, for example to mark it paid.
GET /external-billing/usageGet usage.

List endpoints in this group return 20 items per page by default. Set page_size (up to 100) and page to move through the results.

If you use GoHighLevel, VoiceAIWrapper writes a link to each call's recording into the contact. These links play from /api/v2/…/recording/… on your custom domain when you have one. They don't need an API key, and you don't call them yourself. See Call Results in GoHighLevel Contacts.

Version 1 (legacy)

The older base URL https://api.voiceaiwrapper.app/v1/api only offers add, update and remove for a single lead. Build new integrations on version 2.

Which plan features you need

EndpointsPlan features needed
Campaigns, leads, clients, workspaces, widgets, forms and Pods (version 1 and 2)Campaigns API and Platform API
The same endpoints, called on your custom domainAlso White-labeled campaigns API
External billingExternal billing API
Creating API keysPlatform API

When a feature is missing, version 2 returns status 403 with a message that starts "You've discovered a premium feature!" and ends with an error code naming the missing feature. External billing returns its own 403 message. The legacy version 1 endpoints can instead return status 500 with Internal server error, and the "premium feature" text in the response's exception field. Check your plan in the webapp, or see Compare Plans.

Rate limits

EndpointsLimit
Every version 2 endpoint above, including external billing100 requests per minute
Version 1 lead endpoints100 requests per minute

Limits count per API key and per endpoint. For example, 100 Add Lead calls in a minute don't use up your Get Leads allowance.

When you go over, the API returns status 429:

{
  "message": "Rate limit exceeded. Please try again later.",
  "error": "RATE_LIMIT_EXCEEDED"
}

To stay under the limit:

  • Use the bulk endpoints. One Add Bulk Leads request can carry many leads.
  • Retry a 429 after a short pause instead of straight away, and back off further if it happens again.
  • Spread large imports over several minutes.

Rate limits are separate from call concurrency, which caps how many calls run at once. See 'Concurrency Limit Reached' and '429 Too Many Requests'.

Errors to handle

Most errors return a JSON body with a message. These come from the key and plan checks that run before every request:

StatusMessageWhat to do
401Authorization header not found or Bearer token not foundSend Authorization: Bearer YOUR_API_KEY.
404API key not foundThe key was deleted or mistyped. Copy it again.
403API key is disabledTurn the key's Enabled switch back on.
403"You've discovered a premium feature!…"Your plan is missing a feature. See the table above.
402Your subscription is paused. Resume it from your billing settings to use the API again.Resume your subscription.
405Invalid request methodUse the method listed for the endpoint (GET, POST, PATCH or DELETE).
429Rate limit exceeded. Please try again later.Slow down and retry.
400Varies, for example Invalid data with a list of problemsFix the request body.
500Internal server errorRetry later. If it keeps happening, contact support with the request you sent.

To see the requests you've sent and the responses, use API & Webhook Logs if your plan includes API & webhook logs.

Frequently asked questions

There's no fixed number of leads per bulk request, but a request body larger than a few megabytes fails with an error. Split big imports into several smaller batches, and stay within the rate limit.

Yes. Keys aren't tied to an endpoint group. Each endpoint checks your plan features separately.

Clients don't get keys of their own. With the White labeled API permission, a client sees the leads API documentation in their portal, and the examples use your organization's API keys. That means the client can call the API with those keys, so give the permission only to clients you trust. See Use the API on Your White-Label Domain.