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

# Share a profile at a facility counter

> The patient scans a facility's QR code, your PHR app shares their ABHA profile with that counter, and you poll for the token number.

## In short

* Share the patient's profile with the counter whose QR code they scanned.
* The share returns `202` and a `request_id`; poll with it for the token.
* On `success`, show `token_number` and `expiry`; on `failed`, offer to scan again.

## When to use this

The patient is at a facility's registration counter and scans its Health Facility QR code in your PHR app. You share their ABHA profile with that counter, so the facility's software registers them without a form. Then you show the token number the facility issues.

This is the PHR side. If your software runs the facility's counter and receives the scanned profile, use [Receive a scanned profile as a HIP](https://developer.eka.care/docs/hie-cm/workflows/hip-scan-and-share.md) instead.

## Before you start

* A client access token, sent as a Bearer token. See [Authorization](https://developer.eka.care/api-sdk/auth/getting-started.md).
* A logged-in patient and their Eka user id (`oid`), sent as the `X-Pt-Id` header or the `oid` query parameter. See [Log in to an existing ABHA](https://developer.eka.care/docs/hie-cm/workflows/login-abha.md). 
* A live ABHA gateway session, if this call needs one. See [Hold an ABHA gateway session](https://developer.eka.care/docs/hie-cm/workflows/hold-gateway-session.md). 
* A QR scanner in your app, and permission to read the device location.
* The patient's profile: ABHA address, name, gender, day, month and year of birth, and mobile. See [Manage the ABHA profile and KYC](https://developer.eka.care/docs/hie-cm/workflows/manage-profile-and-kyc.md).

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant Patient as Patient's phone
  participant App as Your app
  participant Eka
  participant HIP as Facility (HIP)
  Patient->>App: Scans the facility QR code
  App->>Eka: POST /abdm/v2/profile/share
  Eka-->>App: 202 with request_id
  Eka->>HIP: Profile shared through the ABDM gateway
  HIP-->>Eka: Token number
  loop Until status is no longer processing
    App->>Eka: GET /abdm/v2/profile/share/{request_id}
  end
  Eka-->>App: token_number and expiry
```

## Steps

**1. Share the profile**

Read `hip_id` and `counter_id` from the scanned QR code. Send both, the device's `latitude` and `longitude` in `location`, and the patient's profile in `patient`, to [Request to generate token](https://developer.eka.care/api-sdk/hie-cm/scan-and-share/phr-scan-share.md). In `patient`, `abha_address`, `name`, `gender`, `day_of_birth`, `month_of_birth`, `year_of_birth` and `mobile` are required.

The call is asynchronous. It returns HTTP `202` with `request_id` and `status`. Keep `request_id`.  

**2. Poll for the token**

Call [Get appointment token](https://developer.eka.care/api-sdk/hie-cm/scan-and-share/phr-scan-share-token.md) with `request_id` in the path. The response carries `status`, `token_number` and `expiry`.

The spec gives `status` three values: `success`, `processing` and `failed`. While it is `processing`, the facility has not answered; call again. When it is `success`, show `token_number` and its `expiry` to the patient. When it is `failed`, tell the patient the share did not go through and offer to scan again.    

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `oid` | ABHA creation or login | On the patient record, for as long as the patient uses your app | `X-Pt-Id` or `oid` on both calls |
| `hip_id`, `counter_id` | The scanned QR code | Until polling ends | Share request; show the patient which facility they checked in at |
| `request_id` | Share response | Until `status` is `success` or `failed` | Every poll |
| `token_number`, `expiry` | Poll response | Until `expiry` | Show the patient their token 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.

Errors come back as HTTP 4XX or 5XX with a `GenericError` body: `code`, `error` and `source_error`. Codes are on the [errors page](https://developer.eka.care/docs/hie-cm/errors.md). 

| Situation | Code | Do |
| - | - | - |
| `hip_id` or `counter_id` missing, or a required `patient` field missing | HTTP 4XX, for example [`ABDM-1010`](https://developer.eka.care/docs/hie-cm/errors) | Rescan the QR code; fill the profile fields |
| QR code from an unknown facility | [`ABDM-1035`](https://developer.eka.care/docs/hie-cm/errors) (Invalid HIP ID) | Ask the patient to scan the counter's QR code again |
| Patient's gateway session expired | HTTP `491` | Run [Hold an ABHA gateway session](https://developer.eka.care/docs/hie-cm/workflows/hold-gateway-session.md), then share again |
| Unknown `request_id` on the poll | [`ABDM-1030`](https://developer.eka.care/docs/hie-cm/errors) | Use the `request_id` from the share response; if lost, share again |
| Poll returns `failed`, for example because the profile could not reach the facility | `status: failed` on the poll. Share returns `202` and the facility answers later, so a failure such as [`ABDM-1018`](https://developer.eka.care/docs/hie-cm/errors) (Unable to share the details with Hospital) or [`ABDM-1028`](https://developer.eka.care/docs/hie-cm/errors) is not returned to your app as an error | Retry later; register the patient at the desk meanwhile |
| Facility never answers | `status` stays `processing` | Stop polling at your limit and tell the patient |

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

Run against the Stage/Sandbox server, `https://api.dev.eka.care`. 

* [ ] Share with the test `hip_id`, `counter_id`, a location and the patient's profile returns `202` and a `request_id`
* [ ] Polling with that `request_id` moves from `processing` to `success` with a `token_number` and `expiry`
* [ ] Share without `counter_id` fails with a 4XX
* [ ] Poll with an unknown `request_id` fails
* [ ] A facility that does not answer: polling stops at your limit and the app tells the patient


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