Choosing a Reviewer
Any eligible physician can answer. Specialty and specific physician selection are not yet available.
expert_ids or specialties are rejected with 400 in both production and sandbox. Omit reviewer or leave both lists empty. The specialty vocabulary endpoint also returns an empty list. The shapes and matching rules below describe planned functionality.Planned reviewer selector
"reviewer": {
"expert_ids": [],
"specialties": ["cardiology", "internal_medicine"],
"turnaround": "24h"
}| Field | Description |
|---|---|
expert_ids | Specific physicians, by public expert ID (exp_…). |
specialties | Specialty IDs from the vocabulary below. general means any physician. |
turnaround | Only "24h" today. |
All fields are optional. Matching rules:
- Within a field, values are OR'd.
"specialties": ["cardiology", "internal_medicine"]means a cardiologist or an internist. - Across fields, they are AND'd.
expert_idscombined withspecialtiesmeans one of those physicians, and only if they also practice one of those specialties. - Empty means no constraint. Omitting
reviewerentirely means any eligible physician. generalmatches everyone. Includinggeneralinspecialtiesremoves the specialty constraint, even alongside other specialties.expert_idspins people. Combined with other fields it narrows them: the pinned physician must also match the specialty constraint.- Up to 50 values per field. Unknown specialties, unknown fields, or malformed expert IDs are a 400.
The selector is saved with the decision. You can override it once, when you call /escalate; after escalation it can't change.
Eligibility today
routing.has_eligible_experts reports whether any enabled physician is accepting decisions. A production preview can return false; escalation then returns 422 no_matching_expert. Retry later. Sandbox always reports true and uses a simulated physician, regardless of the live roster.
routing.suggested.specialties and routing.suggested.expert_idsare reserved and return empty lists. Nonempty reviewer selections are rejected in both production and sandbox.
Planned specialty vocabulary
GET /api/v1/decisions/specialties returns the controlled vocabulary. It is public (no key) and cacheable for an hour.
curl https://api.appendix.com/api/v1/decisions/specialties
{
"object": "list",
"data": [
{ "id": "general", "label": "Any physician" },
{ "id": "allergy_immunology", "label": "Allergy and immunology" },
{ "id": "cardiology", "label": "Cardiology" },
…
]
}| id | Label |
|---|---|
general | Any physician |
allergy_immunology | Allergy and immunology |
anesthesiology | Anesthesiology |
cardiology | Cardiology |
dermatology | Dermatology |
emergency_medicine | Emergency medicine |
endocrinology | Endocrinology |
family_medicine | Family medicine |
gastroenterology | Gastroenterology |
general_surgery | General surgery |
hematology_oncology | Hematology and oncology |
infectious_disease | Infectious disease |
internal_medicine | Internal medicine |
nephrology | Nephrology |
neurology | Neurology |
obstetrics_gynecology | Obstetrics and gynecology |
ophthalmology | Ophthalmology |
orthopaedic_surgery | Orthopaedic surgery |
otolaryngology | Otolaryngology |
pathology | Pathology |
pediatrics | Pediatrics |
physical_medicine_rehabilitation | Physical medicine and rehabilitation |
preventive_medicine | Preventive medicine |
psychiatry | Psychiatry |
pulmonology_critical_care | Pulmonology and critical care |
radiology | Radiology |
rheumatology | Rheumatology |
urology | Urology |
Planned expert directory
GET /api/v1/experts lists the physician profiles you can pin with expert_ids. It requires an API key. Filter with ?specialty=. GET /api/v1/experts/{id} returns one profile.
The example below shows the future profile shape. Today the list returns {"object":"list","data":[]}.
curl "https://api.appendix.com/api/v1/experts?specialty=cardiology" \
-H "Authorization: Bearer $APPENDIX_API_KEY"
{
"object": "list",
"data": [
{
"id": "exp_…",
"object": "expert",
"name": "…, MD",
"credentials": "MD",
"specialties": ["cardiology"],
"board_certifications": ["…"],
"bio": "…",
"photo_url": "https://…" ,
"accepting_decisions": true,
"turnaround": "24h"
}
]
}- The directory includes physicians who are temporarily not accepting decisions; check
accepting_decisions. Only accepting physicians count toward eligibility. photo_urlis a short-lived signed link, ornull. Don't store it.- Physicians are added and change availability over time. Look up the directory when you need it rather than caching it for long.
- In the sandbox, the selector is validated (unknown specialties and malformed expert IDs are still a 400), but the simulated physician answers requests without reviewer constraints. Specialty and specific physician selection are unavailable in the sandbox too. Sandbox decisions always report
has_eligible_experts: true, so they don't tell you whether a specialty is available in production.