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
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
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
In the API, a workspace is called a client account configuration.
Widgets, forms and Pods
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.
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.
Recording links
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
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
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
429after 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:
To see the requests you've sent and the responses, use API & Webhook Logs if your plan includes API & webhook logs.
Frequently asked questions
Is there a limit on how many leads one bulk request can hold?
Is there a limit on how many leads one bulk request can hold?
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.
Can I use the same key for leads and external billing?
Can I use the same key for leads and external billing?
Yes. Keys aren't tied to an endpoint group. Each endpoint checks your plan features separately.
Can my clients call the API?
Can my clients call the API?
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.
Related articles
Was this helpful?
More in Webhooks and API
Which Webhook Should I Use?Post-Call Event WebhookPre-Call Context WebhookPre-Call Decisions: Call Later, Do Not Call and RejectStill need help? Share an idea