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.

Assigning a branch

To put the doctor in a branch, send one of these fields when you create the account:
If you send both fields, they must identify the same branch. If they identify different branches, the request fails with 400 parameter_invalid and param is institutionalBranchId. An institutionalBranchId that is not the id of a branch of your institution fails in the same way. Get the ids and names with GET /v1/institutional/branches. This endpoint requires an institutional API key; a doctor API key gets 403 permission_denied.
Response:
Each item has only the branch id and name. The list includes hidden branches. The list is paginated with page and limit (1–100); total is the number of branches you can reference (a legacy branch without a name is not counted). The id does not change when the branch is renamed, and it is the id that POST /v1/institutional/branches returns. Use a branch id as institutionalBranchId when you create an account or when you set the consultation context. A legacy branch that was created before branch ids existed has id: null. Refer to that branch by its name. To add a branch, use POST /v1/institutional/branches.

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. If an item has an institutionalBranchId that does not identify a branch of your institution, only that item fails; the other items continue. 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:

Updating an account

Change an account with PATCH /v1/institutional/accounts/{account_id}, identifying the account by its id (acc_*) or internalCode. Send only the fields to change:
  • nameFull: the doctor’s full name.
  • doctorSpecialties: the new list of specialties. It replaces the stored list.
  • internalCode: your institution’s code for the account.
Any other field, such as email, is rejected with 400. The endpoint requires an institutional API key with write access. Use it to add your internalCode to accounts that do not have one, for example doctors who joined through an invitation before your integration. Find the account id with GET /v1/institutional/accounts, then set the code:
Response: the updated account, in the same shape as Retrieving an account.
An internalCode is set once. Telepatia uses it to find the doctor in your systems, so it cannot be changed or removed through the API. Sending the stored value again changes nothing. A different value returns 409 resource_conflict with param: "internalCode"; contact Telepatia support to change a stored code. A code that another account or a pending invitation of your institution already uses also returns 409. A pending invitation does not appear in GET /v1/institutional/accounts until the doctor accepts it.

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. The publishable key is rotated too: the previous pk_ key is revoked the same way and the new one is returned once as publishableApiKey. Regeneration is limited to one per account every 2 minutes; exceeding it returns 429 rate_limit_exceeded. See Error Handling.