Quickstart Guide
Integrate PearMedica in under 5 minutes. No SDK required — pure REST.
Prerequisites
- A PearMedica account (sign up at /auth/sign-up)
- An API key from your Dashboard → API Keys
- Any HTTP client (fetch, axios, requests, cURL)
1
Get Your API Key
After signing up, navigate to Dashboard → API Keys and create a new key. Your key will look like sk_live_abc123.... Store it securely — it won't be shown again.
bash
# Set this in your .env or shell profile
export PEARMEDICA_API_KEY="sk_live_your_api_key_here"2
Make Your First Assessment
Send a POST request to /v1/assess with patient demographics and symptom evidence.
JavaScript / TypeScript
javascript
const response = await fetch('https://api.pearmedica.com/v1/assess', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.PEARMEDICA_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
patient: {
age: 28,
sex: 'female',
location: 'lagos_nigeria',
},
evidence: [
{ id: 's_fever', choice_id: 'present', duration_days: 3 },
{ id: 's_headache', choice_id: 'present', severity: 'severe' },
{ id: 's_chills', choice_id: 'present' },
],
}),
});
const data = await response.json();Python
python
import requests
import os
response = requests.post(
'https://api.pearmedica.com/v1/assess',
headers={
'Authorization': f'Bearer {os.environ["PEARMEDICA_API_KEY"]}',
'Content-Type': 'application/json',
},
json={
'patient': {'age': 28, 'sex': 'female', 'location': 'lagos_nigeria'},
'evidence': [
{'id': 's_fever', 'choice_id': 'present', 'duration_days': 3},
{'id': 's_headache', 'choice_id': 'present', 'severity': 'severe'},
{'id': 's_chills', 'choice_id': 'present'},
],
},
)
data = response.json()cURL
bash
curl -X POST https://api.pearmedica.com/v1/assess \\
-H "Authorization: Bearer $PEARMEDICA_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{
"patient": {"age": 28, "sex": "female", "location": "lagos_nigeria"},
"evidence": [
{"id": "s_fever", "choice_id": "present", "duration_days": 3},
{"id": "s_headache", "choice_id": "present", "severity": "severe"},
{"id": "s_chills", "choice_id": "present"}
]
}'3
Parse the Response
The response includes differential conditions, triage level, and optionally a follow-up question for conversational flow.
json
{
"interview_id": "int_abc123",
"conditions": [
{
"name": "Malaria (Plasmodium falciparum)",
"probability": "high",
"common_name": "Malaria",
"icd_10": "B50"
},
{
"name": "Typhoid Fever",
"probability": "medium",
"common_name": "Typhoid",
"icd_10": "A01.0"
}
],
"triage": {
"level": "urgent",
"description": "Seek medical attention within 24 hours.",
"recommended_action": "Visit nearest clinic for malaria RDT.",
"timeframe": "within_24_hours"
},
"should_stop": false,
"next_question": {
"id": "q_travel_history",
"text": "Have you travelled to a rural area recently?",
"explanation": "Travel history helps narrow endemic disease exposure.",
"options": ["yes", "no", "unknown"]
},
"red_flags": [],
"disclaimer": "This assessment is generated by PearMDx..."
}4
Handle Conversational Flow
If should_stop is false and a next_question is present, show the question to the user, collect their answer, and send a new request with the updated evidence. Continue until should_stop is true.
typescript
// Conversational loop
let shouldStop = false;
let evidence = initialEvidence;
let interviewId: string | undefined;
while (!shouldStop) {
const res = await assess({ patient, evidence, interview_id: interviewId });
interviewId = res.interview_id;
shouldStop = res.should_stop;
if (!shouldStop && res.next_question) {
const answer = await askUser(res.next_question);
evidence.push({ id: answer.id, choice_id: answer.value });
}
}
// Final assessment is ready — display conditions and triage