Create a consultation
POST/telehealth/consultations
Creates a questionnaire consultation for one of the provider's patients. The submission passes the create gates in order — questionnaire exists, the pinned version is current, the questionnaire is applicable to the patient, the answers are structurally valid and not disqualifying, the patient meets the provider's minimum age, the requested medications fit the provider's per-consultation item cap and the patient's monthly quantity cap, and, when required by the provider's current policy, the patient's identity is satisfied. Identity is required by default and derived from the patient (patientReferenceId): it passes when the patient has an uploaded ID document on file (mint one via the identity-documents upload-url endpoint) or was doctor-verified on a prior consultation (carried forward). The policy is snapshotted when the consultation is created. On success the consultation is queued pending for a doctor. The provider is resolved from the API key; a organizationId in the body is never trusted.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 409
- 422
- 500
Successful response
The request input failed validation. payload.issues lists the offending paths when the failure is schema-level; otherwise payload.message carries the reason.
Missing or invalid API key.
The provider exists but is not active.
The addressed resource does not exist.
The pinned questionnaireVersion is no longer the approved version. Re-fetch the questionnaire and re-render.
QuestionnaireNotApplicable: This questionnaire cannot be submitted for this patient yet (e.g. a follow-up before any completed consultation).
DisqualifyingAnswer: An answer disqualifies the patient from the requested treatment type; the consultation is rejected without a doctor.
PatientUnderMinimumAge: The patient is younger than the provider's minimum age for treatment.
PrescriptionItemLimitExceeded: The prescription carries more medication items than the provider allows per consultation.
MonthlyPrescribedQuantityLimitExceeded: Issuing would push the patient past the provider's monthly prescribed-quantity cap. payload carries the cap, what is already prescribed this month, and the requested amount.
IdentityRequired: No ID document was supplied and the patient has no prior doctor-verified identity.
An unexpected error occurred. payload.id is a correlation id for support.