Trovacast

Platform

Scopes

Each API key carries a list of scopes, and each endpoint requires exactly one. Grant a key only what it needs.

Scopes are chosen when a key is created. A request outside a key's scopes is 403 API_KEY_SCOPE_MISSING, and the error's requiredScope names the scope it needed — add it by creating a new key with it.

Project key scopes

Contacts

  • contacts:readLook up contacts and their consent on each channel (phone numbers stay masked).
  • contacts:writeCreate and update contacts, and erase a contact for good.
  • contacts:exportExport everything held about one contact, phone number and email in full, for a data request.
  • consent:writeRecord a contact’s WhatsApp, email or SMS opt-in or opt-out, for marketing and updates.

Messaging

  • templates:readList message templates and their Meta review status.
  • templates:writeSubmit templates to Meta, sync them and delete them.
  • messages:readRead sent and received messages, their text and statuses.
  • messages:writeSend WhatsApp templates and replies, and mark messages read.
  • broadcasts:readList broadcasts and follow their progress: how many were sent, delivered, read or skipped.
  • broadcasts:writeSend an approved WhatsApp template to many contacts at once, and pause, resume or cancel it.
  • conversations:readList conversations and when each one’s 24-hour reply window closes.
  • conversations:writeAssign a conversation to a team member, resolve it or reopen it.

WhatsApp account

  • whatsapp:readSee whether WhatsApp is connected, its number, quality and limits.
  • whatsapp:manageStart the hosted WhatsApp connection and disconnect the account.

Email

  • email:readSee sending domains with their DNS records, and the suppression list (addresses masked).
  • email:manageClaim, re-check and release sending domains; add and remove suppressions.

SMS

  • sms:readList the SMS senders (DLT headers, sender IDs and numbers) SMS can go out from, with their status and the categories each fits, and which SMS registration regime applies to the organization's country.
  • sms:manageRegister and remove SMS headers and sender IDs; each waits for the platform to activate it. Live keys only.
  • dlt:readList India's DLT principal entities and the SMS and 140/160-series headers registered under them, with the platform's review status.
  • dlt:writeSubmit, correct and withdraw DLT entities and headers for the platform to verify. Live keys only.

Webhooks

  • webhooks:manageRegister, test and remove webhook endpoints, resend deliveries, and read back the events they carried — each event also needs the scope that reads it (messages, contacts, templates, WhatsApp account or calls).

Calls

  • calls:readList and read calls and their outcomes, and the channels a call can use.
  • calls:writePlace calls whose conversation your own server runs over a live audio stream, and end them.
  • recordings:readGet short-lived download links to call recordings (each one audited), and receive the recording-ready webhook (with Read calls).
  • recordings:writePermanently erase a call's recordings (the audio itself, each erasure audited).
  • transcripts:readRead what was said on a call (its transcript, phone numbers masked) and the AI's summary of it, and receive the transcript- and summary-ready webhooks (with Read calls).

Numbers

  • numbers:readList the project's phone numbers and search the numbers on offer, with their prices.
  • numbers:writeOrder numbers (setup fee and first month from the wallet), set their inbound route and label, and release them.
  • lookup:readCheck whether a number is valid, its formats, country and type, and whether an Indian number is on the do-not-call registry — free, and nothing is stored.

Voice

  • applications:readList the answer URLs that inbound calls ask for instructions — never a signing secret.
  • applications:writeCreate, change and delete voice applications, and rotate their signing secret.
  • call-flows:readList call flows (IVRs) and read their versions.
  • call-flows:writeCreate call flows, draft and publish versions, and archive flows.
  • queues:readList the project's call queues with their settings and members (seat ids, tiers and skills — never names).
  • queues:writeCreate, change and delete call queues and replace their members, under the console's rules (live keys only; each change audited against the key).
  • voice:clientMint short-lived tokens that let your own app answer calls as one identity — and, with Place calls, place them (live keys only).

AI agents

  • agents:readList the project's AI agents and the models they can use — never a provider secret.
  • agents:writeCreate, change and archive AI agents.

Billing

  • billing:readRead the wallet balance, usage by day, channel and destination, and the plan's prices.
  • billing:manageSet the low-balance threshold balance.low fires at, and start top-ups — a checkout link a person pays; the key never credits the wallet itself.

Accounts

  • verifications:readRead the KYC status and the documents still required (identifiers as their last four characters), and what a business of any country must give.
  • verifications:writeSave the business details, upload the documents and submit the verification for review (test keys too: it is the organization's real KYC); a test key also decides a test organization's verification in the sandbox.
  • api-keys:rotateLet this key replace its own secret (POST /v1/me/rotate) — never another key's.

Settings

  • settings:readSee whether the project allows AI calls and records every call, and its own staff phones (masked).
  • settings:writeTurn AI calls on or off for the whole project, and register or remove its own staff phones (each change audited against the key).

Verify

  • verify:readSee a one-time-code verification's status, channel and attempts (the destination masked, never a code).
  • verify:writeStart verifications, check codes and resend them — each send billed from the wallet.

Subaccounts

  • subaccounts:readList the project's subaccounts with their status, verification, balance and usage — counts and money, never their data.
  • subaccounts:writeCreate subaccounts, suspend them, move credit to and from them, and mint their keys (live keys only).

Teams

  • teams:readList the project's teams — the ids call queues take — with whether each is active and its member count.
  • members:readList the project's seats with their names, roles, teams and desk presence — email addresses masked, never in full.
  • contacts:export is not implied by contacts:read: it returns a contact's phone number and email in full, for data requests.
  • broadcasts:write is not implied by messages:write, and email:manage is not implied by email:read.
  • recordings:write is not implied by recordings:read or calls:write; calls:read never returns a recording link.
  • Looking a contact up by phone number while placing a call or sending a message (to.phone) also needs contacts:write, since it may create the contact.

Integration key scopes

Integration keys administer the projects a platform partner provisioned. They never read a project's data, with one exception — organizations:data-subjects, which answers a data subject's request. See Integration keys.

Projects

  • organizations:readRead the identity and status of the projects it provisioned — never their data.
  • organizations:writeCreate projects, change their name, product lines and plan within the integration's terms, and suspend or reactivate the ones it provisioned.
  • organizations:erasePermanently erase a project it provisioned, with everything in it.
  • organizations:data-subjectsFind a person's contacts by phone number, export or erase them, in a project it provisioned — suspended ones included.

Keys

  • api-keys:writeCreate and revoke API keys inside the projects it provisioned.

Projects

  • organizations:actAct for a project it provisioned (Trovacast-Organization), with the scopes the platform delegated to the integration — none unless it did.
  • organizations:eventsRegister the integration's own webhook endpoints, which receive the events of every project it provisioned, and read those events back — only the types the platform delegated it the scopes to read.