Loading documentation…
Loading documentation…
Key terminology and data structures used across the PearMedica API. Understanding these concepts will help you integrate faster and build more robust implementations.
EvidenceA piece of clinical information reported by or about the patient — a symptom, risk factor, or lab test result. Each evidence item includes an ID, a choice (present/absent/unknown), and optional metadata like severity or duration.
choice_idIndicates whether a symptom or risk factor is present, absent, or unknown. Valid values: "present" (patient reports this), "absent" (patient denies this), "unknown" (not yet asked or unsure).
sourceTracks how evidence was collected. Values: "initial" (patient volunteered), "suggest" (follow-up question), "predefined" (pre-screening), "red_flags" (emergency check). Used for audit trails.
Triage LevelUrgency classification for the assessment. Four levels: "emergency" (immediate care), "urgent" (within 24h), "routine" (scheduled appointment), "self-care" (home management). Derived from symptoms, red flags, and clinical rules.
Interview / Conversational FlowA multi-turn assessment where the API asks follow-up questions. Track state with the X-Interview-Id header. The API returns a "next_question" object until "should_stop" is true, indicating enough information has been gathered.
should_stopBoolean in the assessment response. When true, enough evidence has been collected and the assessment is considered complete. When false, additional questions should be presented to the patient.
ConditionA potential diagnosis returned by the assessment engine. Includes an ID (e.g., "c_malaria"), probability (high/medium/low), match_score (0–1), reasoning, severity, and recommended specialty.
Red FlagsEmergency symptoms that require immediate clinical attention. The API always checks for red flags using rules-based validation (not LLM), ensuring zero false negatives on critical conditions.
Risk FactorA non-symptom piece of evidence that influences assessment — e.g., recent travel, unprotected water source, pregnancy status. Documented with IDs prefixed "p_" (e.g., "p_recent_travel").
Nearest FacilitiesGoogle Maps–powered recommendations returned in the assessment metadata. Includes facility name, coordinates, distance, and type (hospital/clinic). Requires patient location to be provided.
API Key PrefixKeys starting with "sk_live_" are production keys (metered and billed). Keys starting with "sk_test_" are sandbox keys (return mock data, free). Never expose live keys in client-side code.
Rate LimitDefault: 100 requests per minute per API key, using a sliding window algorithm. Exceeding the limit returns 429 Too Many Requests. Check X-RateLimit-* headers for current status.
| Prefix | Entity | Example |
|---|---|---|
| s_ | Symptom | s_fever, s_headache |
| c_ | Condition | c_malaria, c_typhoid |
| p_ | Risk Factor | p_recent_travel, p_unprotected_water_source |
| lt_ | Lab Test | lt_malaria_rdt, lt_cbc |
| sk_live_ | Production API Key | sk_live_abc123... |
| sk_test_ | Test API Key | sk_test_xyz789... |