Ringostat
Log in

/rpc methods: calls with an API key

~8 min · The main JSON-RPC methods for a backend: projects, campaigns, numbers, results.

/rpc is the JSON-RPC 2.0 API behind the dashboard. Your backend calls it with a project API key: one POST per call, no session. Below are the methods an integration needs most; every one also exists as an MCP tool, and the “API” section shows the /rpc name under each method.

POST https://apiagent.ringostat.com/rpc
X-API-Key: <YOUR_API_KEY>
Content-Type: application/json

{ "jsonrpc":"2.0", "id":1, "method":"getCampaignStats",
  "params":{ "projectID":217, "campaignID":799 } }

→ 200 { "jsonrpc":"2.0", "id":1, "result":{ … } }
→ 200 { "jsonrpc":"2.0", "id":1,
        "error":{ "code":-32603, "message":"Internal error",
                  "data":"unauthorized access to project" } }

Send projectID yourself: a key opens only its own project, and most methods do not fill it in (addNumbers and uploadNumbersCSV do). A method error comes back with HTTP 200 and error.code -32603; the reason is in error.data. An unknown method is -32601. No key or an invalid one gets HTTP 401 with a plain-text body; more than 60 requests per second from one IP and key gets HTTP 429 for a minute. A request is at most 20 MB, a list page at most 1000 rows; batches (an array of requests) are not supported.

Spell parameter names exactly as the examples show: /rpc does not convert them, MCP does. Where a method's /rpc names differ from its MCP tool, the API page lists them under the method (“other parameter names”): for example campaign.getCallDetail, campaign.getStructuredReport and campaign.resendCallWebhook take project_id and number_id, updateProject takes project_id, integrations.list and shareProject take projectId. Number rows in responses use PascalCase (PhoneNumber, Status).

getProjects — the key's project: ID, name, balance in USD and the concurrent calls limit. This is where your projectID comes from.

{ "jsonrpc":"2.0", "id":1, "method":"getProjects",
  "params":{} }

→ "result": { "projects":[ { "ID":217, "Name":"My project",
    "CurrentBalance":34.44, "MaxConcurrentCalls":3, … } ] }

getCampaignStatus — the project's campaigns with their settings and number counters (stats). The result is an array, also for one campaignID. Without limit it returns every campaign: on a large project page with limit and offset (up to 1000) and ask for fields: "summary". A campaign is dialing when started is true and paused and isArchived are false.

{ "jsonrpc":"2.0", "id":1, "method":"getCampaignStatus",
  "params":{ "projectID":217, "campaignID":799 } }

→ "result": [ { "id":799, "name":"Order confirmation", "type":"aisdr",
    "started":true, "paused":false, "isArchived":false,
    "stats":{ "total":120, "pending":80, "completed":31, "failed":4, … }, … } ]

uploadCampaign — creates a campaign (no campaignID) or changes several of its fields (with campaignID: the keys you send overwrite, the rest stays). type: simple (“Informational Call”), aisdr (“Voice Agent”) or multi_question_dtmf (“Interactive Survey”). A new campaign is active at once and dials numbers as soon as they are added, so create it with "pause": true. retryDelay is in minutes.

{ "jsonrpc":"2.0", "id":1, "method":"uploadCampaign",
  "params":{ "projectID":217, "name":"Order confirmation",
    "type":"aisdr", "language":"en-US", "timezone":"Europe/Kyiv",
    "pause":true } }

→ "result": { "id":799, "started":true, "paused":true, … }

# change several fields of an existing campaign
{ … "method":"uploadCampaign",
  "params":{ "projectID":217, "campaignID":799, "simultaneousCalls":3 } }

updateCampaignField — changes one field. Start and stop with the paused field (false / true); archiving (isArchived: true) needs a paused campaign. Starting (paused: false) runs the compliance check, which can take a few seconds or refuse.

{ "jsonrpc":"2.0", "id":1, "method":"updateCampaignField",
  "params":{ "projectID":217, "campaignID":799,
    "field":"paused", "value":false } }

→ "result": { "message":"…", "campaign":{ "id":799, "paused":false, … } }

addNumbers — adds numbers to the queue; projectID is taken from the key. phone in international format; customFields reach the bot and the webhook, and their values must be strings; scheduledTime (Unix seconds) delays the call. Invalid, blocked and duplicate numbers are skipped and listed in rejected.

{ "jsonrpc":"2.0", "id":1, "method":"addNumbers",
  "params":{ "campaignID":799, "numbers":[
    { "phone":"+14155550123", "customFields":{ "name":"John" } } ] } }

→ "result": { "message":"Successfully added 1 numbers to campaign 799",
  "numbers":[ { "ID":1001, "PhoneNumber":"+14155550123", "Status":"pending", … } ],
  "rejected":[] }

uploadNumbersCSV — the same from CSV text: a phone column (spelled exactly), an optional scheduledTime, every other column becomes a custom field. Every row needs as many columns as the header.

{ "jsonrpc":"2.0", "id":1, "method":"uploadNumbersCSV",
  "params":{ "campaignID":799,
    "csvContent":"phone,name\n+14155550123,John\n" } }

→ "result": { "message":"…", "count":1, "rejected":[] }

removeNumber removes a number from the campaign (numberID, or phoneNumber: every row with that phone); a number in a call is refused. clearPendingNumbers stops the queue: pending and retry numbers become abandoned, the campaign itself keeps running.

{ "jsonrpc":"2.0", "id":1, "method":"removeNumber",
  "params":{ "projectID":217, "campaignID":799, "numberID":1001 } }

→ "result": { "message":"Number removed successfully", … }

{ … "method":"clearPendingNumbers",
  "params":{ "projectID":217, "campaignID":799 } }
→ "result": { "message":"…", "updatedCount":80, … }

getCampaignStats — one campaign's counters by status, call durations in seconds, DTMF answers and spend (approxCostUSD is approximate).

{ "jsonrpc":"2.0", "id":1, "method":"getCampaignStats",
  "params":{ "projectID":217, "campaignID":799 } }

→ "result": { "campaignID":799,
  "stats":{ "total":120, "completed":31, "failed":4, "voicemail":6, … },
  "durationStats":{ "avgConnectedDuration":48, … },
  "spend":{ "unitsConsumed":52000, "approxCostUSD":5.2, … } }

getCampaignNumbers — the call log: numbers with status, times (Unix seconds), custom fields, DTMF answers and AI reports. Filters: status, dates, search, durations; pages with limit (default 50, up to 1000) and offset, total is the count before paging. fields: "summary" leaves out the reports.

{ "jsonrpc":"2.0", "id":1, "method":"getCampaignNumbers",
  "params":{ "projectID":217, "campaignID":799,
    "status":"completed", "limit":100, "offset":0 } }

→ "result": { "total":31, "limit":100, "offset":0,
  "numbers":[ { "ID":1001, "PhoneNumber":"+14155550123", "Status":"completed",
    "StartTime":1760437400, "Duration":56, "CustomFields":{ "name":"John" },
    "StructuredReports":[ … ], … } ] }

campaign.getCallDetail — one call: the number row, the transcript, the AI report, the recording and the webhook deliveries. The recording file is at GET /audio/recording/{number_id} on the same host, with the same X-API-Key.

{ "jsonrpc":"2.0", "id":1, "method":"campaign.getCallDetail",
  "params":{ "project_id":217, "number_id":1001 } }

→ "result": { "number":{ … },
  "messages":{ "messages":[ { "role":"assistant", "content":"…" }, … ] },
  "structured_report":{ … }, "recording":{ "duration_seconds":56, … },
  "webhook":{ "attempts":[ … ] } }

campaign.getStructuredReport — the AI report of one call (number_id) or the latest one of a campaign (campaign_id): outcome and detailed_report with the fields from the campaign's report settings. Only AI-agent calls have reports.

{ "jsonrpc":"2.0", "id":1, "method":"campaign.getStructuredReport",
  "params":{ "number_id":1001 } }

→ "result": { "campaign_id":799, "number_id":1001,
  "outcome":"…", "detailed_report":{ "summary":"…", … } }

campaign.resendCallWebhook — sends a finished call's report to the campaign webhook again (the key's creator must be a project admin). It is a real request to your endpoint: the result has its statusCode and success.

{ "jsonrpc":"2.0", "id":1, "method":"campaign.resendCallWebhook",
  "params":{ "project_id":217, "number_id":1001 } }

→ "result": { "statusCode":200, "success":true, "requestBody":"…", … }

webCall.create — a one-time web call token for a site visitor (the “Web calls” guide). It works only with a “Web calls only” key: a full key is refused. clientIp is the visitor's public IP address; the token lives 20 seconds and works once, and the browser connects to wsUrl with it. A refusal comes with its code in error.data.code (busy, rate_limited, insufficient_funds and so on) and the matching HTTP status.

{ "jsonrpc":"2.0", "id":1, "method":"webCall.create",
  "params":{ "campaignId":799, "clientIp":"203.0.113.7" } }

→ "result": { "token":"wct1.…",
  "wsUrl":"wss://apiagent.ringostat.com/ws/web-call",
  "expiresIn":20, "maxDurationSec":180, "callId":"…" }