Skip to main content
Account management is only available with an institutional API key. Doctor-level API keys do not have access to these endpoints.
Institutional API keys can create and retrieve doctor accounts within their organization. Each account represents a clinician who can use the Telepatia scribe through your integration. Creating an account mints two keys for that account — a secret key (sk_…) for server-side API calls and a publishable key (pk_…) for the browser embed (see Key types). You can later rotate the secret key.

​
Creating an account

POST /v1/institutional/accounts requires email and doctorSpecialties. Optionally pass apiKeyConfig.validForDays (1–365) to control how long the minted API key stays valid — omit it to default to 365 days (1 year).
Response:
apiKey (secret) and publishableApiKey (publishable) are returned only once — store them securely. expiresAt is the UTC timestamp when the keys stop working, and apiKeyExpiresInDays echoes the lifetime that was applied. Use the secret key for server-side API calls; the publishable key is for the browser embed and cannot call the API directly.
Save the id (or your internalCode) — you can use either to retrieve the account later.

​
Creating accounts in bulk

POST /v1/institutional/accounts/batch creates several doctor accounts in one call. Send an accounts array. Each item takes the same fields as a single create. The batch holds at most 10 accounts. The endpoint rejects the whole request with 400 before it creates any account when the batch repeats an email or an internalCode.
The endpoint creates each account on its own. One account can succeed while another fails. The endpoint does not roll back. It returns 200 with a results array. Each entry reports the outcome for one account, in the order you sent them. Response:
Each created account returns its apiKey and publishableApiKey only once. Store the keys for every created entry before you read the next response.
Read createdCount and failedCount for a quick total. Use status on each entry to find the accounts that failed.

​
Retrieving an account

Look up an account by its id (acc_*) or by your own internalCode.
Response:

​
Regenerating an API key

Rotate an account’s API key with POST /v1/institutional/accounts/{account_id}/api-keys/regenerate, identifying the account by its id (acc_*) or internalCode. Optionally pass validForDays (1–365) to set the new key’s lifetime; omit it to keep the account’s default.
Response:
Regenerating revokes the previous key (after a short grace window) and returns the new raw apiKey once — update your integration before the grace window closes. Regeneration is limited to one per account every 2 minutes; exceeding it returns 429 rate_limit_exceeded. See Error Handling.