{"$defs":{"Attachment":{"properties":{"data_base64":{"type":"string"},"doc_type":{"enum":["xray","photo","insurance","other","cbct"],"type":"string"},"filename":{"type":"string"},"media_type":{"description":"image/png, image/jpeg, application/pdf, application/zip (CBCT)","type":"string"}},"required":["filename","data_base64"],"type":"object"},"PatientConsent":{"properties":{"specialist_may_contact":{"description":"The patient agreed the receiving office may text/call them about this referral","type":"boolean"},"wants_earlier_opening":{"description":"The patient wants to be told about cancellations sooner than their appointment","type":"boolean"}},"type":"object"},"ProviderCard":{"properties":{"address":{"type":"string"},"city":{"type":"string"},"credential":{"type":"string"},"fax":{"type":"string"},"insurance":{"description":"Plans the office accepts (self-published)","items":{"type":"string"},"type":"array"},"kind":{"enum":["provider","practice"],"type":"string"},"name":{"type":"string"},"npi":{"pattern":"^[0-9]{10}$","type":"string"},"openings":{"description":"Near-term openings the office chose to share","items":{"type":"object"},"type":"array"},"phone":{"type":"string"},"practice_name":{"type":"string"},"receives_on_voicereferral":{"type":"boolean"},"specialty":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"}},"required":["npi"],"type":"object"},"Referral":{"anyOf":[{"required":["ask"]},{"required":["clinical_note"]},{"required":["letter"]}],"properties":{"ask":{"description":"What you are asking the specialist to do (evaluate #30 for endodontic treatment)","maxLength":600,"type":"string"},"attachments":{"items":{"$ref":"#/$defs/Attachment"},"maxItems":10,"type":"array"},"attestation":{"properties":{"name":{"description":"Who confirms the letter and attachments are approved by the sending provider and pertain to this patient","type":"string"}},"required":["name"],"type":"object"},"clinical_note":{"description":"Findings, history, what has been done. The letter is drafted from this in the sender's voice.","maxLength":20000,"type":"string"},"from_practice":{"description":"Optional practice name when the account has none on file","type":"string"},"letter":{"description":"Your own finished letter text; skips drafting","maxLength":20000,"type":"string"},"patient":{"properties":{"dob":{"description":"YYYY-MM-DD","type":"string"},"name":{"description":"Patient's full name","type":"string"},"phone":{"description":"Patient's cell. Only used when patient_consent.specialist_may_contact is true.","type":"string"}},"required":["name"],"type":"object"},"patient_consent":{"$ref":"#/$defs/PatientConsent"},"to":{"properties":{"npi":{"pattern":"^[0-9]{10}$","type":"string"}},"required":["npi"],"type":"object"},"tooth":{"type":"string"},"urgency":{"description":"routine | soon | urgent | emergency, or words","type":"string"}},"required":["to","patient","attestation"],"type":"object"},"ReferralRecord":{"properties":{"ask":{"type":"string"},"attachments":{"items":{"type":"object"},"type":"array"},"created_at":{"type":"string"},"from":{"$ref":"#/$defs/ProviderCard"},"id":{"type":"string"},"letter":{"type":"string"},"patient":{"properties":{"dob":{"description":"YYYY-MM-DD","type":"string"},"name":{"description":"Patient's full name","type":"string"},"phone":{"description":"Patient's cell. Only used when patient_consent.specialist_may_contact is true.","type":"string"}},"required":["name"],"type":"object"},"receiver_status":{"enum":["received","scheduled","completed","no_contact"],"type":"string"},"scheduled_date":{"type":"string"},"side":{"enum":["sent","incoming"],"type":"string"},"status":{"enum":["sent","held_for_doctor_approval"],"type":"string"},"to":{"$ref":"#/$defs/ProviderCard"},"tooth":{"type":"string"},"urls":{"properties":{"pdf":{"type":"string"},"record":{"type":"string"}},"type":"object"}},"type":"object"},"StatusUpdate":{"properties":{"scheduled_date":{"description":"YYYY-MM-DD when status is scheduled","type":"string"},"status":{"description":"received (default) | scheduled | completed | no_contact (the office could not reach the patient)","enum":["received","scheduled","completed","no_contact"],"type":"string"}},"required":["status"],"type":"object"}},"$id":"https://dentalelephant.com/api/agent/v1/referrals/schema.json","$schema":"https://json-schema.org/draft/2020-12/schema","description":"A vendor-neutral shape for a dentist-to-specialist (or doctor-to-doctor) referral, the provider card that identifies each end, the filed record, and the receiver's status update. Identity is the NPI on both ends. Anyone may implement it; Voice Referral (voicereferral.com) is the reference implementation.","endpoints":{"auth":"Authorization: Bearer vr_live_... (Voice Referral portal \u2192 Settings \u2192 API access); the directory needs no key","directory":"GET https://dentalelephant.com/api/agent/v1/providers?npi=|last=&first=&state=|specialty=&zip=&radius=","get":"GET https://dentalelephant.com/api/agent/v1/referrals/{id}","list":"GET https://dentalelephant.com/api/agent/v1/referrals?box=sent|incoming","mcp":"https://dentalelephant.com/mcp (tools: find_providers, send_referral, list_referrals, get_referral, update_referral_status)","pdf":"GET https://dentalelephant.com/api/agent/v1/referrals/{id}/pdf","send":"POST https://dentalelephant.com/api/agent/v1/referrals (Referral) -> ReferralRecord id + urls","status":"POST https://dentalelephant.com/api/agent/v1/referrals/{id}/status (StatusUpdate)"},"title":"Open Referral Schema for dentistry","version":"1.0.0"}