Blood Bank Discovery

Blood Bank Discovery helps an EUA find blood stock across Blood Bank HSPAs through UHI. Phase 1 supports only search and on_search. Use this page with the shared UHI guide at /docs/uhi/v1/network-and-protocol.

Roles

Flow

sequenceDiagram
participant EUA
participant Gateway
participant HSPA as Blood Bank HSPA
EUA->>Gateway: search
Gateway-->>EUA: ACK
Gateway->>HSPA: search
HSPA->>Gateway: on_search
Gateway->>EUA: on_search
EUA-->>Gateway: ACK

Service identity

Authentication

Sign each UHI request with Ed25519 and a BLAKE-512 body digest. Follow the shared header, ACK, and callback rules at /docs/uhi/v1/network-and-protocol.

Search filter types

Field references

search context

search message.intent

on_search provider record fields

Sample payloads

Use code -1 and name All to search all blood groups. Use a component code from the master list.

{
  "context": {
    "domain": "nic2008:86906",
    "country": "IND",
    "city": "std:011",
    "action": "search",
    "core_version": "0.7.1",
    "consumer_id": "<your-eua-id>",
    "consumer_uri": "<your-https-callback-url>",
    "message_id": "5cc46ce0-cd96-11ef-957f-718cff4e4e0a",
    "timestamp": "2025-01-08T07:58:36.421576Z",
    "transaction_id": "5cc46ce0-cd96-11ef-957f-718cff4e4e0a"
  },
  "message": {
    "intent": {
      "item": { "descriptor": { "name": "O+Ve", "code": "15" } },
      "fulfillment": {
        "type": "BloodStock",
        "start": { "time": { "timestamp": "2025-01-08T13:28:36" } },
        "end": { "time": { "timestamp": "2025-01-08T23:59:59" } }
      },
      "category": { "descriptor": { "name": "WholeBlood", "code": "11" } },
      "location": {
        "gps": "17.3788008,78.4368212",
        "radius": { "type": "CONSTANT", "value": "10.0", "unit": "km" }
      }
    }
  }
}

on_search sample

The source has a larger stock list. This sample keeps 2 blood group items for 1 provider.

{
  "context": {
    "domain": "nic2008:86906",
    "action": "on_search",
    "consumer_id": "<your-eua-id>",
    "consumer_uri": "<your-https-callback-url>",
    "provider_id": "nha.hspa",
    "provider_uri": "https://hspasbx.abdm.gov.in/api/v1/bloodbank",
    "transaction_id": "c51c2800-cd96-11ef-957f-718cff4e4e0a",
    "message_id": "c51c2800-cd96-11ef-957f-718cff4e4e0a"
  },
  "message": {
    "catalog": {
      "descriptor": {
        "name": "e-RaktKosh",
        "short_desc": "e-RaktKosh: A Centralized Blood Bank Management System"
      },
      "providers": [
        {
          "id": "0",
          "descriptor": {
            "name": "Janseva Blood Centre",
            "short_desc": "Charitable/Vol"
          },
          "categories": [
            { "id": "0", "descriptor": { "name": "WholeBlood", "code": "11" } }
          ],
          "fulfillments": [
            { "id": "0", "type": "NotAvailable" },
            { "id": "1", "type": "Available" }
          ],
          "items": [
            {
              "id": "0",
              "descriptor": { "name": "O+Ve", "code": "15" },
              "quantity": { "count": 2 },
              "category_id": "0",
              "fulfillment_id": "1"
            },
            {
              "id": "1",
              "descriptor": { "name": "AB+Ve", "code": "17" },
              "quantity": { "count": 16 },
              "category_id": "0",
              "fulfillment_id": "0"
            }
          ],
          "location": {
            "gps": "18.5246036,73.792927",
            "address": "Paud Road, Pune, Maharashtra",
            "city": { "name": "Pune" },
            "state": { "name": "Maharashtra", "code": "27" },
            "district": { "name": "Pune", "code": "521" }
          },
          "contact": {
            "phone": "8987628900",
            "email": "contact@jansevabc.org"
          }
        }
      ]
    }
  }
}

Service-specific masters

Blood group master

Blood component master

Known limitations

• Offer state and district search as a GPS fallback.
• Show a stock disclaimer before users travel.
• Recommend a call to confirm stock before travel.
• Set a 10 to 15 second callback timeout.
• Add client-side pagination for large catalogs.
• Keep reservation workflows outside Phase 1.

Onboarding steps

Use this service checklist with /docs/uhi/v1/onboarding.

Technical prerequisites

EUA prerequisites

• Use an ABDM-compliant app with M2 of HIECM complete.
• Publish an HTTPS consumer_uri for on_search callbacks.
• Create UHI Authorization headers for search requests.
• Accept asynchronous on_search responses.
• Use the UHI Postman Collection for sandbox tests.

HSPA prerequisites

• Maintain blood group and component inventory data.
• Publish an HTTPS provider_uri for Gateway search requests.
• Create UHI Authorization headers for on_search callbacks.
• Return a valid on_search payload inside an acceptable latency window.
• Complete sandbox tests and get NHA approval before production.

Resources and support