Users and patient identity
Map a patient in your system to one Doctronic user resource and preserve that scope on every request.
Your system authenticates the patient. Doctronic stores a user resource for that patient inside your organization. Keep the mapping between those two records in trusted backend storage.
Your patient record -> Doctronic user ID -> chats, care resources, and documentsThe Doctronic user ID selects a user resource, but it is not a credential. User-scoped requests
require both the API token and X-Doctronic-User-ID.
Create and store the mapping
Create a user with POST /users/. Save the
returned data.id on the matching patient record in your system.
{
"code": "success",
"message": "Request successful",
"data": {
"id": "mem_01K6JGGM2G2DB4Y9KB9H9MJJ6Q",
"createdAt": "2026-08-31T14:30:00Z",
"firstName": "Avery",
"lastName": "Chen",
"dateOfBirth": "1990-06-15",
"email": "avery@example.com",
"phoneNumber": "+15555550100",
"sex": "female"
}
}Do not create a new user each time the same patient starts a conversation. Resolve the existing mapping first. The current public API does not accept your own external patient identifier and does not provide a search or update operation, so your mapping is the source of truth.
Decide which fields to collect
All create-user fields are optional. Later workflows require specific demographics:
| Workflow | Fields required before the workflow |
|---|---|
| Clinical conversation | A valid Doctronic user ID |
| Appointment booking | firstName, lastName, dateOfBirth, and phoneNumber; booking also requires a saved address |
| Pharmacy selection | firstName, lastName, dateOfBirth, and sex |
When supplied, dateOfBirth must be an ISO 8601 date for a patient from 18 through 120 years old.
Phone numbers use E.164 format. See the
CreateUserRequest schema for field
limits and null behavior.
Scope every request on the backend
For user-scoped operations, resolve the current authenticated patient and add both headers from server-side code:
Authorization: Bearer YOUR_API_TOKEN
X-Doctronic-User-ID: mem_01K6JGGM2G2DB4Y9KB9H9MJJ6QNever trust a user ID supplied by browser code, a mobile client, or an automated caller without checking it against your stored patient mapping. Doctronic also verifies that the selected user belongs to the organization authenticated by the token.
Handle missing or stale mappings
- A
403 error.member.forbiddenresponse means the organization cannot act on that user. - A
404on a scoped resource can mean the resource is missing or outside the selected user scope. - If your mapping is missing, reconcile identity before creating another user.
- Keep staging and production mappings separate. IDs are not portable between environments.
The current public API does not expose user deletion or profile update operations. Coordinate data correction, retention, or deletion requirements with the Doctronic team.