Platform
Integration keys
For platforms that provision a Trovacast organization per customer: create and look up organizations, mint their API keys, suspend, reactivate and erase them.
An integration — the Trovacast Shopify app is one — provisions an organization for each of its customers and administers it with an integration key, without ever browsing the organization’s data. The one exception is a data subject’s own request (see Data requests). Integration keys are issued by Trovacast: talk to us to become an integration partner.
Every route that names an organization answers 404 for one the integration did not provision, exactly as for one that does not exist. A project key on these routes is 403 API_KEY_KIND_MISMATCH.
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.
- POST
/v1/organizationsProvisions an organization for a customer (idempotent on externalReference) - GET
/v1/organizationsFinds the organization you provisioned for an externalReference (zero or one) - GET
/v1/organizations/{organizationId}An organization’s lifecycle, product lines and WhatsApp connection status - PATCH
/v1/organizations/{organizationId}Renames an organization, switches its product lines or moves its plan, within your terms - POST
/v1/organizations/{organizationId}/suspendSuspends an organization (its keys and sign-ins stop working); idempotent - POST
/v1/organizations/{organizationId}/reactivateLifts this integration’s suspension; idempotent - POST
/v1/organizations/{organizationId}/api-keysMints an organization API key; the secret is returned once - DELETE
/v1/organizations/{organizationId}/api-keys/{keyId}Revokes an organization API key this integration minted (immediate, idempotent) - DELETE
/v1/organizations/{organizationId}Erases an organization the integration provisioned
Provision an organization
POST /v1/organizations is idempotent on externalReference — your id for the customer, one organization per value: 201 when it is created, 200 with the existing one otherwise, whatever else the body says.
curl -X POST 'https://api.trovacast.com/v1/organizations' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: provision-acme' \
-H 'Content-Type: application/json' \
-d '{
"name": "Acme Store",
"externalReference": "acme.myshopify.com",
"ownerEmail": "owner@acme.example",
"timezone": "Asia/Kolkata",
"locale": "en-IN"
}'- A new organization has the product lines you ask for (
entitlements, messaging only by default), on the plan you ask for (planId, your default plan by default), incountry(the deployment’s home country by default), withownerEmailseated as an invited administrator. No email is sent until they claim the seat. - Lines and plans stay within your integration’s terms, which Trovacast sets: the ceilings and plan list of the partner it binds your integration to (your organizations are that partner’s clients), or messaging on your default plan. Outside them:
409 PRODUCT_LINE_NOT_OFFERED(line) or409 PLAN_NOT_OFFERED(planId). PATCH /v1/organizations/{organizationId}renames an organization, switches its product lines and moves its plan, within the same terms — everything asked is checked before anything changes.- While an erasure of that reference’s organization is in flight, the answer is
409 ORGANIZATION_ERASING. Retry once it finishes and the reference provisions afresh — a reinstall right after an erasure lands here.
Look one up
GET /v1/organizations?externalReference= finds the organization you provisioned for a reference (an exact match): data holds it, or is empty. Another integration’s organization with the same reference is never returned. It is a lookup, not a listing — externalReference is required.
curl 'https://api.trovacast.com/v1/organizations?externalReference=acme.myshopify.com' \
-H "Authorization: Bearer $TROVACAST_API_KEY"{
"object": "organization",
"id": "ORGANIZATION_ID",
"name": "Acme Store",
"slug": "acme-store",
"status": "active",
"suspendedBy": null,
"suspendedAt": null,
"externalReference": "acme.myshopify.com",
"entitlements": {
"calling": false,
"messaging": true
},
"planId": "PLAN_ID",
"country": "IN",
"livemode": true,
"whatsapp": {
"status": "connected"
},
"erasure": null,
"createdAt": "2026-11-05T10:00:00.000Z"
}Act for an organization
A key holding organizations:act acts for one of your organizations by naming it in a Trovacast-Organization header on any project route: the request is then that organization’s, with the scopes Trovacast delegated to your integration (none unless it did). Another integration’s organization is 404, a suspended one 409 ORGANIZATION_NOT_ACTIVE, an undelegated scope 403 API_KEY_SCOPE_MISSING. Every write is audited in the organization naming your integration and key; idempotency keys, rate limits and the request log are the organization’s. A live key waits for the organization’s business verification where it must pass one — except on the verification itself. See Acting for an organization.
One webhook feed for all of them
A key holding organizations:events registers your integration’s own webhook endpoints (/v1/integration/webhook-endpoints): each receives the events of every organization you provisioned, signed and retried like any endpoint, each envelope naming the organization (organizationId) and your externalReference for it. It carries the event types whose reading scopes Trovacast delegated to your integration, and takes the key’s mode. GET /v1/integration/events reads them back across your organizations. See One feed for an integration.
Pay for them
billing: { payer: "integration" } on POST or PATCH /v1/organizations bills an organization’s calls, messages, plan fees and numbers to your integration’s billing organization — your own account, which Trovacast names for you (409 BILLING_PAYER_NOT_CONFIGURED until then) — so the organization never sees a bill. Each charge in your ledger names the organization; refunds go back to the wallet that was charged. An optional spendCap: { amountMinor, period: "month" } refuses what would pass it (402 BILLING_SPEND_CAP_REACHED). Read one organization’s usage with GET /v1/organizations/{organizationId}/usage, and your account’s spend by organization with GET /v1/usage?breakdown=organization and its statements’ paidFor.
Test mode
Your test key (tc_test_…) provisions test organizations (livemode: false): only test keys reach them, nothing they do is billed and they never go live. Acting for an organization, a test key reaches its test partition and the sandboxes — so you can run your whole flow in test mode: provision, act, erase.
An organization read carries its identity, lifecycle, product lines and the WhatsApp connection’s status — nothing else.
Mint a key for it
POST /v1/organizations/{organizationId}/api-keys mints a project key for the organization — project scopes only — and returns its secret once. With an Idempotency-Key, a retry within 24 hours returns the same key instead of minting another. The key is listed on the organization’s Developers page, labelled with your integration, and its administrators can revoke it.
curl -X POST 'https://api.trovacast.com/v1/organizations/ORGANIZATION_ID/api-keys' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: acme-app-key' \
-H 'Content-Type: application/json' \
-d '{
"name": "Shopify app",
"scopes": [
"contacts:read",
"contacts:write",
"consent:write",
"messages:write",
"messages:read"
]
}'DELETE /v1/organizations/{organizationId}/api-keys/{keyId} revokes a key your integration minted, at once; any other key id is 404.
Suspend and reactivate
POST …/suspend with a reason (3–500 characters, audited) stops the organization’s keys and sign-ins at once. POST …/reactivate lifts your suspension. Both are idempotent. suspendedBy says who holds a suspension — integration (you), platform or partner — and a hold that is not yours is 409 ORGANIZATION_SUSPENDED_BY_PLATFORM; a closed organization is 409 ORGANIZATION_CLOSED.
curl -X POST 'https://api.trovacast.com/v1/organizations/ORGANIZATION_ID/suspend' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: suspend-acme-uninstall' \
-H 'Content-Type: application/json' \
-d '{
"reason": "App uninstalled"
}'Erase it
DELETE /v1/organizations/{organizationId} erases the organization and everything in it. See Erase an organization.
Errors
| Code | Status | Meaning and what to do |
|---|---|---|
API_KEY_KIND_MISMATCH | 403 | A project key on an integration endpoint, or an integration key on a project endpoint.What to do: Call /v1/organizations with an integration key and every other endpoint with a project key. See Integration keys. |
ORGANIZATION_CLOSED | 409 | The organization is closed: it can be neither suspended, reactivated nor changed (PATCH /v1/organizations/{organizationId}), and a closed subaccount takes no transfer.What to do: Do not retry: closing is final. |
ORGANIZATION_ERASING | 409 | POST /v1/organizations named an externalReference whose organization is being erased.What to do: Retry once the erasure finishes: the reference then provisions a new organization. |
ORGANIZATION_SUSPENDED_BY_PLATFORM | 409 | Trovacast or a partner holds the organization's suspension; an integration can lift only its own.What to do: Do not retry: ask whoever holds it — suspendedBy on GET /v1/organizations/{organizationId} says — to lift it; contact us when it is the platform. |