You are integrating Telepatia Synapse Public API.
Endpoint: POST /v1/appointments
Base URL: https://scribe-api.telepatia.ai
Auth: Authorization: Bearer ${SYNAPSE_API_KEY}
Request:
- consultationInternalId [body]: string (required, pattern=^[a-zA-Z0-9_-]{1,128}$, maxLength=128) — Your own consultation id. The booking join key: the consultation that fulfils this appointment carries the same id.
- name [body]: string (optional, minLength=1, maxLength=500) — Patient full name. Part of the inline identity. Provide the full inline identity (name + idCountry + idType + idValue), or reference an existing patient with patientId or internalCode: exactly one of the three is required.
- idCountry [body]: string (optional, enum: 250 values) — ISO 3166-1 alpha-2 country codes. Mirrors tanjiro's CountryCodes enum.
- idType [body]: string (optional, enum: 8 values) — Supported patient identification document types.
- idValue [body]: string (optional, minLength=1, maxLength=50) — Patient document number. Part of the inline identity (see `name`).
- patientId [body]: string (optional, pattern=^sp_[a-z0-9]{16}$) — Public id of an existing patient (sp_...). One of the three patient references (exactly one required): patientId, internalCode, or the inline identity.
- internalCode [body]: string (optional, minLength=1, maxLength=128) — Your own patient code, unique per institution. Looks up an existing patient; when none matches, the inline identity creates one. One of the three patient references (exactly one required).
- start [body]: string (required, maxLength=64) — ISO-8601 start. Required.
- end [body]: string (required, maxLength=64) — ISO-8601 end. Required.
- minutesDuration [body]: integer (optional, min=1.0) — Duration in minutes.
- serviceType [body]: string (optional, maxLength=256)
- appointmentType [body]: string (optional, maxLength=256)
- reason [body]: string (optional, maxLength=2000)
- description [body]: string (optional, maxLength=2000)
- medicalRecordConfigurationId [body]: string (optional, maxLength=128) — Public id of a medical record configuration (mrc_...). When present, the consultation context is seeded.
- scribeSessionModality [body]: string (optional, enum: IN_PERSON, TELEMEDICINE, DICTATION) — Supported scribe session modalities.
- notes [body]: string (optional, maxLength=10000)
- pastMedicalHistory [body]: string (optional, maxLength=10000)
Success 200:
- id: string
- consultationInternalId?: string
- status: string
- start?: string
- end?: string
- minutesDuration?: integer
- serviceType?: string
- appointmentType?: string
- reason?: string
- description?: string
- createdAt: string
Errors (envelope: { error: { type, code, message, param? } }):
- 400: parameter_missing, parameter_invalid, account_invalid
- 401: authentication_required
- 403: permission_denied, permission_denied_role
- 404: resource_not_found
- 409: resource_conflict
- 503: service_unavailable
Generate code in the language of the current file that:
1. Reads SYNAPSE_API_KEY from env (do not hardcode it).
2. Calls the endpoint with typed request and response.
3. Maps the error envelope to typed exceptions per status code.
4. Adds one happy-path test using the Bearer token.
