> ## 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.

# Receive a scanned profile as a HIP

> Accept the profile a patient shares by scanning your counter QR, and reply with a token.

## In short

* Eka sends a profile shared from your facility QR on `abha.hip_profile_share`.
* Match or register the patient, and issue an OPD token for the counter in `hip_code`.
* Reply with On-Share, sending the webhook's `req_id` as `request_id`.

## When to use this

A patient at your registration counter scans the facility's Health Facility QR code with a PHR app and shares their ABHA profile. Eka sends you the profile on a webhook. You register or match the patient, issue an OPD token, and reply with it. The PHR app shows the patient the token.

This replaces asking the patient for their ABHA at the counter. If the patient has no PHR app, register them at the desk. Use [Log in to an existing ABHA](https://developer.eka.care/docs/hie-cm/workflows/login-abha.md) or [Create an ABHA with Aadhaar OTP](https://developer.eka.care/docs/hie-cm/workflows/create-abha-aadhaar-otp.md).

The PHR app's side of this exchange, scanning and fetching the token, is a separate workflow: [Share a profile at a facility counter](https://developer.eka.care/docs/hie-cm/workflows/phr-scan-and-share.md).

## Before you start

* A client access token, sent as a Bearer token. See [Authorization](https://developer.eka.care/api-sdk/auth/getting-started.md).
* Your facility onboarded as a Health Information Provider (HIP), with its HIP ID.
* A Health Facility QR code displayed at each counter, each with its counter id (`hip_code`).
* A webhook URL registered with Eka that can receive `abha.hip_profile_share`, and the means to verify the [webhook signature](https://developer.eka.care/docs/webhooks/webhook-signature.md).
* A way to issue OPD token numbers in your system.

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant PHR as Patient's PHR app
  participant Eka
  participant App as Your app
  PHR->>Eka: Scan facility QR and share profile
  Eka-->>App: webhook abha.hip_profile_share
  App->>Eka: POST /abdm/v1/hip/patient/profile/on-share
  Eka-->>PHR: Token for the patient
```

## Steps

**1. Receive the shared profile**

Eka sends the [`abha.hip_profile_share`](https://developer.eka.care/docs/hie-cm/webhooks/hip-scan-and-share) webhook. Acknowledge it with HTTP `200` within 5 seconds; Eka retries on any other status.

From `data`, keep `req_id`, `abha_address`, `abha_number`, `hip_code` (the counter the patient scanned), `hip_id`, `oid` and `partner_patient_id`.

Look the patient up by `abha_address` or `abha_number`. If you find them, use that record. If not, register a new patient and save `abha_address`, `abha_number` and `oid` on the record. Issue an OPD token for the counter in `hip_code`.

**2. Reply with the token**

Call [On-Share](https://developer.eka.care/api-sdk/hie-cm/scan-and-share/scan-on-share.md). Send the patient's `oid` in `X-Pt-Id`, your patient id in `X-Partner-Pt-Id` and your HIP ID in `X-Hip-Id`. In the body send:

* `request_id`: the `req_id` from the webhook.
* `abha_address`: from the webhook.
* `hip_code`: the counter id from the webhook.
* `token`: with `token_number` (required) and `expires_at`.

If you cannot register the patient or issue a token, send `error` with `code` and `message` instead of `token`.

The call returns `202 Accepted`. Eka passes the token to the patient's PHR app.

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `req_id` | `abha.hip_profile_share` | Until on-share returns `202` | `request_id` in the on-share reply |
| `hip_code` | `abha.hip_profile_share` | Until on-share returns `202` | Issuing the token for the right counter, and the reply |
| `abha_address`, `abha_number`, `oid` | `abha.hip_profile_share` | Forever, on the patient record | Linking this visit as a care context, and every later ABDM call |
| `token_number` | Your token system | For the visit | Calling the patient at the counter |

## 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.

Error responses carry `code`, `error` and `source_error`. The codes below are from the [errors page](https://developer.eka.care/docs/hie-cm/errors.md).

| Situation | Code | Do |
| - | - | - |
| On-share body malformed or a field missing | `ABDM-1006`, `ABDM-1010` | Check `request_id` and `abha_address` are set and resend |
| Request id not recognised | `ABDM-1030`, `ABDM-1052` | Check you sent the webhook's `req_id` |
| Share could not reach the hospital | `ABDM-1018` | Retry later; register the patient at the desk meanwhile |
| Profile share keys invalid | `ABDM-1049`, `ABDM-1050` | Not documented |
| Your webhook did not answer within 5 seconds | No code; Eka retries the webhook | Acknowledge first, then register and reply |

## 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.

* [ ] Scan your sandbox facility QR from a PHR app with a test ABHA and receive `abha.hip_profile_share`
* [ ] Reply with a `token_number` and get `202 Accepted`; the PHR app shows the token
* [ ] Share the same ABHA again and confirm you match the existing patient instead of creating a duplicate
* [ ] Reply with `error` instead of `token` and check what the PHR app shows


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