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)

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"

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"}
    ]
  }'

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": 0.82,
      "common_name": "Malaria",
      "icd10": "B50",
      "snomed_ct": "61462000",
      "rationale_one_line": "High fever with headache and mosquito exposure in Lagos is strongly suggestive of P. falciparum malaria."
    },
    {
      "name": "Typhoid Fever",
      "probability": 0.45,
      "common_name": "Typhoid",
      "icd10": "A01.0"
    }
  ],
  "triage": {
    "level": "urgent",
    "description": "Seek medical attention within 24 hours.",
    "recommended_action": "Visit nearest clinic for malaria RDT.",
    "timeframe": "within_24_hours",
    "recommended_specialist": { "id": "sp_internal_medicine", "name": "Internal Medicine" },
    "recommended_channel": "personal_visit"
  },
  "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": [{ "id": "yes", "label": "Yes" }, { "id": "no", "label": "No" }, { "id": "unknown", "label": "Not sure" }]
  },
  "red_flags_present": ["High fever (≥39°C) with severe headache"],
  "red_flags_watch_for": ["Confusion or altered consciousness", "Difficulty breathing"],
  "clinical_warnings": [],
  "recommended_investigations": [{ "priority": 1, "test_name": "Malaria RDT", "purpose": "Confirm P. falciparum infection", "urgency": "immediate" }],
  "metadata": { "confidence": 0.87, "total_latency_ms": 1850, "escalation_tier": 3, "phi_tokenized": true },
  "disclaimer": "This assessment is generated by PearMDx..."
}

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

Next Steps

Explore the full API Reference Authentication & Rate Limiting More Code Examples Try the Interactive Sandbox

Loading documentation…

Concepts & Glossary Authentication

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();

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 -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"}

]

{

"interview_id": "int_abc123",

"conditions": [

{

"name": "Malaria (Plasmodium falciparum)",

"probability": 0.82,

"common_name": "Malaria",

"icd10": "B50",

"snomed_ct": "61462000",

"rationale_one_line": "High fever with headache and mosquito exposure in Lagos is strongly suggestive of P. falciparum malaria."

{

"name": "Typhoid Fever",

"probability": 0.45,

"common_name": "Typhoid",

"icd10": "A01.0"

}

"triage": {

"level": "urgent",

"description": "Seek medical attention within 24 hours.",

"recommended_action": "Visit nearest clinic for malaria RDT.",

"timeframe": "within_24_hours",

"recommended_specialist": { "id": "sp_internal_medicine", "name": "Internal Medicine" },

"recommended_channel": "personal_visit"

"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": [{ "id": "yes", "label": "Yes" }, { "id": "no", "label": "No" }, { "id": "unknown", "label": "Not sure" }]

"red_flags_present": ["High fever (≥39°C) with severe headache"],

"red_flags_watch_for": ["Confusion or altered consciousness", "Difficulty breathing"],

"clinical_warnings": [],

"recommended_investigations": [{ "priority": 1, "test_name": "Malaria RDT", "purpose": "Confirm P. falciparum infection", "urgency": "immediate" }],

"metadata": { "confidence": 0.87, "total_latency_ms": 1850, "escalation_tier": 3, "phi_tokenized": true },

"disclaimer": "This assessment is generated by PearMDx..."

}

// 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