> ## Documentation Index
> Fetch the complete documentation index at: https://developer.eka.care/llms.txt
> Use this file to discover all available pages before exploring further.

# Search blood banks over UHI

> Find blood banks that hold a blood group and component, by state and district or by location and radius.

## In short

* Search blood banks over UHI by state and district, or by a location and radius.
* Keep `request_id` from Search Blood Banks and pass it to Get Blood Banks.
* Tell the user to check with the blood bank before they visit.

## When to use this

Your user needs a blood group and component, and wants to know which blood banks hold it. You search across blood banks on the Unified Health Interface (UHI) by state and district, or by a location and a radius around it. Availability is updated periodically, so tell the user to check with the blood bank before they visit.

## Before you start

* A Bearer token. Both operations use the `authApiKey` scheme. See [Authorization](https://developer.eka.care/api-sdk/auth/getting-started.md).
* The blood group and blood component the user needs.
* Either the state and district, or the user's latitude, longitude and a search radius.
* The patient headers, if your integration sends them. 

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  App->>Eka: POST /abdm/uhi/v1/blood-bank/search
  App->>Eka: GET /abdm/uhi/v1/blood-bank/search/{request_id}
```

## Steps

**1. Start the search**

Send `search_type`, `blood_group` and `blood_component` to [Search Blood Banks](https://developer.eka.care/api-sdk/uhi/blood-bank/state-district.md). All three are required. For a district search, also send `state` and `district`. For a location search, send `search_type` `location`, `location` with `lat` and `long`, and `radius` with `value` and `unit`, for example `km`.

Keep `request_id` from the response. `status` is `SUCCESS` or `FAILURE`; on `FAILURE`, check the request.

**2. Read the results**

Call [Get Blood Banks](https://developer.eka.care/api-sdk/uhi/blood-bank/get-blood-banks.md) with `request_id`. The response carries `status` and `data`, which holds `context`, `message.catalog` with the matching blood banks, and `error_code` if the search failed. Show each blood bank's name, contact details and availability.

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `request_id` | Search Blood Banks | Until the results are read | Get Blood Banks |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](https://developer.eka.care/docs/hie-cm/errors.md), matched by meaning. Log the code you actually receive.

Both operations return `GenericError` with `code`, `error` and `source_error` on a 4XX or 5XX. A failure in the search itself comes back in `data.error_code` with `code` and `message`. See [Errors](https://developer.eka.care/docs/hie-cm/errors.md).

| Situation | Code | Do |
| - | - | - |
| Missing `search_type`, `blood_group` or `blood_component` | 4XX | Fix the request |
| District search without `state` or `district`, or location search without `location` or `radius` | 4XX | Send the fields for that search type |
| Search not accepted | `status` `FAILURE` | |
| Unknown `request_id` | | Start a new search |
| No blood bank matches | | Widen the radius or try a neighbouring district |
| Upstream unavailable | 5XX | Retry later |

## Test it

The [testing page](https://developer.eka.care/docs/hie-cm/testing.md) has the sandbox base URL, credentials and the happy path for every journey.

* [ ] District search with a test state, district, blood group and component; receive `request_id` and `SUCCESS`
* [ ] Get Blood Banks with that `request_id`; results list at least one blood bank
* [ ] Location search with a test latitude, longitude and a 10 km radius
* [ ] Failure: a search without `blood_group` returns a 4XX


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.