Concepts & Glossary
Key terminology and data structures used across the PearMedica API. Understanding these concepts will help you integrate faster and build more robust implementations.
Core Terminology
Evidence
A 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_id
Indicates 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).
source
Tracks how evidence was collected. Values: "initial" (patient volunteered), "suggest" (follow-up question), "predefined" (pre-screening), "red_flags" (emergency check). Used for audit trails.
Triage Level
Urgency 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 Flow
A 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_stop
Boolean 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.
Condition
A 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 Flags
Emergency 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 Factor
A 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 Facilities
Google 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 Prefix
Keys 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 Limit
Default: 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.
ID Prefix Conventions
| 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... |