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

# Overview

> Environments, authentication, headers, callbacks and errors for the ABDM Connect APIs, plus a Postman collection with every API and callback.

export const PostmanCollection = ({collection, environment, postmanCollectionId, postmanWorkspaceId, children}) => {
  const [copied, setCopied] = useState(false);
  const [failed, setFailed] = useState(false);
  const link = "https://developer.eka.care" + collection;
  const download = event => {
    event.preventDefault();
    const path = event.currentTarget.getAttribute("href");
    const sources = [path, "https://raw.githubusercontent.com/eka-care/eka-docs/main" + path];
    setFailed(false);
    const attempt = i => {
      if (i === sources.length) {
        setFailed(true);
        return;
      }
      fetch(sources[i]).then(response => response.ok ? response.text() : Promise.reject()).then(text => {
        JSON.parse(text);
        const url = URL.createObjectURL(new Blob([text], {
          type: "application/json"
        }));
        const a = document.createElement("a");
        a.href = url;
        a.download = path.split("/").pop();
        document.body.appendChild(a);
        a.click();
        a.remove();
        setTimeout(() => URL.revokeObjectURL(url), 1000);
      }).catch(() => attempt(i + 1));
    };
    attempt(0);
  };
  const forkUrl = postmanCollectionId && postmanWorkspaceId ? "https://god.gw.postman.com/run-collection/" + postmanCollectionId + "?action=collection%2Ffork&source=rip_markdown&collection-url=" + encodeURIComponent("entityId=" + postmanCollectionId + "&entityType=collection&workspaceId=" + postmanWorkspaceId) : null;
  const copy = event => {
    const code = event.currentTarget.previousElementSibling;
    navigator.clipboard.writeText(link).then(() => {
      setCopied(true);
      setTimeout(() => setCopied(false), 1500);
    }).catch(() => {
      window.getSelection().selectAllChildren(code);
    });
  };
  const downloadIcon = <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
      <path d="M12 3v12" />
      <path d="m7 10 5 5 5-5" />
      <path d="M4 17v2a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-2" />
    </svg>;
  return <div className="eka-postman not-prose">
      <div className="eka-postman-text">{children}</div>
      <div className="eka-postman-actions">
        <a className="eka-postman-btn eka-postman-btn-primary" href={collection} download onClick={download}>
          {downloadIcon} Collection
        </a>
        {environment && <a className="eka-postman-btn" href={environment} download onClick={download}>
            {downloadIcon} Environment
          </a>}
        {forkUrl && <a className="eka-postman-btn" href={forkUrl} target="_blank" rel="noopener noreferrer">
            <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
              <circle cx="6" cy="5" r="2" />
              <circle cx="18" cy="5" r="2" />
              <circle cx="12" cy="19" r="2" />
              <path d="M6 7v2a3 3 0 0 0 3 3h6a3 3 0 0 0 3-3V7" />
              <path d="M12 12v5" />
            </svg>
            Fork in Postman
          </a>}
      </div>
      {failed && <div className="eka-postman-error" role="alert">
          The download didn't work. Try again, or import the link below in Postman.
        </div>}
      <div className="eka-postman-link">
        <code>{link}</code>
        <button type="button" onClick={copy} aria-label="Copy collection link" title={copied ? "Copied" : "Copy link"}>
          {copied ? "Copied" : <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
              <rect x="9" y="9" width="12" height="12" rx="2" />
              <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
            </svg>}
        </button>
      </div>
      <div className="eka-postman-note">
        Postman, Insomnia, Hoppscotch and Bruno take this through Import, as a link or as the downloaded file.
      </div>
    </div>;
};

ABDM Connect is a REST API over the ABDM gateway. You call Eka, and Eka handles ABDM's gateway protocol, encryption and callbacks for you. This page covers what every ABDM Connect call has in common. New to ABDM? Read the [ABDM overview](/integrations/interoperability/abdm) first for the ecosystem, roles and milestones.

## Postman Collection

<PostmanCollection collection="/api-reference/user-app/abdm-connect/postman/eka-abdm-connect.postman_collection.json" environment="/api-reference/user-app/abdm-connect/postman/eka-abdm-connect-sandbox.postman_environment.json">
  Every ABDM Connect API and callback, grouped by milestone in the order you build them, and a sandbox environment to fill in. Run **Connect Login** first; each step keeps the `txn_id`, `request_id` and user token it gets back for the steps after it. Callback requests replay the payloads Eka sends, so you can test your own webhook receiver.
</PostmanCollection>

## Environments

| Environment | Base URL |
| - | - |
| Sandbox | `https://api.dev.eka.care` |
| Production | `https://api.eka.care` |

Build and certify against the sandbox, then switch the base URL.

## Authentication

Every ABDM Connect API takes an Eka access token for your client.

<Steps>
  <Step title="Log in">
    Call [Connect Login](/api-reference/authorization/client-login) with your `client_id` and `client_secret`. It returns an `access_token` and a `refresh_token`.
  </Step>

  <Step title="Send the token">
    Pass it on every request as `Authorization: Bearer <access_token>`.
  </Step>

  <Step title="Refresh on 401">
    A `401` means the access token expired. Get a new one with [Connect Refresh](/api-reference/authorization/refresh-token-v2).
  </Step>
</Steps>

```bash theme={null}
curl https://api.dev.eka.care/abdm/v1/session/status \
  --header 'Authorization: Bearer <access_token>' \
  --header 'X-Pt-Id: <eka user id>'
```

See [Authorization](/api-reference/authorization/getting-started) to get credentials.

### The patient's ABHA session

Some APIs also act for a specific patient and need their ABHA session with the ABDM gateway. It is separate from your client token:

* ABHA creation, login and [session verify](/api-reference/user-app/abdm-connect/session/verify) return the patient's `token`. APIs that need it, such as KYC, take it as `user_x_token` in the body.
* When the ABHA session expires, these APIs return HTTP `491`. Check it with [Session Status](/api-reference/user-app/abdm-connect/session/status) and start a new one with a mobile OTP. See [User Session](/api-reference/user-app/abdm-connect/session/getting-started).

## Common Headers

Most ABDM Connect APIs take these headers to say which patient and facility the call is for.

| Header | Value |
| - | - |
| `X-Pt-Id` | Eka user ID (OID) of the patient |
| `X-Partner-Pt-Id` | Your own ID for the patient |
| `X-Hip-Id` | Your HIP ID, for the facility the call is made from |

Each API page lists the headers that call takes.

## Multi-step Flows

OTP and linking flows take more than one call. The first call returns a `txn_id` (or a `request_id`), and every later step in that flow sends it back.

## APIs by Milestone

| Milestone | Who needs it | Start here | Flow |
| - | - | - | - |
| M1: ABHA identity | Every integration | [ABHA creation and login](/api-reference/user-app/abdm-connect/registration/intro), [Profile](/api-reference/user-app/abdm-connect/profile/getting-started), [Scan & Share](/api-reference/user-app/abdm-connect/scan-and-share/getting-started) | [M1 flow](/api-reference/user-app/abdm-connect/flows/m1) |
| M2: Care context linking and data sharing | HIPs | [Care contexts](/api-reference/user-app/abdm-connect/care-contexts/getting-started), [Discover and link](/api-reference/user-app/abdm-connect/care-contexts/discover/introduction) | [M2 flow](/api-reference/user-app/abdm-connect/flows/m2) |
| M3: Consent and data fetch | HIUs | [Consents](/api-reference/user-app/abdm-connect/consents/getting-started) | [M3 flow](/api-reference/user-app/abdm-connect/flows/m3) |
| M4: HPR and HFR | Every HMIS/LMIS | [Registries](/api-reference/user-app/abdm-connect/nhpr-abdm/getting-started) | [M4 flow](/api-reference/user-app/abdm-connect/flows/m4) |
| PHR app | Patient-facing apps | [PHR API map](/api-reference/user-app/abdm-connect/phr/overview) | |
| UHI | Discovery and booking | [Blood bank](/api-reference/user-app/abdm-connect/blood-bank/getting-started) | |
| NHCX | Hospitals raising cashless insurance claims | [NHCX claims](/api-reference/user-app/abdm-connect/nhcx/getting-started) | |

## Callbacks

ABDM is asynchronous: many results reach you later as a webhook. Register your endpoint with the [Webhooks API](/api-reference/connect/webhooks/register-webhook). Every callback is a `POST` with a JSON body that names its `event`, and carries an `Eka-Webhook-Signature` header you should [verify](/api-reference/connect/webhooks/webhook-signature).

| Event | Sent when |
| - | - |
| [`abha.created`](/api-reference/user-app/abdm-connect/webhooks/abha-created) | An ABHA address is created |
| [`abha.locker_created`](/api-reference/user-app/abdm-connect/webhooks/locker-created) | A health locker is created |
| [`abha.hip_profile_share`](/api-reference/user-app/abdm-connect/webhooks/hip-scan-and-share) | A patient shares their profile by scanning your QR code |
| [`abha.link_care_context`](/api-reference/user-app/abdm-connect/webhooks/link-care-context) | A care context you linked succeeds or fails |
| [`abha.care_context_discover`](/api-reference/user-app/abdm-connect/webhooks/discover-care-context) | A patient searches your facility for their records |
| [`abha.care_context_discover_link_init`](/api-reference/user-app/abdm-connect/webhooks/discover-link-init) | A patient starts linking the records they found |
| [`abha.context_discover_link_confirm`](/api-reference/user-app/abdm-connect/webhooks/discover-link-confirm) | A patient confirms that link with an OTP |
| [`abha.hip_data_fetch`](/api-reference/user-app/abdm-connect/webhooks/hip-data-fetch) | An HIU requests records you hold (only if Eka doesn't store them) |
| [`abha.hiu_data_push`](/api-reference/user-app/abdm-connect/webhooks/hiu-data-push) | Records you requested arrive from a HIP |
| [`abha.subscription_notify`](/api-reference/user-app/abdm-connect/webhooks/subscription-notify) | A provider links a new record for a subscribed patient |
| [`abha.subscription_modified`](/api-reference/user-app/abdm-connect/webhooks/subscription-modify) | A subscription changes |
| [`abha.consent_update`](/api-reference/user-app/abdm-connect/webhooks/consent-update) | A consent request's status changes |

## Encryption

Health records travel between HIPs and HIUs encrypted with ECDH on Curve25519. If Eka stores your records, Eka encrypts and decrypts them for you. If you serve records yourself, see [ECDH encryption](/api-reference/user-app/abdm-connect/care-contexts/ecdh-encryption).

## Errors

`4XX` codes are request errors and `5XX` are server errors. Error bodies look like this:

```json theme={null}
{
  "code": 400,
  "error": "Validation failed",
  "source_error": {
    "code": "ABDM-1010",
    "message": "Validation failed"
  }
}
```

`source_error` carries ABDM's own code when the gateway refused the call. See [Errors](/api-reference/user-app/abdm-connect/errors) for every code.

## SDKs

<CardGroup cols={2}>
  <Card title="ABHA Web SDK (M1)" icon="id-card" href="/SDKs/web-sdk/abha-sdk/get-started">
    Drop-in ABHA creation, login, KYC and Scan & Share screens.
  </Card>

  <Card title="Consent Management Web SDK (M3)" icon="file-medical" href="/SDKs/web-sdk/consent-management/get-started">
    A UI widget to request, track and act on consents for your patients.
  </Card>

  <Card title="NHPR Web SDK (M4)" icon="user-doctor" href="/SDKs/web-sdk/nhpr-sdk/get-started">
    A UI widget to register doctors on the HPR and their clinic on the HFR.
  </Card>

  <Card title="Go SDK" icon="code" href="/SDKs/backend/go-sdk">
    Backend client for the ABDM Connect APIs.
  </Card>
</CardGroup>


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