Part 2A — Setup: basics, accounts, numbers

← Contents · Previous: Part 1 · Next: Part 2B2A — Call flowsSetup

EveryRead endpointthis herepage needsbefore Authorization:the Bearerendpoints. <apiRingmaster key>is (🔒).the Theengine envelopeof an intelligent call centre; your service is a client app built on it. This page explains the engine's objects, how a call runs, and error codes are on the contents page.

A. Basics

A1. Ping

Purpose: Check the key works and see which featureswhat the client app has.must do at each step.

Endpoint:

1.1 {base_url}/ping

Who's

Access Level: 🔒 Protected · Bearer API key

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "200 OK",
  "message": "pong",
  "action": null,
  "action_time": "2026-11-13T19:57:58.900619432",
  "data": {
    "clientAppId": "bd74035b-bdb6-450d-885b-222e83719906",
    "name": "softphone-test",
    "features": ["INBOUND", "CALLOUTS", "OTP", "AI"]
  }
}

who

Ringmaster owner
 └── Client app  (API key, webhook URL, features)
      ├── Account: PMK Chemicals  (hours, quiet hours, recording, limits)
      │    ├── Numbers ── each plays one pinned flow version
      │    ├── Call flows ── versions v1, v2, v3 …
      │    ├── Departments ── agents
      │    ├── Media (audio files), knowledge base (for the AI), opt-outs
      │    └── Calls, call-outs, reports
      └── Account: Kliniki ya Afya Bora …

A client app maps its own objects to these: one of its businesses = an account (externalRef = its business id), one of its users who answers calls = an agent (ref = its user id).

1.2 Getting access

The Ringmaster owner creates the client app once and gives it:

{
  "success": false,if "httpStatus": "401 UNAUTHORIZED",
  "message": "Missing or invalid API key",
  "code": "UNAUTHORIZED",
  "action_time": "2026-11-13T19:57:59.067583389",
  "data": null
}

1. POST  /v1/accounts                         {externalRef: "pmk-chemicals"}        → accountId
2. PATCH /v1/accounts/{accountId}             {businessName, hours, quietHours, …}
3. GET   /v1/numbers?status=ALLOCATED          free numbers the owner gave the client app
   POST  /v1/numbers/{numberId}/assign         {accountId, label}
4. PUT   /v1/accounts/{accountId}/scripts/orders            {name, direction: "INCOMING"}
   POST  /v1/accounts/{accountId}/scripts/orders/versions   {version: 1, definition, runnable: true}  → versionId
5. PUT   /v1/numbers/{numberId}/script         {scriptVersionId}

Caller dials +255677000010
   │  phone network → SIP trunk → LiveKit room → voice worker joins
   ▼
Engine: which account and which flow version is pinned on the number?   (none → call refused, NO_SCRIPT)
   │  checks: app active, account active, INBOUND on, caller under the per-caller limit
   ▼
call.started webhook ──────────────────────────────────────────► client app
   │
   ▼  blocks run one after another, starting at the flow's start block
   cataloguesay a"Karibu flowPMK editorChemicals…" needs:→ menu "Bonyeza 1 kuagiza…" → (caller presses 1 or says "oda")
   │      every blockstep type,is itswritten group, what it does, its exits, whether
it needs approval;to the rules;call's timeline (BLOCK_ENTER, SAY, KEYS, SPEECH, …)
   │      call.block webhooks for the messagesteps shape;clients thecare variablesabout a(menu flowchoice, canApp use;action, an…)
   example▼
   flow.
… collect → pick → confirm → goodbye
   ▼
Call ends ─► call.ended webhook (full summary: result, durations, keys, outcomes, cost)
         └─► recording.ready / summary.ready later, if anything was recorded

{
  "success": true,
  "httpStatus": "200 OK",
  "message": "Script schema",
  "action": null,
  "action_time": "2026-11-13T19:58:20.112842101",
  "data": {
    "schemaVersion": "1",
    "blocks": [
      { "type": "say", "group": "Speak", "description": "Say a text or play an audio message, then continue.",
        "exits": ["next"], "needsApproval": false },
      { "type": "menu", "group": "Ask",
        "description": "AskWhat the caller tohears pickis played in order, block after block: a block's sound finishes before the next block's
sound starts. Blocks that make something happen for a person wait for that too: a Connect block rings agents only
after the caller has heard everything before the waiting music.

Statuses of a call (status): QUEUED → DIALING → RINGING (outgoing only) → IN_SCRIPT → WAITING
(waiting room) → CONNECTING → LIVE (with an optionagent) by→ keyENDED. or,After whenit speechends, isresult on,says byhow voiceit …"went
(HANDLED_BY_SCRIPT, "exits": ["<option>"HANDLED_BY_AGENT, "noInput"HANDLED_BY_AI, "notUnderstood"VOICEMAIL, "later"]MISSED, "needsApproval": false }NO_ANSWER, { "type": "collect"BUSY, "group": "Ask"DECLINED…),
"description":endReason "Collectwhy ait numberended and endedBy who ended it. All values: Part 4.

Guards that protect every account (account,account PIN, amount) into {input.<name>}."limits, "exits"changeable with PATCH /v1/accounts/{id}): ["ok", "failed", "later"], "needsApproval": true }
    ],
    "rules": [
      "direction is INCOMING (start exit 'call') or OUTGOING (start exit 'out'); never both",
      "every block: {type, …settings, before?: message, wr?: waiting room, x: {exit: blockId}}; a missing exit ends the call",
      "at most 60 blocks, 10 menu keys, 3 retries; text at most 500 characters"
    ],
    "messageShape": {
      "text": { "src": "text", "text": "Habari {name}", "lang": "sw",
                "voice": "marin|coral|shimmer|sage|cedar|ash|echo|ballad|verse", "speed": "0.7-1.5 (1.0 normal)…" },
      "audio": { "src": "record|upload|library", "media": "<mediaId>" }
    },
    "systemVariables": ["date", "time", "lang", "answeredBy", "key", "heard", "number", "caller", "callId"],
    "example": {
      "direction": "INCOMING",
      "start": { "call": "greet" },
      "blocks": {
        "greet": { "type": "say", "msg": { "src": "text", "text": "Karibu!" }, "x": { "next": "menu" } },
        "menu": { "type": "menu", "msg": { "src": "text", "text": "Bonyeza moja kwa mauzo, mbili kwa msaada." },
                  "options": [ { "k": "1", "id": "sales", "label": "Mauzo", "words": ["mauzo", "kununua"] },
                               { "k": "2", "id": "help", "label": "Msaada", "words": ["msaada", "tatizo"] } ],
                  "x": { "sales": "sales", "help": "help", "noInput": "bye", "notUnderstood": "bye" } },
        "sales": { "type": "say", "msg": { "src": "text", "text": "Bei zetu ziko kwenye tovuti yetu." }, "x": { "next": "bye" } },
        "help": { "type": "say", "msg": { "src": "text", "text": "Mhudumu atakupigia leo." }, "x": { "next": "bye" } },
        "bye": { "type": "goodbye", "msg": { "src": "text", "text": "Asante, kwaheri." } }
      }
    }
  }
}

1.5 Calling people (call-outs)

The fullengine meaningplaces ofcalls everyfor blockan settingaccount isand inplays SCRIPTS.md.an TheOutgoing schemaflow is generated fromwhen the engine'sperson code, so it always matches what the engine accepts; cache it per schemaVersion.answers.

A3. Check a script (dry run)

Purpose: Validate a flow document without storing it: the same checks as pushing a version. Use it in the editor on every save.

Endpoint: POST {base_url}/scripts/validate

Access Level: 🔒 Protected · Bearer API key

Request JSON Sample:

{
  "accountId": "adb72fac-66a2-471b-a437-035fe008197d",
  "definition": {
    "direction": "INCOMING",
    "start": { "call": "a" },
    "blocks": {
      "a": { "type": "say", "msg": { "src": "text", "text": "Hi" }, "x": { "next": "zz" } }
    }
  }
}

Each person on a call-out is a Successrecipient Responsewith JSONtheir Sampleown vars (e.g. {"name": "Asha", "amount": "45000"}) that the flow says as {name}, {amount}.

Rules the engine applies to every call-out (the checkclient ran;app thisdoesn't need to):

• Quiet hours (account quietHours, default 21:00–07:00): nobody is called inside them; calls wait for the end.
• Opt-outs: a number on the account's opt-out list is skipped (SKIPPED), checked again just before dialling.
• Retries: busy, no answer, unreachable or failed → tried again after retryGapSec (≥ 300 s) up to maxTries (quick call ≤ 3, campaign ≤ 5). Declined (the person rejected the call) is never retried.
• Pace: campaigns dial at most pacePerMin.

Call-out statuses: DRAFT → SCHEDULED → RUNNING ⇄ PAUSED → COMPLETED / STOPPED / CANCELLED. Recipient: PENDING → DIALING → DONE (with a result) or SKIPPED.

1.6 A call flow's life

PUT  …/scripts/{ref}                    create the flow (name, INCOMING or OUTGOING); direction never changes
POST …/scripts/{ref}/versions           push version 1, 2, 3 … — each version is frozen once stored
         │  the engine checks it (Part 5 §5.9): errors → 422 with the list, nothing stored
         │                                       warnings → stored, warnings returned
         ▼
      runnable?  ── no (you pushed runnable:false: it has risky blocks and waits for approval)
         │              POST …/versions/{n}/runnable  after the client app's approval step
         ▼ yes
PUT  /v1/numbers/{id}/script            put the version on a number (Incoming)     — or —
POST /v1/calls · /v1/callouts           use it for calls out (Outgoing)
POST …/versions/{n}/revoke              stop a version for good: a number still playing it refuses calls,
                                        call-outs using it pause (VERSION_REVOKED) — move them first
DELETE …/scripts/{ref}                  delete the flow (refused while anything uses it; archived if it ever ran)

• Versions never change. To change a flow, push the next version and move the number to it. Calls keep pointing at the exact version they ran, so reports stay true.
• Pushing the same version number with the same document again is safe: 200 "Version already stored".
• Approval is the client app's policy. Some blocks are risky: collect (callers' digits), request (calls a URL), ai_agent, and App actions the client app registered as risky (e.g. pay). The engine lists them in riskyBlocks when a version is checked or stored, and trusts the runnable flag it is given: push such a version with runnable: false, let the business's reviewer approve it in the client app, then POST …/versions/{n}/runnable. A not-runnable version can't be put on a number. A call-out may already use it: it is saved and waits (waitingApproval: true), then starts by itself once the version is approved.
• testOnly versions are for test calls only and never become runnable.
• Reading a flow back: GET …/scripts/{ref}/versions/{n} returns the full document. Secrets stored in Send request blocks come back as "(hidden)".
• Layout (block positions on the client app's canvas) belongs to the client app: the engine drops a layout key on push.
• Texts are turned into speech when the version is stored, so the first caller doesn't wait.

1.7 Agents in the browser

Client app (once): POST departments {name, strategy, ringTimeoutSec…}  ·  PUT agents/{ref} {displayName}
                 PUT departments/{id}/members {agentRefs: [...]}      (list order = round-robin order)

Agent's browser:
  "Start shift"  → client app backend → POST agents/{ref}/lobby-token → {url, room, token}
                 → browser joins the lobby room (LiveKit JS SDK, data only, no mic)
                 → client app backend → PUT agents/{ref}/status {AVAILABLE}
  A caller reaches a Connect block → hears "tunakuunganisha…", then music
                 → engine sends {type:"ring", callId, from, department} into the lobby
  "Accept"       → client app backend → POST /v1/calls/{callId}/accept {agentRef} → {url, room, token}
                 → browser joins the call room with the microphone on → they talk
  "Hold" / "Transfer" / "Hang up" → POST /v1/calls/{callId}/hold · /transfer · /hangup {agentRef}
  Call ends      → agent is WRAP_UP for the department's wrapUpSec, then AVAILABLE (or POST …/ready)

Agent statuses: OFFLINE → AVAILABLE → RINGING → BUSY → WRAP_UP → AVAILABLE; AWAY = on a break (online, no calls). One call at a time per agent. Missing maxMissedBeforeAway rings in a row (default 5) moves the agent to AWAY. Every change is sent as an error)agent.status webhook (for a wallboard).

Ring modes (per number, PUT /v1/numbers/{id}/ring-mode): BROWSER (agents' browsers), MOBILE (agents' mobiles), BROWSER_AND_MOBILE.

The browser needs HTTPS (or localhost) for the microphone, and the "Start shift" click is what allows the ring sound. Details of every signal: Part 3.

1.8 Webhooks

Every event is a signed POST to the client app's webhook URL:

POST https://app.example.co.tz/hooks/ringmaster
Content-Type: application/json
X-Ringmaster-Event: call.ended
X-Ringmaster-Delivery: 5b0c7f8e-…            (same as the body's id; use it to drop repeats)
X-Ringmaster-Timestamp: 1794588244
X-Ringmaster-Signature: 9f2c…                 hex HMAC-SHA256(secret, "<timestamp>.<raw body>")

{ "success": true,
  "httpStatus"id": "200 OK"5b0c7f8e-…", "message"type": "Validation result"call.ended", "action": null,
  "action_time"createdAt": "2026-11-13T18:06:38.004985164"13T16:44:04Z", "data": { "valid": false,
    "errors": [
      { "level": "ERROR", "block": "a", "code": "EXIT_TARGET_MISSING", "message": "Exit 'next' points to a missing block: zz" }
    ],
    "warnings": [],
    "vars": [],
    "texts": ["Hi"],
    "riskyBlocks": []… } }

• Answer 2xx quickly (do the work after). Anything else is retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, then every 12 h until 24 h have passed; then the event is marked failed.
• Events are written in the same database step as the change they describe, so none is lost; a repeat can arrive — drop it by id.
• Check the signature on the raw body before parsing, and refuse timestamps more than 5 minutes old.

All events and their data: Part 3.

1.9 App actions (the client app does something during a call)

Ringmaster never sends SMS, takes payments or tags contacts itself. The client app registers what it can do; a flow's App action block asks for it; the client app does it and answers.

PUT /v1/actions  [ {name: "pay", label: "Pay now", params: {...}, wait: true, outcomes: ["paid","failed"], timeoutSec: 120}, … ]

Caller in a flow reaches  "pay_1": {type: "app_action", action: "pay", params: {amount: "{amount}"}, x: {paid: …, failed: …, timeout: …}}
   engine ─► webhook action.requested {actionId, name: "pay", callId, params: {amount: "45000", phone: "+2557…"}, wait: true, timeoutAt}
   caller waits (music, "Thibitisha malipo kwenye simu yako")
   client app pushes M-Pesa … PIN entered …
   client app ─► POST /v1/calls/{callId}/action-result {actionId, outcome: "paid", data: {receipt: "QK7…"}}
   engine: the flow goes on through the "paid" exit; {action.pay_1.receipt} can be said

wait: false actions (send SMS, tag a contact) are fired and the call goes on at once.

1.10 Recordings, transcripts, summaries

TheAfter answera recording: recording.ready webhook → GET /v1/calls/{id}/recording (MP3). If recording.transcribe is alwayson (default), a transcript and a short summary follow: 200summary.ready when→ GET /v1/calls/{id}/transcript. Recordings are encrypted at rest and deleted after the document could be read;account's validretentionDays says(default whether90).

1.11 Costs

Every call carries providerCost: what it wouldcost beRingmaster stored.in Whenphone theminutes and AI, line by line.

"providerCost": { "tzs": 68.61, "usd": 0.000334, "items": [
  { "provider": "AT", "tzs": 68.61, "lines": [
      { "item": "AT_OUTBOUND", "qty": 1, "unit": "MINUTE", "rate": 60, "currency": "TZS", "amount": 60, "source": "RATE" },
      { "item": "AT_SIP_TRUNK", "qty": 1, "unit": "MINUTE", "rate": 8.61, "currency": "TZS", "amount": 8.61, "source": "RATE" } ] },
  { "provider": "OPENAI", "usd": 0.000334, "lines": [
      { "item": "OPENAI_TRANSCRIBE", "qty": 0.0742, "unit": "MINUTE", "rate": 0.0045, "currency": "USD", "amount": 0.0003339, "source": "MEASURED", "model": "gpt-transcribe" } ] } ] }

The client app hasdecides nowhat AIto feature,charge eachits blockcustomers; thatthese usesare AIinputs, (AInot Agent, speech.match: "smart") is an error with code FEATURE_OFF.prices.

B.

1.12 Accounts

An account is one business. Its id is used in most paths. externalRef is the client app's own id for it.

B1. Create an accountFormats

Purpose: Add a business. It starts with sensible defaults (hours Mon–Fri 08–17, Sat 09–13; quiet hours 21:00–07:00; recording of live parts with a Kiswahili notice; limits; 90 days retention).

Endpoint: POST {base_url}/accounts

Access Level: 🔒 Protected · Bearer API key

Request JSON Sample:

{
  "externalRef": "pmk-chemicals",
  "defaultLanguage": "sw",
  "timezone": "Africa/Dar_es_Salaam"
}

Success Response: 201 Created, data = the account, same shape as B3.

Errors:

{ "success": false, "httpStatus": "409 CONFLICT", "message": "An account with this externalRef already exists",
  "code": "ACCOUNT_EXISTS", "action_time": "2026-11-13T19:57:58.985027739", "data": null }

{ "success": false, "httpStatus": "422 UNPROCESSABLE_CONTENT", "message": "Validation failed",
  "code": "VALIDATION_FAILED", "action_time": "2026-11-13T19:57:59.051669172", "data": { "externalRef": "must not be blank" } }

{ "success": false, "httpStatus": "400 BAD_REQUEST", "message": "Unknown timezone: Mars/Base",
  "code": "BAD_REQUEST", "action_time": "2026-11-13T19:57:59.009578709", "data": null }

B2. List accounts

Purpose: All accounts of the client app, or the one with a given externalRef.

Endpoint: GET {base_url}/accounts

Access Level: 🔒 Protected · Bearer API key

Success Response: data = array of accounts (B3 shape).

B3. Get an account

Endpoint: GET {base_url}/accounts/{accountId}

Access Level: 🔒 Protected · Bearer API key

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "200 OK",
  "message": "Account",
  "action": null,
  "action_time": "2026-11-13T19:57:58.939219236",
  "data": {
    "id": "adb72fac-66a2-471b-a437-035fe008197d",
    "externalRef": "softphone",
    "status": "ACTIVE",
    "defaultLanguage": "sw",
    "timezone": "Africa/Dar_es_Salaam",
    "hours": {
      "days": {
        "MONDAY": [ { "from": "08:00", "to": "17:00" } ],
        "TUESDAY": [ { "from": "08:00", "to": "17:00" } ],
        "WEDNESDAY": [ { "from": "08:00", "to": "17:00" } ],
        "THURSDAY": [ { "from": "08:00", "to": "17:00" } ],
        "FRIDAY": [ { "from": "08:00", "to": "17:00" } ],
        "SATURDAY": [ { "from": "09:00", "to": "13:00" } ]
      }
    },
    "quietHours": { "from": "21:00", "to": "07:00" },
    "recording": {
      "mode": "LIVE_PARTS",
      "noticeText": "Mazungumzo haya yanarekodiwa kwa ajili ya ubora wa huduma.",
      "noticeMediaId": null,
      "transcribe": true
    },
    "limits": {
      "maxCallMinutes": 15,
      "maxWaitSeconds": 300,
      "callerCallsPer10Min": 100,
      "otpPerDestinationPer10Min": 3,
      "voicemailMaxSeconds": 120,
      "maxBlockVisits": 25
    },
    "hasRequestSigningSecret": false,
    "retentionDays": 90,
    "businessName": "Ringmaster Lab",
    "aiDisclosure": null,
    "createdAt": "2026-11-12T05:20:55.204082Z"
  }
}

Errors: 404 NOT_FOUND "Account not found" (unknown, or another client app's).

B4. Update an account

Purpose: Change any setting. Send only what changes; missing fields keep their value.

Endpoint: PATCH {base_url}/accounts/{accountId}

Access Level: 🔒 Protected · Bearer API key

Request JSON Sample:

{
  "businessName": "PMK Chemicals",
  "hours": { "days": { "MONDAY": [ { "from": "08:00", "to": "12:30" }, { "from": "14:00", "to": "17:00" } ] } },
  "quietHours": { "from": "20:00", "to": "08:00" },
  "recording": { "mode": "LIVE_PARTS", "noticeText": "Simu hii inarekodiwa.", "transcribe": true },
  "limits": { "maxCallMinutes": 20, "maxWaitSeconds": 300, "callerCallsPer10Min": 5,
              "otpPerDestinationPer10Min": 3, "voicemailMaxSeconds": 120, "maxBlockVisits": 25 },
  "retentionDays": 180,
  "aiDisclosure": { "sw": "Unazungumza na msaidizi wa kidijitali wa PMK.", "en": "You are talking to PMK's digital assistant." }
}

Success Response: the updated account (B3 shape).

C. Numbers

A number moves through three states:

POOL ──(owner gives it to the client app)──► ALLOCATED ──assign──► ASSIGNED (to one account) ──release──► ALLOCATED
                                                  ▲  remove (NUMBERS feature) ◄── POOL      transfer: account → account

Only an assigned number with a pinned, runnable Incoming flow answers calls.

C1. List numbers

Endpoint: GET {base_url}/numbers

Access Level: 🔒 Protected · Bearer API key

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "200 OK",
  "message": "Numbers",
  "action": null,
  "action_time": "2026-11-13T19:58:07.321779977",
  "data": [
    {
      "id": "8a8d9c13-bda2-4a18-8410-c5ec49ed2c66",
      "e164": "+255677000001",
      "status": "ASSIGNED",
      "accountId": "adb72fac-66a2-471b-a437-035fe008197d",
      "label": null,
      "incomingScriptVersionId": "e183c7f1-3137-4848-95c1-11a7e8bef17a",
      "verified": true,
      "verifiedAt": "2026-11-12T05:33:27.481181Z",
      "ringMode": "BROWSER"
    }
  ]
}

C2. Add a number

Purpose: Bring a Tanzanian number the client app owns at the carrier into Ringmaster (it must be routed to the engine's trunk). Needs the NUMBERS feature.

Endpoint: POST {base_url}/numbers

Access Level: 🔒 Protected · Bearer API key · feature NUMBERS

Request JSON Sample:

{ "e164": "+255677000099", "type": "REGULAR", "label": "Mauzo", "by": "admin@business.co.tz" }

Success Response: 201 Created, data = the number (status ALLOCATED).

Errors:

{ "success": false, "httpStatus": "403 FORBIDDEN", "message": "Adding and removing numbers is not enabled for this client app",
  "code": "FEATURE_OFF", "action_time": "2026-11-13T19:58:07.349143236", "data": null }

400 "Only Tanzanian numbers (+255 and 9 digits) can be added" · 409 NUMBER_ALREADY_YOURS · 409 NUMBER_TAKEN (another client app has it).

C3. Remove a number

Purpose: Give a free number back to the pool. Needs the NUMBERS feature.

Endpoint: DELETE {base_url}/numbers/{numberId}

Access Level: 🔒 Protected · Bearer API key · feature NUMBERS

Success Response: 200, message "Number removed", data null.

Errors: 409 NUMBER_ASSIGNED (release it first) · 409 NUMBER_BUSY (a call is in progress) · 409 NUMBER_IN_CALLOUT (a scheduled, running or paused call-out calls from it).

C4. Assign a number to an account

Endpoint: POST {base_url}/numbers/{numberId}/assign

Access Level: 🔒 Protected · Bearer API key

Request JSON Sample:

{ "accountId": "adb72fac-66a2-471b-a437-035fe008197d", "label": "Mapokezi" }

Success Response: the number with status: "ASSIGNED". Assigning again to the same account only changes the label.

Errors: 409 NUMBER_ASSIGNED "Number is assigned to another account; release it first" (use C6 instead).

C5. Release a number from its account

Purpose: Take the number off the account; it becomes free (ALLOCATED) and its flow is cleared.

Endpoint: POST {base_url}/numbers/{numberId}/release

Access Level: 🔒 Protected · Bearer API key

Success Response: the number with status: "ALLOCATED", accountId: null, incomingScriptVersionId: null.

Errors: 409 NUMBER_BUSY · 409 NUMBER_IN_CALLOUT.

C6. Transfer a number to another account

Purpose: Move an assigned number straight to another account of the same client app. The old account's flow is cleared, so pin the new account's flow next (C7).

Endpoint: POST {base_url}/numbers/{numberId}/transfer

Access Level: 🔒 Protected · Bearer API key

Request JSON Sample:

{ "accountId": "51f815ba-e9eb-4e29-9297-3c56033d32cd", "label": "Oda", "by": "admin@business.co.tz" }

Errors:

{ "success": false, "httpStatus": "409 CONFLICT", "message": "The number is already on this account",
  "code": "SAME_ACCOUNT", "action_time": "2026-11-13T19:58:07.424064672", "data": null }

409 NUMBER_NOT_ASSIGNED (assign it instead) · 409 ACCOUNT_NOT_ACTIVE · 409 NUMBER_BUSY · 409 NUMBER_IN_CALLOUT.

C7. Put a flow on a number

Purpose: Choose the flow version callers hear. Takes effect for the next call; calls in progress keep their version.

Endpoint: PUT {base_url}/numbers/{numberId}/script

Access Level: 🔒 Protected · Bearer API key

Request JSON Sample:

{ "scriptVersionId": "e183c7f1-3137-4848-95c1-11a7e8bef17a" }

Success Response: the number, message "Incoming script set".

Errors:

• 400 "Assign the number to an account first"
• 400 "Script version belongs to another account" · 400 "Numbers run Incoming scripts only"
• 404 NOT_FOUND "Script version not found"
• 409 VERSION_NOT_RUNNABLE "Only runnable versions can be put on a number" (approve it, Part 2B D7)

C8. Set where agents are rung

Endpoint: PUT {base_url}/numbers/{numberId}/ring-mode

Access Level: 🔒 Protected · Bearer API key

Request JSON Sample:

{ "ringMode": "BROWSER_AND_MOBILE" }

Success Response: the number, message "Ring mode set".

Errors: an unknown value → 400 "Request body is not valid JSON".