Blood bank discovery

Blood bank discovery is the smallest service on UHI: one call pair. Your app sends a search with a blood group, a component and a location, and gets back blood banks with unit counts, addresses and phone numbers.

Read UHI services first, for the context block, the acknowledgement model, signing and the two transports.

Scope​

Discovery only: search and on_search. There is no booking or reservation. Put the blood bank's phone number somewhere the user cannot miss it, because calling is how a unit gets held.

Service identity​

Who is involved​

Both roles are open here. An organisation can onboard as either or both.

At the time of the document there was one registered blood bank HSPA on the network: e-RaktKosh, the centralised blood bank management system.

NHA sets a bar for the HSPA role. Your blood bank database has to be maintained independently and cover stock at a scope and quality comparable to e-RaktKosh. Integrations built on manually maintained or infrequently updated records will not be approved for production.

The flow​

There is no end signal. Responses land one at a time and nothing tells you the last one has arrived. Use a timeout window of 10 to 15 seconds, and display results as they come in.

Two search modes​

Blood group and component filters work with either mode.

Support both. GPS returns incomplete results where blood bank density is low, and state and district is the only option when GPS is unavailable.

search​

context is the standard UHI block, with domain fixed to nic2008:86906 and action set to search. Set city to std:011 as the default. The filters live in message.intent.

Sample, GPS with a specific group and component​

{
  "context": {
    "domain": "nic2008:86906",
    "country": "IND",
    "city": "std:011",
    "action": "search",
    "core_version": "0.7.1",
    "consumer_id": "<YOUR_EUA_ID_FROM_NHA_ONBOARDING>",
    "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" }
      },
      "category": {
        "descriptor": { "name": "WholeBlood", "code": "11" }
      },
      "fulfillment": {
        "type": "BloodStock",
        "start": { "time": { "timestamp": "2025-01-08T13:28:36" } },
        "end": { "time": { "timestamp": "2025-01-08T23:59:59" } }
      },
      "location": {
        "gps": "17.3788008,78.4368212",
        "radius": { "type": "CONSTANT", "value": "10.0", "unit": "km" }
      }
    }
  }
}

To search every blood group at once, set item.descriptor.name to All and item.descriptor.code to -1.

Sample, state and district​

Replace the location block. Everything else is the same.

{
  "location": {
    "state": { "name": "DELHI", "code": "7" },
    "district": { "name": "SOUTH", "code": "83" }
  }
}

on_search​

The part that trips people up​

Availability is not a field on the item. Each provider declares a small set of fulfillments, one meaning Available and one meaning NotAvailable. Each blood group item points at one of them through fulfillment_id. A group with a unit count of 16 can still be unavailable. Resolve the link before you show a number to a user.

Sample response​

{
  "context": {
    "domain": "nic2008:86906",
    "action": "on_search",
    "consumer_id": "<YOUR_EUA_ID_FROM_NHA_ONBOARDING>",
    "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"
          }
        }
      ]
    }
  }
}

In that response O+Ve points at fulfilment 1, which is Available. AB+Ve has a count of 16 but points at fulfilment 0, which is NotAvailable.

Blood group master list​

Use these in item.descriptor.code.

Blood component master list​

Use these in category.descriptor.code.

Known limitations​

Prerequisites​

For an EUA:

• ABDM M2 with HIE-CM completed. This is a hard prerequisite for any UHI service.
• A publicly reachable HTTPS consumer_uri.
• Ed25519 signing with BLAKE-512 body hashing.
• Asynchronous handling. Do not block on a synchronous reply to search.

For an HSPA:

• An independently maintained blood bank database with real-time or near real-time inventory, comparable in scope and quality to e-RaktKosh.
• A publicly reachable HTTPS provider_uri to receive searches from the gateway.
• Ed25519 signing on every outbound response.
• Sandbox integration and written sign-off before production.

What is missing here​

• No error code list is published for this service.
• No response time SLA is published for HSPAs beyond an acceptable latency window.
• State and district codes are issued at onboarding. Delhi is 7 and South district is 83.

Next​

• UHI services for the shared protocol
• Ambulance booking
• Physical consultation
• Support