Public API
Reference Documentation

{
      "donors": [{
        "id": 12, "unique_id": "Xb3Mn7291", "name": "Md. Rafiqul Islam",
        "blood_group": "B+", "is_available": 1, "total_donations": 7,
        "eligibility_status": "eligible", "recovery_pct": 100,
        "days_until_eligible": 0, "phone_masked": "01712••••••12",
        "is_verified": 1
      }],
      "count": 1, "total": 248, "offset": 0, "limit": 20, "has_more": true
      }

curl "https://blood.islamos.org/api.php?action=donors&blood_group=B%2B&available=1&q=Khulna&limit=10"

{
  "id": 12, "unique_id": "Xb3Mn7291", "name": "Md. Rafiqul Islam",
  "blood_group": "B+", "is_verified": 1,
  "history": [{ "donated_at": "2024-11-03", "location": "iBDN" }]
}

curl "https://blood.islamos.org/api.php?action=donor&id=12"

curl "https://blood.islamos.org/api.php?action=donor_profile&uid=Xb3Mn7291"

{ "message": "Registered successfully", "id": 99, "unique_id": "Xb3Mn7291" }

curl -X POST "https://blood.islamos.org/api.php?action=register" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Numan Ibne Bashir",
    "blood_group": "O+",
    "phone": "+8801712345678",
    "email": "numan@example.com",
    "password": "SecurePass!1",
    "home_district": "Dhaka"
  }'

{
  "message": "Login successful",
  "token": "64-char-hex-session-token",
  "donor": { /* full donor object, password_hash and phone stripped */ }
}

curl -X POST "https://blood.islamos.org/api.php?action=login" \
  -H "Content-Type: application/json" \
  -d '{"email":"fatema@example.com","password":"SecurePass!1"}'

{ "message": "Status updated" }

curl -X PUT "https://blood.islamos.org/api.php?action=update_status" \
  -H "Content-Type: application/json" \
  -d '{"donor_id":12,"is_available":1}'

{
  "message": "Request sent. The donor will contact you if available.",
  "request_id": 45,
  "track_token": "3f8a2b1c...",
  "track_url": "https://blood.islamos.org/track/3f8a2b1c...",
  "email_results": {
    "donor_notified": true, "requester_confirmed": true, "admin_notified": true
  }
}

curl -X POST "https://blood.islamos.org/api.php?action=contact_request" \
  -H "Content-Type: application/json" \
  -d '{
    "donor_id": 12,
    "requester_name": "Dr. Hasan",
    "requester_phone": "01811223344",
    "message": "Emergency post-surgical patient needs 2 bags",
    "bags_needed": 2,
    "location": "Location of Donation"
  }'

{
  "requests": [{
    "id": 7, "blood_group": "O-", "hospital": "Mayo Clinic",
    "urgency": "critical", "bags_needed": 3,
    "time_left": "4 hr left",
    "requester_phone": "017123****78"
  }],
  "total": 5
}

curl "https://blood.islamos.org/api.php?action=public_requests&bg=O-"

{ "message": "Marked as fulfilled" }

curl -X POST "https://blood.islamos.org/api.php?action=fulfill_public" \
  -H "Content-Type: application/json" \
  -d '{"request_id":7}'

{
  "id": 45, "status": "accepted",
  "status_label": "Accepted by Donor", "status_icon": "✅",
  "status_color": "#16A34A",
  "status_desc": "The donor has accepted. They will contact you shortly.",
  "donor_name": "Md. Rafiqul Islam",
  "donor_uid": "Xb3Mn7291",
  "donor_blood_group": "B+",
  "donor_district": "Khulna",
  "donor_present_address": "Khulna Medical College Road",
  "donor_phone_masked": "01712••••••12",
  "donor_email_masked": "raf••••••ul@gmail.com"
}

curl "https://blood.islamos.org/api.php?action=track_request&token=3f8a2b1c..."

{ "message": "Status updated" }

curl -X POST "https://blood.islamos.org/api.php?action=update_request_status" \
  -H "Content-Type: application/json" \
  -d '{"request_id":45,"status":"accepted"}'

{ "message": "Donation submitted for admin approval. Your record will be updated once approved." }

curl -X POST "https://blood.islamos.org/api.php?action=log_donation" \
  -H "Content-Type: application/json" \
  -d '{"donor_id":12,"donated_at":"2025-06-01","location":"Location"}'

{ "message": "Donation submitted for admin approval. Your record will be updated once approved." }

curl -X POST "https://blood.islamos.org/api.php?action=confirm_donation" \
  -H "Content-Type: application/json" \
  -d '{"request_id":45,"location":"Location of Donation"}'

{
  "donations": [{
    "id": 88,
    "donor_id": 12, "donor_name": "Md. Rafiqul Islam",
    "donor_uid": "Xb3Mn7291", "blood_group": "B+",
    "donated_at": "2025-06-01", "location": "iBDN",
    "approval_status": "pending",
    "submitted_by": "donor",
    "donor_verified": 1
  }],
  "count": 3
}

curl "https://blood.islamos.org/api.php?action=pending_donations"

{ "message": "Donation approved and donor stats updated." }

curl -X POST "https://blood.islamos.org/api.php?action=approve_donation" \
  -H "Content-Type: application/json" \
  -d '{"donation_id":88,"admin_id":1,"note":"Verified via hospital record"}'

{ "message": "Donation rejected. Donor notified." }

curl -X POST "https://blood.islamos.org/api.php?action=reject_donation" \
  -H "Content-Type: application/json" \
  -d '{"donation_id":88,"note":"Could not verify — no hospital record found","admin_id":1}'

{
  "total_donors": 312, "available_donors": 198,
  "total_donations": 1074, "total_requests": 456,
  "by_blood_group": [{ "blood_group": "B+", "c": 89 }],
  "top_donors": [{
    "id": 12, "unique_id": "Xb3Mn7291", "name": "Md. Rafiqul",
    "blood_group": "B+", "total_donations": 23, "is_verified": 1
  }],
  "prize": {
    "cycle_number": 2,
    "cycle_end": "2026-12-31",
    "years_left": 0, "months_left": 6, "days_left": 24,
    "ended": false,
    "last_winners": []
  }
}

curl "https://blood.islamos.org/api.php?action=stats"

{ "message": "Preferences updated", "preferences": { /* updated prefs */ } }

curl -X POST "https://blood.islamos.org/api.php?action=update_email_prefs" \
  -H "Content-Type: application/json" \
  -d '{"token":"abc123...","emergency_alerts":true,"newsletter":false}'

{ "message": "Unsubscribed successfully", "preferences": { /* updated */ } }

curl "https://blood.islamos.org/api.php?action=unsubscribe&token=TOKEN&pref=newsletter"