Skip to main content

Choosing a Reviewer

Any eligible physician can answer. Specialty and specific physician selection are not yet available.

Reviewer selection is not yet generally available. This page documents the API shape, but the public physician directory is currently empty. Individual profile lookups return 404, and requests with nonempty 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"
}
FieldDescription
expert_idsSpecific physicians, by public expert ID (exp_…).
specialtiesSpecialty IDs from the vocabulary below. general means any physician.
turnaroundOnly "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_ids combined with specialties means one of those physicians, and only if they also practice one of those specialties.
  • Empty means no constraint. Omitting reviewer entirely means any eligible physician.
  • general matches everyone. Including general in specialties removes the specialty constraint, even alongside other specialties.
  • expert_ids pins 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" },
    …
  ]
}
Specialty selection is not yet available. Specialty selection is not implemented yet. The vocabulary below describes the planned API shape, not currently available routing. If your use case needs a particular specialty, discuss your use case and expected volume with us at hello@appendix.com, and we can commission physicians in that specialty.
idLabel
generalAny physician
allergy_immunologyAllergy and immunology
anesthesiologyAnesthesiology
cardiologyCardiology
dermatologyDermatology
emergency_medicineEmergency medicine
endocrinologyEndocrinology
family_medicineFamily medicine
gastroenterologyGastroenterology
general_surgeryGeneral surgery
hematology_oncologyHematology and oncology
infectious_diseaseInfectious disease
internal_medicineInternal medicine
nephrologyNephrology
neurologyNeurology
obstetrics_gynecologyObstetrics and gynecology
ophthalmologyOphthalmology
orthopaedic_surgeryOrthopaedic surgery
otolaryngologyOtolaryngology
pathologyPathology
pediatricsPediatrics
physical_medicine_rehabilitationPhysical medicine and rehabilitation
preventive_medicinePreventive medicine
psychiatryPsychiatry
pulmonology_critical_carePulmonology and critical care
radiologyRadiology
rheumatologyRheumatology
urologyUrology
New values will appear. Specialties may be added at any time. Treat values you don't recognize as valid, and read the endpoint rather than hardcoding this list.

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_url is a short-lived signed link, or null. 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.