Quickstart
Get up and running with the MediLoop API in just a few minutes. This guide walks you through authentication, making your first API call, and common integration patterns.
Prerequisites
- A MediLoop developer account (Sign up here)
- An API key (
sk_test_…orsk_live_…) from the Developer Portal - Basic familiarity with REST APIs
Step 1: Get an Access Token
Exchange your API key for a short-lived access token, then send it as a Bearer token on every call. See Authentication for details.
Get a token
bash
curl -X POST https://sandbox.api.mediloop.co/api/v1/auth/token \
-H "Content-Type: application/json" \
-d '{
"api_key": "sk_test_YOUR_API_KEY"
}'RESPONSE200
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
"token_type": "Bearer",
"expires_in": 3600,
"environment": "sandbox"
}Save the token (e.g. export ACCESS_TOKEN=...) and reuse it until it expires.
Step 2: Make Your First Request
Let's verify your token works by listing patients:
Request
bash
curl https://sandbox.api.mediloop.co/api/v1/uhid/ \
-H "Authorization: Bearer $ACCESS_TOKEN"RESPONSE200
{
"results": [],
"count": 0,
"page": 1,
"page_size": 20,
"source": "fhir"
}Step 3: Register a Patient
Create your first patient record. In sandbox mode, use test data:
Request
bash
curl -X POST https://sandbox.api.mediloop.co/api/v1/uhid/register/ \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"first_name": "Test",
"last_name": "Patient",
"date_of_birth": "1990-01-15",
"gender": "M",
"phone_number": "+256700000001",
"district": "Kampala"
}'RESPONSE201
{
"uhid": "UG987654321B",
"first_name": "Test",
"last_name": "Patient",
"date_of_birth": "1990-01-15",
"gender": "M",
"phone_number": "+256700000001",
"district": "Kampala",
"fhir_patient_id": "fhir-test-123",
"is_active": true,
"created_at": "2024-01-15T10:00:00Z"
}Step 4: Book an Appointment
Now let's book an appointment for the patient:
Request
bash
curl -X POST https://sandbox.api.mediloop.co/api/v1/appointments/ \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"patient_uhid": "UG987654321B",
"practitioner_id": "prov-test-001",
"service_type_code": "consultation",
"start_time": "2024-01-20T10:00:00Z",
"duration_minutes": 30,
"reason_text": "General checkup"
}'RESPONSE201
{
"id": "apt-123-456",
"appointment_number": "APT-2024-0001",
"patient_uhid": "UG987654321B",
"status": "booked",
"start_time": "2024-01-20T10:00:00Z",
"end_time": "2024-01-20T10:30:00Z",
"created_at": "2024-01-15T10:05:00Z"
}Step 5: Schedule an Appointment Reminder
Schedule a reminder for the patient. The reminder engine owns scheduling and delivery (in-app call, WhatsApp, SMS or push); set use_ai to have the wording generated for the patient.
Request
bash
curl -X POST https://sandbox.api.mediloop.co/api/v1/calls/reminders/ \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"patient_uhid": "UG987654321B",
"kind": "appointment",
"channel": "whatsapp_message",
"scheduled_at": "2024-01-19T08:00:00Z",
"title": "Appointment reminder",
"message": "You have a consultation tomorrow at 10:00.",
"context_type": "appointment",
"context_id": "apt-123-456"
}'RESPONSE201
{
"id": "rem-789-012",
"patient_uhid": "UG987654321B",
"kind": "appointment",
"channel": "whatsapp_message",
"status": "scheduled",
"scheduled_at": "2024-01-19T08:00:00Z"
}Environments
| Environment | Base URL | Credentials |
|---|---|---|
| Sandbox | https://sandbox.api.mediloop.co | Use an sk_test_ key (isolated test data) |
| Production | https://api.mediloop.co | Use an sk_live_ key (live data) |