Account management is only available with an institutional API key. Doctor-level API keys do not have access to these endpoints.
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).
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: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.
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.
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:
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 itsid (acc_*) or by your own internalCode.
Updating an account
Change an account withPATCH /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.
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:
Regenerating an API key
Rotate an account’s API key withPOST /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.