Raktify Developer API

Public REST webhook contract for blood-bank software vendors to sync donor and donation records into Raktify, India's district-wide blood-response platform.

Everything you need, in one place

Overview

Raktify is a not-for-profit blood-response platform built by Choudhari EduHealth India Foundation. It runs the matching pipeline between hospitals with urgent blood requests, blood banks holding tested inventory, and voluntary donors in the surrounding district.

Blood banks already run software — Safetrans (Strides), e-RaktKosh, BLIS, RAKT, or homegrown Excel/Access systems. Asking a technician to also type each donor and donation into Raktify is friction that will kill adoption. Instead we publish a single webhook contract: your software pushes an event, our platform mirrors it. Direction is vendor → Raktify (push) — you don't need to open any inbound ports or expose credentials.

Who this is for

• BB software vendors (Safetrans/Strides, e-RaktKosh, BLIS, RAKT, and any homegrown system) who want their hospital clients to appear in Raktify's matching pool without dual data entry.
• Hospital IT teams maintaining in-house BB software; you can implement the client yourself in ~1 day.
• Standards-based tools — we publish an OpenAPI 3.0 spec. Any language that can HTTP + HMAC-SHA256 can integrate.

Quickstart

1. Request a partner key for each hospital installation you integrate.
2. Every donor registration your operator completes: POST to /webhooks/v1/donor-registration.
3. Every donation event (draw + TTI screening result): POST to /webhooks/v1/donation.
4. Sign each request body with your partner key's HMAC-SHA256 secret; carry X-Raktify-Partner-Key and X-Raktify-Signature headers.
5. Include a vendor_event_id in every payload. Retries with the same ID are safe (idempotent).

Authentication

HMAC-SHA256 request signing

Every request MUST carry two headers:

Signing example (Node)

const crypto = require('crypto');
const body = JSON.stringify(payload);
const signature = crypto
  .createHmac('sha256', PARTNER_SECRET)
  .update(body)
  .digest('hex');

fetch('https://raktify-api.azurewebsites.net/webhooks/v1/donor-registration', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Raktify-Partner-Key': 'pk_your_key_here',
    'X-Raktify-Signature': 'sha256=' + signature,
  },
  body,
});

Signing example (Python)

import hmac, hashlib, json, requests

body = json.dumps(payload).encode('utf-8')
sig = hmac.new(PARTNER_SECRET.encode('utf-8'), body, hashlib.sha256).hexdigest()

requests.post(
    'https://raktify-api.azurewebsites.net/webhooks/v1/donor-registration',
    data=body,
    headers={
        'Content-Type': 'application/json',
        'X-Raktify-Partner-Key': 'pk_your_key_here',
        'X-Raktify-Signature': 'sha256=' + sig,
    },
)

Getting a partner key

Partner keys are for blood-bank software vendors only. This is a one-way push API for software that runs at a hospital or blood bank, and keys are not issued to individual developers or students. It has no endpoints to search donors, check availability or contact a donor; we do not expose donor data to third-party applications.

Partner keys are issued per hospital installation. If your software serves five hospitals, you get five distinct keys — that way we can revoke a single hospital's key without affecting the others.

To request a key, contact contact@choudhari.ngo with:

• Vendor / company name
• Hospital(s) currently using your software that want Raktify integration
• Technical contact for the integration engineer

We reply with the partner_key and the HMAC secret (revealed exactly once — save it into your credentials store immediately). Self-service issuance via an admin panel is on the roadmap.

Endpoints

Base URL: https://raktify-api.azurewebsites.net

All request and response bodies are JSON. Successful writes return 202 Accepted (the row is stored and the consent flow is enqueued asynchronously).

{
  "raktify_donor_id": "6fda231f-9e7e-4a1d-8761-87e15f83d1ee",
  "action": "created",             // "created" | "updated_pending" | "updated_consented"
  "is_new": true,
  "consent_status": "pending"      // "pending" | "active"
}

{
  "raktify_donor_id": "6fda231f-9e7e-4a1d-8761-87e15f83d1ee",
  "raktify_donation_id": "4ab05951-f222-4e14-9993-4ea38372b777",
  "action": "created"
}

Reliability

Idempotency

Every request MUST include vendor_event_id. If your delivery layer retries after a network blip, retries with the same (partner_key, vendor_event_id) pair return the original result cached from the first attempt — the same raktify_donor_id, the same status. This lets you use at-least-once delivery semantics safely.

Idempotency records are retained for 30 days. Beyond that, a repeat of an old vendor_event_id is treated as a fresh request.

Rate limits

Currently 100 requests / IP / minute globally. Your partner key isn't rate-limited separately — the global limit is generous enough for any normal BB workflow (a busy blood bank processes ~50 donations per day). If you need higher throughput for a batch backfill, contact us to arrange a temporary uplift.

Responses on rate-limit: 429 with {"error":"rate_limit_global"} and a Retry-After header. Back off + retry.

Error reference

Consent flow — what happens after your push

India's Digital Personal Data Protection Act (DPDP §7) requires explicit donor consent before we process their PII for platform purposes. Your push tells us the donor exists at a specific blood bank; consent is captured separately on Raktify's own screen.

1. Your push lands. Donor row is created with consent_data_use=false and consent_pending_since=NOW().
2. Raktify sends the donor a WhatsApp (approved Meta template donor_consent_invite) with a magic link to https://raktify.choudhari.ngo/consent/<token>.
3. The donor sees Raktify's own consent screen — what data we hold, what we'll do with it, their DPDP rights — and taps Accept, Decline, or defers.
4. Accept: consent_data_use flips to true; the donor becomes visible to matching for compatible requests in their district.
5. Decline: we run the donor-erasure scrub (mobile tombstoned, name and address wiped) within seconds.
6. No response in 14 days: the same scrub runs automatically. We don't retain PII we have no lawful basis to process.

Interactive API browser

Browse the full OpenAPI 3.0 spec below — expand any endpoint to see the schema, examples, and error responses. Requests you fire from here hit the live production API; without a valid X-Raktify-Partner-Key + HMAC signature they'll return 401 signature_mismatch (that's the correct auth response). For real end-to-end testing use the Postman collection — it auto-signs with your partner secret.

Downloads & tooling

All artifacts for the vendor push webhook. Machine-readable and human-readable in one place.

• /api/vendor-webhook-v1.yaml — OpenAPI 3.0.3, single source of truth. Import into openapi-generator, Insomnia, Postman.
• /api/vendor-webhook-v1.postman_collection.json — Postman v2.1 collection with an HMAC-SHA256 pre-request script; import, set partner_key + partner_secret, hit Send.
• /developers.md — Markdown version of this whole page. Feed it to Claude / ChatGPT / any AI coding assistant as context and ask it to write the client for you in any language.

The spec is versioned in the URL (/webhooks/v1/). Adding an optional field is not a version bump; changing semantics, removing, or renaming fields would be v2 and would run alongside v1.

Contact + support

• Get a partner key / start integration (blood-bank software vendors only): contact@choudhari.ngo
• Report a bug or ask a question: same address — reply time is typically same day IST business hours.
• About the platform: How Raktify works · Home
• Legal: Terms · Privacy · Data deletion