Skip to main content
The Ringg AI API lets your backend create assistants, initiate calls, run campaigns, manage numbers, and retrieve post-call results. Use this page as the mental model before jumping into individual endpoints.

​
API Architecture

Ringg AI provides REST-style APIs that allow you to:
  • Create and manage AI voice assistants
  • Initiate individual and bulk calls
  • Embed voice assistants on websites
  • Manage reusable contact lists and phone numbers
  • Access call history and analytics
  • Subscribe assistants to webhook events

​
Base URL

All API requests should be made to the following base URL: 
https://prod-api.ringg.ai/ca/api/v0

​
Available Resources

The Ringg AI API is organized around the following main resources:
  • Workspace: Verify authentication, manage workspace metadata, users, credits, and API keys.
  • Assistant: Create, list, fetch, and configure AI voice assistants.
  • Numbers: Fetch caller numbers available for outbound calls and campaigns.
  • Calling: Initiate individual outbound calls and inspect call history.
  • Campaigns: Upload campaign CSVs, start bulk calls, and monitor campaign state.
  • Webhooks: Subscribe assistants to call, recording, and analysis events.
  • Analytics: Build dashboards from call, number, duration, and classification metrics.

​
Request and Response Formats

Most Ringg API endpoints accept and return JSON. Use this header for POST and PATCH requests with JSON bodies: 
Content-Type: application/json
For campaign CSV uploads and contact CSV uploads, send multipart/form-data and let your HTTP client set the Content-Type boundary.

​
Common Headers

All API requests require the following headers:
  • X-API-KEY: Workspace API key for authentication.
  • Content-Type: Set to application/json for JSON requests. Omit it for FormData/multipart requests unless your HTTP client requires otherwise.

​
Core ID fields

Store these IDs in your application. They are how Ringg APIs and webhooks connect.
IDWhere it comes fromWhere it is used
agent_idAssistant APIs or dashboardIndividual calls, campaigns, webhook subscriptions
from_number_idGET /workspace/numbersIndividual outbound calls
list_id / bulk_list_idCampaign uploadCampaign start, campaign analytics, history filters
call_idCall initiation, call history, webhooksWebhook dedupe, call details, support debugging

​
Error Handling

The Ringg AI API uses conventional HTTP response codes to indicate the success or failure of requests:
  • 2xx: Success
  • 4xx: Client errors (invalid request, authentication issues)
  • 5xx: Server errors
Error responses include a JSON body with details about what went wrong: 
{
  "error": {
    "code": "invalid_request",
    "message": "The mobile_number parameter is required"
  }
}

​
Common Error Codes

  • 400: Bad Request – Invalid parameters or request format
  • 401: Unauthorized – Invalid or missing API key
  • 404: Not Found – Resource doesn’t exist
  • 429: Too Many Requests – Rate limit exceeded
  • 500: Internal Server Error – Something went wrong on our end

​
API Versioning

The current version of the Ringg AI API is v0. The version is included in the base URL: 
https://prod-api.ringg.ai/ca/api/v0
Future versions will follow the pattern v1, v2, etc. We’ll provide ample notice before deprecating any API version to ensure a smooth transition for your applications.

​
Pagination

For endpoints that return lists of objects, the API supports pagination through the following query parameters:
  • limit: Number of items to return (default: 20, max: 100)
  • offset: Number of items to skip (default: 0)
  1. Verify API key with GET /workspace.
  2. Select an assistant with GET /agent/all.
  3. Select a number with GET /workspace/numbers.
  4. Make one call with POST /calling/outbound/individual.
  5. Configure webhooks for post-call events.
  6. Add campaigns, analytics, and history views.

​
Next Steps

Now that you understand the basics of the Ringg AI API, you’re ready to start building!
Check out our detailed documentation for each resource to learn more about specific endpoints and capabilities.