NPS Swasthya – Standard API Specifications & Integration Contracts

Document status: Draft for technical and business finalisation
Applies to: NPS Central and all participating Insurance Companies
This draft: Incorporates PFRDA IT feedback on Draft 2 (12-Oct-2026).
Prepared by: NPS Central technology team
Date: 14-Oct-2026

1Common Integration Architecture and Principles

NPS Central shall act as the customer-facing platform and API consumer/orchestrator for NPS Swasthya. Each participating Insurance Company shall develop, host and maintain APIs conforming to the standard API specifications prescribed in this document.

The Insurance Company shall remain the authoritative system of record for insurance policy information. NPS Central shall not maintain a duplicate policy master. Policy information shall be retrieved from the respective Insurance Company whenever required for subscriber display or authorised servicing.

Component	Responsibility
NPS Central	Customer interface, API consumer/orchestrator, transaction initiation, display of insurer responses
Insurance Company	API development and hosting, pricing, underwriting, policy issuance, policy data and servicing
Insurance Company System	System of record for policy and insurance servicing information
NPS Central API Standard	Common interface, data, security, error and SLA requirements applicable to all insurers (this document)

1.1One contract, every insurer

This document is a provider specification. It defines the APIs each Insurance Company builds and hosts, and the one endpoint NPS Central hosts for insurer notifications. Every Insurance Company exposes the same paths, the same request and response bodies, the same status values and the same error codes. Nothing in a request or response varies by insurer except the values defined in the insurer's own masters (products and reason codes).

NPS Central maintains, for each onboarded Insurance Company, its base URL per environment, its credentials and its masters. To reach a subscriber's insurer, NPS Central selects that configuration by insurerId and makes the identical call. Adding an insurer is therefore an onboarding and configuration activity, not a development activity, on the NPS Central side.

API	Hosted by	Path (relative to the host's base URL)
Token (OAuth 2.0)	Insurance Company	POST /api/v1/nps-swasthya/oauth/token
Premium Calculation	Insurance Company	POST /api/v1/nps-swasthya/premium/calculate
Policy Issuance	Insurance Company	POST /api/v1/nps-swasthya/policy/issue
Policy Issuance Status	Insurance Company	POST /api/v1/nps-swasthya/policy/issuance-status
Policy Details	Insurance Company	POST /api/v1/nps-swasthya/policy/details
Policy Document	Insurance Company	POST /api/v1/nps-swasthya/policy/document
Issuance Callback (optional for insurer to call)	NPS Central	URL provided to each insurer at onboarding

NPS contribution, Health Benefit Account (HBA) charges and payment-gateway charges are NPS-side amounts. They are collected by NPS Central but are not part of the insurer contract and are not sent to the Insurance Company.

1.2Data held by NPS Central

NPS Central retains only the transaction and reference data needed to correlate, poll, audit and reconcile: npsRequestId, quoteId, insurerTransactionId, issuanceRefId, policyNumber, insurerId, issuance status and timestamps. It does not hold policy contents, insured-member details beyond what it sent, or policy documents. Those are always fetched from the Insurance Company.

2Common Subscriber Journey

Step	Actor	Action	API
1	Subscriber	Logs into NPS Central using mobile number, date of birth and OTP authentication.	–
2	Subscriber	Selects NPS Swasthya and chooses Self or Family Floater.	–
3	Subscriber	Enters subscriber/family details and completes the prescribed Good Health Declaration (GHD).	–
4	NPS Central	Obtains premium options from the insurer for eligible PF + Insurance Company + Product + Sum Insured + Deductible combinations.	Premium Calculation
5	Subscriber	Selects the preferred quote and enters the minimum NPS contribution.	–
6	Subscriber	Completes KYC.	–
7	Subscriber	Pays Annual Maintenance Charges, Insurance Premium and NPS Contribution in one payment to NPS Central.	–
8	NPS Central	PRAN is generated.	–
9	NPS Central	Sends the policy issuance request to the selected Insurance Company. The insurer either issues synchronously or acknowledges with an issuanceRefId.	Policy Issuance
10	NPS Central	If not issued synchronously, polls the issuance status until a final status (ISSUED or REJECTED). The insurer may call the callback to prompt an earlier poll.	Issuance Status, Callback
11	NPS Central	On the onboarding confirmation screen, shows the policy and offers the policy document if the insurer reports it as available.	Policy Details, Policy Document
12	Subscriber	Later, from the dashboard, enters the policy number to view the policy and download documents. NPS Central fetches them directly from the insurer.	Policy Details, Policy Document

3Common API Standards

Area	Standard Requirement
Protocol	HTTPS REST APIs. TLS 1.2 minimum, TLS 1.3 preferred. Plain HTTP is not permitted in any environment.
Payload	JSON (UTF-8). Field names are camelCase and case-sensitive.
Versioning	Major version in the path: /api/v1/… Adding an optional field is not a breaking change. A breaking change moves to /api/v2/ with a parallel-run period agreed with NPS Central.
Authentication	Mutual TLS on insurer-hosted APIs (3.1), together with OAuth 2.0 client credentials and private_key_jwt client authentication (3.2).
Encryption and signing	All data in transit is encrypted with TLS 1.2 minimum. Issuance messages and callbacks are signed with JWS (3.10). GHD data is encrypted with JWE (3.11).
Transaction ID	npsRequestId correlates the end-to-end NPS Swasthya transaction, from premium calculation to policy retrieval (3.5).
Request ID	Every HTTP call carries a unique X-Request-Id for tracing, echoed in the response (3.3).
Idempotency	Policy issuance is idempotent on npsRequestId. The insurer issues at most one policy per npsRequestId (3.6).
Error Handling	Insurer-specific errors are mapped to the NPS Swasthya standard error catalogue (Annexure A) and returned in the standard error structure (3.7).
Audit	Insurers maintain API transaction logs and audit trails as required by applicable law/regulation and the agreed retention policy (3.8).
Monitoring	Insurers monitor availability, response time, failures and critical incidents and comply with the agreed SLA/escalation requirements (3.9).

3.1Environments, network and mutual TLS

Each Insurance Company provides a UAT and a Production base URL. All paths in this document are appended to that base URL unchanged.
Both sides allow-list each other's egress IP addresses per environment.
Mutual TLS (mTLS) is mandatory on every API hosted by the Insurance Company, including the token endpoint. NPS Central presents its client certificate; the insurer rejects the TLS handshake if the certificate is missing, expired or not the one registered for NPS Central in that environment.
The Issuance Callback, hosted by NPS Central, does not use mTLS in this version. It is secured by the OAuth access token (3.2), the JWS signature (3.10) and IP allow-listing of the insurer's egress addresses. It carries identifiers and status only (5.9).
NPS Central's client certificates are X.509, RSA 2048-bit minimum, issued by a certificate authority agreed with the insurer at onboarding, one per environment. Certificates are exchanged at onboarding and renewed with at least 30 days' notice, the old certificate remaining valid until the new one is confirmed in use.
mTLS establishes which system is connecting; the OAuth access token (3.2) establishes which APIs it may call. Both are required.
Personal data is never placed in URLs, path segments or query strings. This is why every API in this document, including the retrieval APIs, uses POST.

3.2Authentication

NPS Central authenticates to the Insurance Company using the OAuth 2.0 client credentials grant (RFC 6749 §4.4). The client authenticates to the token endpoint with a signed JWT assertion (private_key_jwt, RFC 7523), so no shared secret is exchanged or stored.

Token endpoint: POST {insurerBaseUrl}/api/v1/nps-swasthya/oauth/token (Content-Type: application/x-www-form-urlencoded)
Request parameters: grant_type=client_credentials client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer client_assertion=<JWT signed by NPS Central> scope=nps-swasthya
Client assertion claims: iss = sub = NPS Central client_id issued by the insurer; aud = the token endpoint URL; jti = unique per assertion; iat; exp ≤ iat + 5 minutes. Signed PS256 (RS256 accepted) with the NPS Central signing key whose kid is registered with the insurer.
Token response: { "access_token": "…", "token_type": "Bearer", "expires_in": 900 }
Token lifetime: Maximum 15 minutes. NPS Central reuses a token until shortly before expiry and requests a new one on HTTP 401.
API calls: Authorization: Bearer <access_token>
Callback (insurer → NPS Central): The same mechanism in the opposite direction. NPS Central issues the insurer a client_id and gives it the NPS Central token endpoint URL at onboarding; the insurer registers its signing public key with NPS Central.

3.3Common HTTP headers

Common HTTP headers

Authorization
StringRequired
Rules: Bearer <access_token>
Content-Type
StringRequired
Rules: application/json
X-Request-Id
String 36Required
Rules: UUID v4, new value on every HTTP attempt including retries. Echoed in the response header and in requestId.
Idempotency-Key
String 20–36Conditional
Rules: Mandatory on Policy Issuance; value = npsRequestId. Not used on other APIs.
X-Client-Id
String 1–20Required
Rules: Calling system: NPSCENTRAL on calls to insurers; the insurer's insurerId on the callback.
X-JWS-Signature
StringConditional
Rules: Detached JWS of the body (3.10). Mandatory on Policy Issuance and Issuance Status requests and responses, and on the Issuance Callback.

3.4Data type conventions

Type	Format	Example	Rule
Date	String yyyy-MM-dd (ISO 8601)	1985-08-15	Valid calendar date.
Timestamp	String ISO 8601 with offset	2026-10-12T10:50:00+05:30	IST offset +05:30. Seconds mandatory, fractions optional.
Amount	String, decimal, exactly 2 decimal places	"4620.00"	INR. Up to 10 integer digits. No currency symbol, commas or negatives. Sent as a string so totals reconcile exactly.
Integer	JSON number	1	Whole numbers only (counts, sequence numbers).
Enum	String, UPPER_SNAKE_CASE	FAMILY_FLOATER	Case-sensitive. Allowed values listed per field.
Code	String	"01"	Codes with leading zeros are strings, never numbers.
Flag	String Y / N	Y
Name	String 1–270	D'Souza Anil	First character A–Z, a–z or apostrophe; then letters, space, apostrophe, dot, hyphen.
Mobile	String 10 digits	9876543210	^[6-9][0-9]{9}$; no +91 prefix.
PRAN	String 12 digits	110012345678	^[0-9]{12}$
Pincode	String 6 digits	600004	^[1-9][0-9]{5}$
Gender	Enum	M	M (male), F (female), T (transgender)

Absent and empty are different: an optional field with no value is omitted, never sent as an empty string or null. A field marked M is never omitted.

3.5Identifiers and correlation

Identifier	Generated by	Purpose and life
npsRequestId	NPS Central	One per subscriber quote journey with one insurer. Sent on Premium Calculation and reused on Issuance, Issuance Status, Callback and Policy Details. Idempotency key for issuance.
X-Request-Id / requestId	Caller	One per HTTP attempt. Tracing only; never used for business correlation.
insurerTransactionId	Insurance Company	Insurer's reference for the premium calculation. Returned in the quote; echoed by NPS Central on issuance.
quoteId	Insurance Company	One per priced option. The subscriber's selected quoteId is sent on issuance.
issuanceRefId	Insurance Company	Acknowledgement of an accepted issuance request. Returned on every issuance response, including when the policy is issued synchronously. Key for the Issuance Status API.
policyNumber	Insurance Company	Policy / certificate number once issued. Key for Policy Details and Policy Document.
documentId	Insurance Company	Opaque reference to one document of a policy. Key for Policy Document.

3.6Idempotency

Policy Issuance is idempotent on npsRequestId (sent as Idempotency-Key and in the body). A repeat with the same npsRequestId and the same body returns the current state of that issuance (same issuanceRefId), with HTTP 200. It never creates a second policy.
A repeat with the same npsRequestId and a different body is rejected with HTTP 409, SWH-3004, and nothing is processed.
The insurer issues at most one policy per npsRequestId, regardless of headers, retries or timing. The idempotency record is kept for at least 90 days.
A request answered FAILED (validation or technical error, no issuanceRefId) is not recorded against the npsRequestId; a corrected request may be sent with the same npsRequestId.
A request answered REJECTED is final for that npsRequestId: every repeat returns the same REJECTED response (5.6.a).
Premium Calculation, Issuance Status, Policy Details and Policy Document are read-style and safe to repeat. A repeated Premium Calculation may return new quoteIds.

3.7Response structure and errors

Every response body carries the common fields below; the API-specific fields sit alongside them. On a failure, errors is present and holds one entry per problem found.

Common response fields

requestId
String 36Required
Rules: Echo of X-Request-Id
Per-call trace ID
npsRequestId
String 20–36Conditional
Rules: Echo, where the request carried one
NPS Swasthya transaction reference
status
EnumRequired
Rules: API-specific values (see each API)
Business outcome of the call
responseTimestamp
TimestampRequired
Time the response was generated
errors
Array 1–50Conditional
Rules: Present when status is FAILED or the call is rejected
List of errors
errors[].errorCode
String 8Required
Rules: SWH-nnnn from Annexure A
Standard error code
errors[].errorDescription
String 1–500Required
Rules: Plain English; no stack traces, SQL or internal hostnames
Readable error description
errors[].field
String 1–150Optional
Rules: JSON path of the offending field, e.g. members[1].dateOfBirth
Field in error
errors[].insurerErrorCode
String 1–30Optional
Insurer's native code, for support only

HTTP status codes follow the catalogue: 200 for a processed call (including business outcomes such as NOT_ELIGIBLE or REJECTED), 400/409/410/422 for request problems, 401/403 for authentication, 404 for an unknown key, 429 for rate limiting and 5xx for provider failures. NPS Central decides whether to retry from the HTTP status and errorCode, never from the description text.

3.8Audit, logging and data protection

Personal data is processed only for the purpose of NPS Swasthya under the Digital Personal Data Protection Act, 2023 and applicable IRDAI and PFRDA regulations.
Both sides log every call with X-Request-Id, npsRequestId, API, HTTP status, errorCode, latency and timestamp. Request and response bodies are not logged in clear.
Personal data in logs is masked (e.g. mobile 98XXXXXX10, PRAN XXXXXXXX5678). GHD answers and descriptions are never logged.
Retention of logs and audit trails: as per applicable regulation and the retention period agreed with NPS Central.

3.9Service levels

Values below are NPS Central's proposed targets; each Insurance Company confirms or proposes alternatives at onboarding. NPS Central applies the caller timeout shown and treats a timeout as "outcome unknown" (never as a rejection).

API	Response time (p95)	Caller timeout	Availability	Rate limit
Premium Calculation	≤ 3 s	10 s	99.5% monthly	50 TPS
Policy Issuance	≤ 5 s	20 s	99.5% monthly	20 TPS
Final issuance status reached	≤ 30 minutes from acknowledgement	–	–	–
Issuance Status	≤ 2 s	10 s	99.5% monthly	50 TPS
Policy Details	≤ 3 s	10 s	99.5% monthly	50 TPS
Policy Document	≤ 5 s	20 s	99.5% monthly	20 TPS
Issuance Callback (NPS Central)	≤ 2 s	10 s	99.9% monthly	–

Planned maintenance requires 48 hours' notice to NPS Central. A P1 incident (API unavailable) is reported to NPS Central within 15 minutes, per the escalation matrix exchanged at onboarding.

3.10Message signing (JWS)

Policy Issuance and Issuance Status requests and responses, and Issuance Callback requests, are signed by the sender with a detached JSON Web Signature (RFC 7515, Appendix F) carried in the X-JWS-Signature header. The body stays plain JSON; the signature proves which party produced it and that it was not altered.

Signed content: The exact bytes of the HTTP body as sent (UTF-8). The receiver verifies against the bytes received, before parsing.
Form: Compact JWS with the payload part left empty: <protected header>..<signature>
Protected header: alg = PS256 (RS256 accepted); kid = sender's signing key; iat = signing time (Unix seconds)
Freshness: The receiver rejects a signature whose iat differs from its own clock by more than 5 minutes.
Keys: RSA 2048-bit minimum, separate from the mTLS certificate key. Public keys exchanged at onboarding as JWKS (a published JWKS URL is preferred).
Key rotation: A new key is published with a new kid at least 30 days before use; the old key remains valid for 30 days after. Receivers select the key by kid.
Failure: A request whose signature is missing or does not verify is rejected with HTTP 400, SWH-2004, without processing. A response that fails verification is treated by NPS Central as an unknown outcome and resolved through the Issuance Status API (5.8).

3.11Encryption of GHD data (JWE)

The Good Health Declaration of each insured member is sent encrypted to the Insurance Company as a JSON Web Encryption value (RFC 7516) in the field members[].ghdEncrypted, on the Premium Calculation and Policy Issuance requests. The rest of the request remains plain JSON. Only the insurer can read the GHD, end to end through gateways, proxies and logs.

Plaintext: The member's GHD object (ghdVersion, responses, description) as defined in 4.4.a, serialised as UTF-8 JSON.
Form: Compact JWE
Protected header: alg = RSA-OAEP-256; enc = A256GCM; kid = insurer's encryption key
Keys: Insurer's RSA encryption key, 2048-bit minimum, separate from its signing and TLS keys; public key exchanged at onboarding as JWKS. Rotation as for signing keys (3.10).
Failure: A value that cannot be decrypted, or whose plaintext is not a valid GHD object, is rejected with HTTP 400, SWH-2005.
Scope: GHD data only in this version. Whether JWE should extend to complete request and response payloads is open for PFRDA confirmation (Annexure D).

Part I – Premium Calculation API

4NPS Swasthya – Premium Calculation API Standard

4.1Purpose

The Premium Calculation API shall enable NPS Central to obtain the applicable insurance premium for eligible insurance products based on subscriber/family details and the Good Health Declaration, for each Sum Insured / Deductible option.

4.2Responsibility

Party	Responsibility
NPS Central	API consumer; submits the required inputs and displays the returned premium unchanged.
Insurance Company	API provider; calculates premium and underwriting loading and returns a quote with a unique quotation number.
Insurance Company	Responsible for correctness of pricing, eligibility and loading under its approved product/pricing framework.

4.3API Definition

POST/api/v1/nps-swasthya/premium/calculatePremium Calculation API

Direction: NPS Central → Insurance Company
Response: Synchronous, within the agreed SLA (3.9)

4.4Request Data

Data Group	Fields
Transaction	Request Id, Time stamp
Subscriber	Name, Gender, Date of Birth
Family Members	Sr. no. of the family member, Name, Gender, Date of Birth, relationship for each insured member
GHD	GHD 1–15 (Annexure B) with explicit YES (negative GHD) / NO (positive GHD) responses; GHD Description in case of Yes; GHD version
Insurance Parameters	Insurer Id (ID as per Insurer master), Product Id (defined by Insurer), Sum Insured (non mandatory), Deductible (non mandatory), Self / Family Floater, policy term (non mandatory), premium frequency (non mandatory)
Consent	Data-sharing declaration

4.4.aAPI Request parameters

Request parameters

npsRequestId
String 20–36Required
Rules: Alphanumeric and hyphen; unique per quote journey
Request ID: NPS Swasthya transaction reference, generated by NPS Central. Reused on issuance.
requestTimestamp
TimestampRequired
Rules: Not more than 5 minutes in the future
Time stamp of the request
insurerId
String 1–10Required
Rules: As per Insurer master (Annexure B); the insurer rejects a value that is not its own (SWH-1003)
Insurer ID
productId
String 1–20Required
Rules: As registered by the insurer with NPS Central
Product ID
planType
EnumRequired
Rules: SELF / FAMILY_FLOATER
Self / Family
sumInsured
AmountOptional
Rules: > 0; one of the product's options
Sum Insured. If omitted, the insurer returns every eligible option.
deductible
AmountOptional
Rules: > 0; one of the product's options
Deductible. If omitted, the insurer returns every eligible option.
policyTermYears
Integer 1–2Optional
Rules: Filter; if sent, only 1
Policy term in years. If omitted, the insurer returns every eligible term.
premiumFrequency
EnumOptional
Rules: Filter; if sent, only YEARLY
Frequency of premium payment. If omitted, the insurer returns every eligible frequency.
subscriber.name
String 1–270Required
Rules: Name rule (3.4)
Name
subscriber.gender
EnumRequired
Rules: M / F / T
Gender
subscriber.dateOfBirth
DateRequired
Rules: Not in the future
DOB
members
Array 1–nRequired
Rules: SELF: exactly one member, relation SELF. FAMILY_FLOATER: one SELF plus at least one other. Maximum members per product
Persons to be insured; the subscriber is always the member with relation SELF
members[].memberSrNo
Integer 1–2Required
Rules: Unique; SELF = 1, others from 2
Family Sr.
members[].name
String 1–270Required
Rules: Name rule
Member Name
members[].gender
EnumRequired
Rules: M / F / T
Member Gender
members[].dateOfBirth
DateRequired
Rules: Not in the future; within the product's age band
Member DOB
members[].relation
EnumRequired
Rules: SELF, SPOUSE, SON, DAUGHTER
Member relationship
members[].ghdEncrypted
StringRequired
Rules: Compact JWE (3.11) whose plaintext is the GHD object in rows 20–24
Encrypted GHD of the member
ghd.ghdVersion
String 1–10Required
Rules: Inside ghdEncrypted. Version of the GHD master in Annexure B ("1.0")
GHD Version
ghd.responses
Array 15Required
Rules: Inside ghdEncrypted. Exactly one entry for each GHD code 1–15. A missing code is rejected (SWH-1004); it is never read as YES or NO
GHD answers for the member
ghd.responses[].ghdCode
String 1–2Required
Rules: "1"–"15" as per Annexure B
GHD Sr. no.
ghd.responses[].answer
EnumRequired
Rules: YES / NO
GHD Confirmation. YES = condition present (negative GHD); NO = condition absent (positive GHD)
ghd.description
String 1–2000Conditional
Rules: Inside ghdEncrypted. Mandatory when any answer is YES; omitted otherwise
GHD Description: details of the declared conditions for this member
dataSharingDeclaration
FlagRequired
Rules: Only Y
Subscriber's consent to share their and their family's details, including the GHD, with the Insurance Company for a quote

Relation to the base draft

rows 1–7 and 10–24 are the base fields (Request ID, Timestamp, subscriber, family, GHD, Insurer ID, Product ID, Sum Insured, Deductible, Self/Family). The subscriber's mobile number is not sent: it has no bearing on the premium, and a quote can be requested before the subscriber has registered. It is sent on Policy Issuance. Policy term and premium frequency (from the PCRA field specification) are optional filters, like Sum Insured and Deductible. The data-sharing consent is required because personal and health details leave NPS Central at this step. The Good Health Declaration acceptance, declaration text and acceptance timestamp are sent on Policy Issuance, once the subscriber has accepted the quote. The subscriber's own GHD is carried on the SELF member, so GHD answers appear once per insured person. Each member's GHD travels encrypted (3.11).

4.5Response Data

Field	Description
NPS Request ID	NPS Swasthya transaction reference
Quote Id	Unique Insurer Quote Identifier
Insurer Transaction Id	Insurance Company transaction reference
Product Id	Product identifier
Base Premium	Premium before underwriting loading
Loading Amount	Additional premium arising from underwriting/negative GHD
GST	Applicable GST
Final Premium	Total insurance premium payable
Quote Valid Until	Quote validity date/time
Status	SUCCESS / NOT_ELIGIBLE / QUOTE_NOT_AVAILABLE / FAILED, Ineligible Family member sr. no., Reason for Ineligible family member
Error Code / Description	Standard error code and human-readable description where applicable

4.5.aAPI Response parameters

Response parameters

requestId
String 36Required
Rules: Echo of X-Request-Id
Request ID (per call)
npsRequestId
String 20–36Required
Rules: Echo
NPS Request ID
status
EnumRequired
Rules: SUCCESS / NOT_ELIGIBLE / QUOTE_NOT_AVAILABLE / FAILED (4.7)
Status
responseTimestamp
TimestampRequired
Response timestamp
insurerTransactionId
String 1–50Conditional
Rules: Mandatory unless FAILED
Insurance Transaction ID
quotes
Array 0–nConditional
Rules: Mandatory when SUCCESS; one entry per sum insured × deductible option
Premium for each option
quotes[].quoteId
String 1–50Required
Rules: Unique
Quote ID
quotes[].productId
String 1–20Required
Rules: Echo
Product ID
quotes[].sumInsured
AmountRequired
Rules: > 0
Sum insured of this option
quotes[].deductible
AmountRequired
Rules: > 0
Deductible of this option
quotes[].policyTermYears
Integer 1–2Required
Policy term of this option
quotes[].premiumFrequency
EnumRequired
Rules: YEARLY
Premium frequency of this option
quotes[].basePremium
AmountRequired
Rules: > 0
Base premium
quotes[].loadingAmount
AmountRequired
Rules: ≥ 0
Loading Amount
quotes[].gstAmount
AmountRequired
Rules: ≥ 0
GST
quotes[].finalPremium
AmountRequired
Rules: Exactly basePremium + loadingAmount + gstAmount
Final Premium
quotes[].quoteValidUntil
TimestampRequired
Rules: Later than the request time
Quote validity
ineligibleMembers
Array 0–nConditional
Rules: Mandatory when any member is ineligible
Ineligible family members
ineligibleMembers[].memberSrNo
Integer 1–2Required
Rules: As in the request
Ineligible family member sr. no.
ineligibleMembers[].reason
String 1–500Required
Rules: Plain English, suitable to show the subscriber
Reason for ineligible family member

4.5.bError parameters

As per the common error structure (3.7) and catalogue (Annexure A).

4.6Premium Loading

Where the GHD or other underwriting information results in loading, the Insurance Company shall separately identify the base premium, loading amount, GST and final premium. NPS Central shall not independently alter or recalculate the premium returned by the Insurance Company.

4.7Business Rules

The Insurance Company shall apply its approved product pricing and underwriting rules. NPS Central contains no insurer-specific underwriting logic.
A missing GHD parameter shall not be interpreted as a YES or NO response (SWH-1004).
Ages are computed as on the date of the request (requestTimestamp).
Every quote shall have a defined validity period (quoteValidUntil). The insurer states its standard validity period at onboarding.
The insurer shall honour a quote for issuance when the subscriber's payment was completed before quoteValidUntil (payment.paymentTimestamp on the issuance request), even if the issuance request reaches the insurer after that time. Only a payment completed after quoteValidUntil may be refused with SWH-3002.
The insurer shall return a clear non-success status where the product cannot be offered: NOT_ELIGIBLE when no member or option can be offered, QUOTE_NOT_AVAILABLE when the requested option is not available, FAILED when the request could not be processed (errors present).
SUCCESS may be returned with ineligibleMembers where the remaining members are covered. For FAMILY_FLOATER, if the SELF member is ineligible the status is NOT_ELIGIBLE.

4.8Idempotency and Performance

The API supports request tracing as prescribed in the common API standard and is safe to repeat; a repeated call may return new quoteIds. The Insurance Company shall meet the response-time SLA agreed with NPS Central (3.9).

4.9Sample request

CodeJSON

{
  "npsRequestId": "NSW-20261012-000001234",
  "requestTimestamp": "2026-10-12T10:50:00+05:30",
  "insurerId": "INS001",
  "productId": "SWT-TOPUP-01",
  "planType": "FAMILY_FLOATER",
  "subscriber": { "name": "Ravi Kumar", "gender": "M", "dateOfBirth": "1985-08-15" },
  "members": [
    { "memberSrNo": 1, "relation": "SELF", "name": "Ravi Kumar",
      "gender": "M", "dateOfBirth": "1985-08-15",
      "ghdEncrypted": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiaW5zMDAxLWVuYy0xIn0.…" },
    { "memberSrNo": 2, "relation": "SPOUSE", "name": "Lakshmi Kumar",
      "gender": "F", "dateOfBirth": "1988-03-02",
      "ghdEncrypted": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiaW5zMDAxLWVuYy0xIn0.…" }
  ],
  "dataSharingDeclaration": "Y"
}

Plaintext of the SELF member's ghdEncryptedJSON

{ "ghdVersion": "1.0",
  "responses": [ { "ghdCode": "1", "answer": "NO" },
                 { "ghdCode": "2", "answer": "NO" },
                 { "ghdCode": "3", "answer": "YES" },
                 "... one entry for each code up to 15 ..." ],
  "description": "Hypothyroidism, on medication since 2022" }

4.10Sample response

CodeJSON

{
  "requestId": "6f1c2a9e-3b7d-4c1e-9a55-0b2f6f8d1e44",
  "npsRequestId": "NSW-20261012-000001234",
  "status": "SUCCESS",
  "responseTimestamp": "2026-10-12T10:50:02+05:30",
  "insurerTransactionId": "INS-TXN-778812",
  "quotes": [
    { "quoteId": "Q-000981", "productId": "SWT-TOPUP-01",
      "sumInsured": "500000.00", "deductible": "300000.00",
      "policyTermYears": 1, "premiumFrequency": "YEARLY",
      "basePremium": "4200.00", "loadingAmount": "420.00",
      "gstAmount": "0.00", "finalPremium": "4620.00",
      "quoteValidUntil": "2026-10-19T23:59:59+05:30" }
  ]
}

Part II – Policy Issuance API

5NPS Swasthya – Policy Issuance API Standard

5.1Purpose

The Policy Issuance API shall enable NPS Central to transmit verified subscriber and insured-member information to the selected Insurance Company for issuance of the insurance policy. The API shall be invoked after successful completion of subscriber onboarding in NPS Swasthya, which includes acceptance of premium, KYC, successful premium payment and PRAN generation.

5.2System of Record

The Insurance Company shall be the system of record for the insurance policy. NPS Central shall not maintain a duplicate policy master. NPS Central may retain transaction/reference information required for audit, reconciliation and system integration (1.2).

5.3API Definition and issuance model

POST/api/v1/nps-swasthya/policy/issuePolicy Issuance API

Direction: NPS Central → Insurance Company
Idempotency: Mandatory, on npsRequestId (3.6). Idempotency-Key header = npsRequestId

Issuance uses one pattern for every insurer:

Every accepted issuance request receives an issuanceRefId (the insurer's acknowledgement / proposal ID).
If the insurer can issue immediately, it returns status ISSUED with the policy number and dates in the same response.
Otherwise it returns RECEIVED or PROCESSING, and NPS Central polls the Policy Issuance Status API (5.7) with the issuanceRefId until the status is ISSUED or REJECTED.
The insurer may also call the Issuance Callback (5.9) to notify a status change; NPS Central then calls the Status API. Polling remains the source of truth.

5.4Request Data

Data Group	Fields
Transaction	Request Id (generated for premium calculation), Time stamp, PRAN
Subscriber	Name, DOB, Gender, Mobile, Email, Address, City, State, Pincode, nominee sr. no., nominee name, nominee relationship, nominee age, KYC source and KYC reference
Family	Sr. no. of family member, Name, DOB, Gender, Relationship with the Subscriber
GHD	GHD 1–15 with explicit YES / NO responses; GHD Description in case of Yes; GHD version; Declaration timestamp; Consent flag
Selected Insurance	Insurer Id, Product Id, Quote Id, Sum Insured, Deductible, Base Premium, Loading Amount, GST, Final Premium, Self / Family
Payment	Premium paid amount, Payment Date, Payment Status, payment reference

5.4.aAPI Request parameters

Request parameters

npsRequestId
String 20–36Required
Rules: Same value as on the Premium Calculation; equals the Idempotency-Key header
Request ID
requestTimestamp
TimestampRequired
Rules: Not more than 5 minutes in the future
Time stamp of the request
pran
String 12Required
Rules: PRAN rule (3.4)
PRAN
subscriber.name
String 1–270Required
Rules: Name rule
Name
subscriber.gender
EnumRequired
Rules: M / F / T
Gender
subscriber.dateOfBirth
DateRequired
Rules: Equal to the SELF member's date of birth
DOB
subscriber.mobileNumber
String 10Required
Rules: Mobile rule
Mobile No.
subscriber.email
String 5–100Optional
Rules: Valid email address
Email
subscriber.address.line1
String 1–100Required
Address
subscriber.address.line2
String 1–100Optional
Address
subscriber.address.line3
String 1–100Optional
Address
subscriber.address.city
String 1–50Required
City
subscriber.address.stateCode
String 2Required
Rules: State code list (Annexure B)
State
subscriber.address.pincode
String 6Required
Rules: Pincode rule
Pin Code
nominees
Array 1–nRequired
Rules: Maximum number of nominees
Nominee(s)
nominees[].nomineeSrNo
Integer 1Required
Rules: Unique, from 1
Nominee Sr. No.
nominees[].name
String 1–270Required
Rules: Name rule
Nominee name
nominees[].age
Integer 1–3Required
Rules: 0–120
Nominee Age
nominees[].relation
EnumRequired
Rules: Nominee relation list (Annexure B)
Nominee Relationship
kyc.kycSource
EnumRequired
Rules: CKYC / AADHAAR_DIGILOCKER
KYC source
kyc.kycReferenceNo
String 4–14Required
Rules: CKYC: the 14-digit CKYC number. AADHAAR_DIGILOCKER: last 4 digits of Aadhaar (the full number is never sent)
KYC reference no.
members
Array 1–nRequired
Rules: Same structure, sr. no. and GHD as the Premium Calculation request (4.4.a rows 13–24), for the members covered by the accepted quote
Family members with their GHD
declarations.goodHealthDeclaration
FlagRequired
Rules: Only Y
Subscriber confirms the GHD answers are true and complete
declarations.dataSharingDeclaration
FlagRequired
Rules: Only Y
Consent flag
declarations.declarationText
String 1–5000Required
Rules: Exactly as displayed to the subscriber
Declaration content shown during onboarding
declarations.acceptedAt
TimestampRequired
Rules: Not in the future
Declaration timestamp
insurerId
String 1–10Required
Rules: As per Insurer master; must be this insurer
Insurer ID
productId
String 1–20Required
Rules: Must match the quote
Product ID
quoteId
String 1–50Required
Rules: From the Premium Calculation response; honoured per 4.7
Quote ID
insurerTransactionId
String 1–50Required
Rules: From the Premium Calculation response
Insurer transaction ID of the quote
planType
EnumRequired
Rules: SELF / FAMILY_FLOATER; must match the quote
Self/Family
sumInsured
AmountRequired
Rules: Must match the quote
Sum Assured
deductible
AmountRequired
Rules: Must match the quote
Deductible
basePremium
AmountRequired
Rules: Must match the quote
Base Premium
loadingAmount
AmountRequired
Rules: Must match the quote
Loading Amount
gstAmount
AmountRequired
Rules: Must match the quote
GST
finalPremium
AmountRequired
Rules: Must match the quote
Final Premium Amount
payment.premiumPaidAmount
AmountRequired
Rules: = finalPremium
Premium Paid amount
payment.paymentTimestamp
TimestampRequired
Rules: Not in the future; the time the payment gateway confirmed the payment
Payment Date and time; decides whether the quote is honoured (4.7)
payment.paymentStatus
EnumRequired
Rules: Only SUCCESS
Payment Status
payment.paymentReference
String 1–50Required
Rules: Unique per payment
NPS Central payment reference, quoted on premium remittance and reconciliation

5.5Acknowledgement Response

Field	Description
NPS Request ID	NPS Request ID generated by NPS Central
Insurer Transaction Id	Insurer transaction ID generated by the insurer against the NPS request ID
Quote ID	Quote ID as per premium calculation
Issuance Ref ID	Insurer acknowledgement of the issuance request; used to poll the status
Policy details	Policy no., Policy RSD, Policy RED, GWP (when issued)
Status	RECEIVED / PROCESSING / ISSUED / REJECTED / FAILED
Time stamp	Response timestamp

5.5.aAPI Response parameters (Issuance and Issuance Status)

Response parameters (Issuance and Issuance Status)

requestId
String 36Required
Rules: Echo of X-Request-Id
Request ID (per call)
npsRequestId
String 20–36Required
Rules: Echo
NPS Request ID
insurerTransactionId
String 1–50Conditional
Rules: Not on FAILED / NOT_FOUND
Insurance transaction ID
quoteId
String 1–50Conditional
Rules: Not on FAILED / NOT_FOUND
Quote ID
issuanceRefId
String 1–50Conditional
Rules: Mandatory except on FAILED / NOT_FOUND; same value on every response for this npsRequestId
Issuance acknowledgement ID
status
EnumRequired
Rules: RECEIVED / PROCESSING / ISSUED / REJECTED / FAILED; NOT_FOUND on the Status API only (5.6)
Status
policyNumber
String 1–50Conditional
Rules: Mandatory when ISSUED
Policy No.
policyStartDate
DateConditional
Rules: Mandatory when ISSUED
Policy RSD (risk start date)
policyEndDate
DateConditional
Rules: Mandatory when ISSUED; after the start date
Policy RED (risk end date)
grossWrittenPremium
AmountConditional
Rules: Mandatory when ISSUED
GWP
rejectionReasonCode
EnumConditional
Rules: Mandatory when REJECTED; rejection reason list (Annexure B)
Rejection reason code
rejectionReason
String 1–500Conditional
Rules: Mandatory when REJECTED; plain English, suitable to show the subscriber
Reason the policy will not be issued
responseTimestamp
TimestampRequired
Response Timestamp

5.5.bError parameters

As per the common error structure (3.7) and catalogue (Annexure A).

5.6Issuance status values

Status	Final?	Meaning and NPS Central action
RECEIVED	No	Accepted; issuanceRefId assigned. NPS Central polls.
PROCESSING	No	Underwriting / issuance in progress. NPS Central polls.
ISSUED	Yes	Policy issued; policy number and dates present.
REJECTED	Yes	The insurer will not issue; rejectionReasonCode and rejectionReason present. Handled as in 5.6.a.
FAILED	No	Request not accepted because of a validation or technical problem (errors present); no issuanceRefId.
NOT_FOUND	No	Status API only: the insurer holds no issuance for this npsRequestId. NPS Central may safely resend the issuance request.

5.6.aRejection handling

REJECTED is final for the npsRequestId. A repeat of the issuance request with the same npsRequestId, and every Issuance Status call for it, returns the same REJECTED response. The insurer never issues a policy later for that npsRequestId.
The insurer creates no policy, member or premium record that would block a later request for the same subscriber.
Any further attempt for the subscriber starts again from Premium Calculation with a new npsRequestId, and is issued against the new quote.
NPS Central acts on rejectionReasonCode, never on the text: it informs the subscriber with rejectionReason and handles the premium already collected under its business process (Annexure D).
REJECTED (an underwriting or business decision on a valid request) is distinct from FAILED (the request was not accepted, and may be corrected and resent with the same npsRequestId, 3.6).

5.7Policy Issuance Status API

Used by NPS Central to obtain the current state of an issuance it has sent. Mandatory for every Insurance Company. The response is the structure of 5.5.a.

POST/api/v1/nps-swasthya/policy/issuance-statusPolicy Issuance Status API

Direction: NPS Central → Insurance Company

5.7.aAPI Request parameters

Request parameters

npsRequestId
String 20–36Required
NPS Request ID
issuanceRefId
String 1–50Conditional
Rules: Mandatory when NPS Central has received one; omitted when the issuance call's outcome is unknown (e.g. timeout)
Issuance acknowledgement ID
pran
String 12Required
Rules: Must match the issuance request, otherwise NOT_FOUND
PRAN

5.8Failure and Retry

A successful payment followed by temporary unavailability of the Insurance Company API shall not be treated as payment failure. Policy issuance shall remain pending and the transaction shall be retried/reconciled as below. The insurer shall support idempotent issuance requests (3.6).

Situation	Rule
Issuance call times out, returns 5xx, or the connection fails	Outcome unknown. NPS Central calls the Status API with npsRequestId. It never treats this as a rejection.
Status API returns NOT_FOUND	The request never reached the insurer. NPS Central resends the issuance request with the same npsRequestId and body.
RECEIVED / PROCESSING	NPS Central polls at 1, 5, 15 and 30 minutes and then hourly up to 24 hours; thereafter the case goes to manual reconciliation with the insurer.
ISSUED or REJECTED	Final. NPS Central stops polling. A REJECTED outcome is handled as in 5.6.a.
Signature on a response does not verify (3.10)	Treated as outcome unknown; NPS Central calls the Status API.
FAILED	NPS Central retries only if the error code is retryable (Annexure A); otherwise the case goes to operations.
Insurer obligation	Reach a final status within 30 minutes of acknowledgement in normal operation, and in no case later than T+1 working day.

5.9Callback / Webhook (optional)

The Insurance Company may notify NPS Central when an issuance reaches a new status. On receipt NPS Central calls the Status API (5.7) and uses that response as the result, so the callback carries identifiers and status only.

Endpoint: POST {npsCentralCallbackUrl}, provided to each insurer at onboarding (base draft: /api/v1/nps-swasthya/policy/issuance-callback)
Direction: Insurance Company → NPS Central
Authentication: As 3.2, in the reverse direction, with the JWS signature (3.10) and IP allow-listing. mTLS is not used on the callback in this version (3.1).
Response: HTTP 200 with status ACKNOWLEDGED, including for duplicates

5.9.aCallback request parameters

Callback request parameters

npsRequestId
String 20–36Required
NPS Request ID
insurerTransactionId
String 1–50Required
Insurer transaction ID
issuanceRefId
String 1–50Required
Issuance acknowledgement ID (proposal ID in the base draft)
status
EnumRequired
Rules: PROCESSING / ISSUED / REJECTED
New status
eventTimestamp
TimestampRequired
Rules: Not in the future
Timestamp

5.10Policy Issuance Result

On successful issuance, the Insurance Company shall make the following information available through the Policy Details and Policy Document APIs (Part III): policy number / certificate number, product ID and name, policy start and end dates, sum insured, deductible, premium and loading, insured member details, policy document, e-card, premium receipt and invoice where applicable, and policy terms and conditions.

5.11Sample responses

Acknowledged, to be polledJSON

{
  "requestId": "a3e9c1d0-5b2e-4f8a-9d61-2c7a1e4b9f03",
  "npsRequestId": "NSW-20261012-000001234",
  "insurerTransactionId": "INS-TXN-778812",
  "quoteId": "Q-000981",
  "issuanceRefId": "ISR-20261012-55821",
  "status": "RECEIVED",
  "responseTimestamp": "2026-10-12T11:05:04+05:30"
}

Issued (synchronously, or on a later Status API call)JSON

{
  "requestId": "0b7d22f4-8a1c-4e55-b3a9-6f2d90c1e7aa",
  "npsRequestId": "NSW-20261012-000001234",
  "insurerTransactionId": "INS-TXN-778812",
  "quoteId": "Q-000981",
  "issuanceRefId": "ISR-20261012-55821",
  "status": "ISSUED",
  "policyNumber": "SWT/2026/0000451",
  "policyStartDate": "2026-10-13",
  "policyEndDate": "2027-10-12",
  "grossWrittenPremium": "4620.00",
  "responseTimestamp": "2026-10-12T11:12:40+05:30"
}

Part III – Policy Information Retrieval & Display API

6NPS Swasthya – Policy Information Retrieval & Display API Standard

6.1Purpose

This API shall enable an authenticated subscriber using NPS Central to view the insurance policy issued under NPS Swasthya directly from the Insurance Company's system. It is used from the subscriber dashboard (for example with the policy number entered by the subscriber) and, where the policy is already available, from the onboarding confirmation step.

6.2Source of Truth

The Insurance Company shall remain the authoritative source of policy information. NPS Central shall retrieve and display the information when requested and shall not modify or maintain a duplicate policy master.

6.3API Definition

POST/api/v1/nps-swasthya/policy/detailsGet Policy Details API

Direction: NPS Central → Insurance Company
Why POST: The base draft proposed GET /policy/{policyNumber}. The identifiers include PRAN, mobile number and date of birth, which must not appear in URLs or access logs (3.1), so they travel in the request body.

6.4Request

The request identifies the subscriber, and optionally the policy, using the identifiers in the base draft:

Subscriber (mandatory): PRAN, or Mobile No. + DOB. Either form, or both.
Policy (optional, at most one): Policy No., Quote ID, Insurer Transaction ID, NPS Request ID or Issuance Ref ID.
With a policy identifier, the insurer returns that policy if it belongs to the subscriber. Without one, the insurer returns every NPS Swasthya policy of the subscriber.

6.4.bMultiple, unavailable and pending policies

Situation	Rule
Several policies for the subscriber (no policy identifier sent)	All are returned, whatever their status, ordered by policyStartDate, latest first. NPS Central shows the ACTIVE policy first and the others as history.
A policy identifier sent	Exactly one policy is returned, or an error; never a list of more than one.
Issuance accepted but not yet final (RECEIVED / PROCESSING)	HTTP 404, SWH-3008 Policy not yet issued. NPS Central shows the policy as being issued and retries later.
Issuance REJECTED, no policy, or not this subscriber's policy	HTTP 404, SWH-3006, with identical content in every case (ownership rule below).
Insurer system unavailable	HTTP 503, SWH-5002, with a Retry-After header where known. Handled as in 6.8.

6.4.aAPI Request parameters

Request parameters

pran
String 12Conditional
Rules: PRAN rule. Mandatory unless mobileNumber + dateOfBirth are sent
PRAN
mobileNumber
String 10Conditional
Rules: Mobile rule. Only together with dateOfBirth
Mobile No.
dateOfBirth
DateConditional
Rules: Only together with mobileNumber
DOB
policyNumber
String 1–50Optional
Rules: At most one policy identifier
Policy No.
quoteId
String 1–50Optional
Rules: At most one policy identifier
Quote ID
insurerTransactionId
String 1–50Optional
Rules: At most one policy identifier
Insurer Transaction ID
npsRequestId
String 20–36Optional
Rules: At most one policy identifier
Request ID
issuanceRefId
String 1–50Optional
Rules: At most one policy identifier
Issuance acknowledgement ID

Ownership rule: the subscriber identifiers are matched against the policyholder as registered at issuance. If a policy identifier resolves to a policy of another subscriber, the insurer answers exactly as for a policy that does not exist (HTTP 404, SWH-3006), so valid policy numbers cannot be discovered.

6.5Response

Data Group	Fields
Policy	Policy Number, Policy Status, Insurer, Product Id, Product Name, Policy Start Date, Policy End Date, Sum Insured, Deductible, Premium, Loading, GST
Insured Members	Insured member name, relationship, DOB and gender for each insured member, member status
Documents	Policy document, e-card, certificate, premium receipt, invoice, policy terms and conditions
Transaction	Insurer Transaction Id, last updated timestamp

6.5.aAPI Response parameters

Response parameters

requestId
String 36Required
Rules: Echo of X-Request-Id
Request ID (per call)
status
EnumRequired
Rules: SUCCESS / FAILED
Outcome
responseTimestamp
TimestampRequired
Response timestamp
policies
Array 1–nConditional
Rules: Mandatory on SUCCESS; one entry when a policy identifier was sent
Policies found
policies[].pran
String 12Required
PRAN
policies[].mobileNumber
String 10Required
Mobile No.
policies[].dateOfBirth
DateRequired
DOB
policies[].quoteId
String 1–50Required
Quote ID
policies[].insurerTransactionId
String 1–50Required
Insurer Transaction ID
policies[].npsRequestId
String 20–36Required
Request ID
policies[].policyNumber
String 1–50Required
Policy No.
policies[].policyStatus
EnumRequired
Rules: Policy status list (6.7)
Policy Status
policies[].insurerId
String 1–10Required
Rules: Insurer master
Insurer ID
policies[].productId
String 1–20Required
Product ID
policies[].productName
String 1–150Required
Product Name
policies[].policyStartDate
DateRequired
Policy Start Date
policies[].policyEndDate
DateRequired
Policy End Date
policies[].sumInsured
AmountRequired
Sum Assured
policies[].deductible
AmountRequired
Deductible
policies[].basePremium
AmountRequired
Base Premium
policies[].loadingAmount
AmountRequired
Loading Amount
policies[].gstAmount
AmountRequired
GST
policies[].finalPremium
AmountRequired
Final Premium Amount
policies[].premiumPaidAmount
AmountRequired
Premium Paid amount
policies[].paymentTimestamp
TimestampRequired
Rules: As on the issuance request
Payment Date
policies[].planType
EnumRequired
Rules: SELF / FAMILY_FLOATER
Self/Family
policies[].members
Array 1–nRequired
Insured family members
policies[].members[].memberSrNo
Integer 1–2Required
Rules: As on the issuance request
Insured Family Sr.
policies[].members[].name
String 1–270Required
Member Name
policies[].members[].gender
EnumRequired
Rules: M / F / T
Member Gender
policies[].members[].dateOfBirth
DateRequired
Member DOB
policies[].members[].relation
EnumRequired
Member relationship
policies[].members[].memberStatus
EnumRequired
Rules: ACTIVE / INACTIVE
Member Status
policies[].documents
Array 0–nRequired
Rules: One entry per document type the policy has
Policy document, e-card, premium receipt, invoice, policy terms and conditions
policies[].documents[].documentType
EnumRequired
Rules: Document type list (Annexure B)
Type of document
policies[].documents[].documentId
String 1–100Required
Rules: Opaque; used with the Policy Document API (6.6)
Document reference
policies[].documents[].documentVersion
Integer 1–3Required
Rules: Starts at 1; increases on every revision
Version of the document
policies[].documents[].issuedAt
TimestampConditional
Rules: Mandatory when available = Y
When this version was generated
policies[].documents[].available
FlagRequired
Rules: Y / N
Y when ready to download now
policies[].lastUpdatedTimestamp
TimestampRequired
Last update timestamp

6.5.bError parameters

As per the common error structure (3.7) and catalogue (Annexure A).

6.6Document Retrieval

Policy documents and e-cards shall be made available through a secure authenticated mechanism. Publicly accessible unrestricted document URLs shall not be used. The mechanism is the API below; a document is requested only when Policy Details reports it with available = Y.

Limits, timeouts and revised documents

Item	Rule
Format and size	PDF only; maximum 5 MB per document after decoding. A larger document is not sent through this API (SWH-3011); the insurer splits or compresses it.
Timeout	NPS Central waits up to 20 seconds (3.9). A timeout is shown to the subscriber as "please try again", never as "document not available".
Request limits	NPS Central allows a subscriber at most 10 downloads per document per hour. The insurer may apply its own limit, returning HTTP 429, SWH-4001 with Retry-After.
Not yet generated	available = N in Policy Details; a request returns HTTP 404, SWH-3007, retry later.
Revised documents	A revised document (e.g. after a correction or endorsement) gets a new documentId and the next documentVersion. Policy Details lists only the current version of each document type. A request for a superseded documentId returns HTTP 410, SWH-3010; NPS Central fetches Policy Details again for the current documentId.
Integrity	NPS Central verifies checksumSha256 and sizeBytes before offering the file to the subscriber.

POST/api/v1/nps-swasthya/policy/documentGet Policy Document API

Direction: NPS Central → Insurance Company
Delivery: PDF as Base64 inside the JSON response; maximum 5 MB per document (see limits above)

6.6.aRequest parameters

Request parameters

pran
String 12Conditional
Rules: Subscriber identification as in 6.4
PRAN
mobileNumber
String 10Conditional
Rules: Subscriber identification as in 6.4
Mobile No.
dateOfBirth
DateConditional
Rules: Subscriber identification as in 6.4
DOB
policyNumber
String 1–50Required
Policy No.
documentId
String 1–100Required
Rules: From Policy Details
Document reference

6.6.bResponse parameters

Response parameters

requestId
String 36Required
Rules: Echo of X-Request-Id
Request ID (per call)
status
EnumRequired
Rules: SUCCESS / FAILED
Outcome
responseTimestamp
TimestampRequired
Response timestamp
documentId
String 1–100Required
Rules: Echo
Document reference
documentType
EnumRequired
Rules: Annexure B
Type of document
fileName
String 1–150Required
Rules: Ends in .pdf
Suggested file name
mimeType
StringRequired
Rules: Only application/pdf
File type
documentVersion
Integer 1–3Required
Rules: As in Policy Details
Version of the document
sizeBytes
IntegerRequired
Rules: ≤ 5,242,880
Size of the decoded file
contentBase64
StringRequired
Rules: Base64 of the file
Document content
checksumSha256
String 64Required
Rules: Lower-case hex SHA-256 of the decoded file
Integrity check

6.7Policy Status

The insurer shall provide the current status, including as applicable: ACTIVE, EXPIRED, CANCELLED, PENDING, SUSPENDED.

6.8API Failure

An API failure or timeout shall not be interpreted by NPS Central as policy expiry, cancellation or rejection. NPS Central shall display an appropriate service-unavailable message and the subscriber may retry. During planned maintenance the insurer returns HTTP 503, SWH-5002 with Retry-After; NPS Central does not cache policy data to cover an outage (6.9).

6.9Data Synchronisation Principle

Because the Insurance Company is the system of record, the next successful retrieval shall return the latest policy information. NPS Central shall not be responsible for maintaining a parallel policy master.

6.10Sample requests

Dashboard: policy number entered by the subscriberJSON

{ "pran": "110012345678", "policyNumber": "SWT/2026/0000451" }

Onboarding confirmationJSON

{ "pran": "110012345678", "npsRequestId": "NSW-20261012-000001234" }

All policies of a subscriberJSON

{ "mobileNumber": "9876543210", "dateOfBirth": "1985-08-15" }

Annexures

AStandard Error Catalogue

Insurers map their native errors to these codes. The native code may be sent in errors[].insurerErrorCode for support. "Retry" states what NPS Central does.

24 rows

Code	HTTP	Meaning	Typical cause	Retry?
SWH-1001	400	Mandatory field missing	A field marked M is absent	No – fix request
SWH-1002	400	Invalid format or length	Bad date, amount, length or pattern	No
SWH-1003	400	Value not in master	Unknown insurerId, productId, relation or GHD code	No
SWH-1004	400	GHD incomplete	A GHD code missing, or YES without description	No
SWH-1005	422	Business rule failed	Amounts do not add up, member count or age outside product rules	No
SWH-2001	401	Authentication failed	Missing or expired token, invalid client assertion	Yes – once, with a new token
SWH-2002	403	Not authorised	Client not permitted for this API or environment	No
SWH-2004	400	Signature invalid	X-JWS-Signature missing, stale or not verifiable (3.10)	No – check keys
SWH-2005	400	GHD cannot be decrypted	ghdEncrypted not decryptable or not a valid GHD object (3.11)	No – check keys
SWH-3001	404	Quote not found	Unknown quoteId or insurerTransactionId	No
SWH-3002	410	Quote expired	Payment completed after quoteValidUntil (4.7)	No – recalculate
SWH-3003	409	Amount mismatch	Issuance amounts differ from the quote	No
SWH-3004	409	Idempotency conflict	Same npsRequestId, different body	No
SWH-3005	422	Member set mismatch	Members differ from those quoted	No
SWH-3006	404	Policy not found	No policy for the identifiers, or not this subscriber's policy	No
SWH-3007	404	Document not yet available	Document not generated yet	Yes – later
SWH-3008	404	Policy not yet issued	Issuance RECEIVED / PROCESSING	Yes – later
SWH-3009	422	Product not available	Product closed or not offered	No
SWH-3010	410	Document superseded	A newer version of the document exists	No – fetch Policy Details
SWH-3011	413	Document too large	Decoded file exceeds 5 MB	No
SWH-4001	429	Rate limit exceeded	Too many calls	Yes – after Retry-After
SWH-5001	500	Provider internal error	Unhandled error	Yes – with backoff
SWH-5002	503	Service unavailable	Maintenance or outage	Yes – with backoff
SWH-5003	504	Downstream timeout	Insurer core system timeout	Yes – with backoff

BCode Lists and Masters

GHD codes (version 1.0)

The same fifteen Good Health Declaration items used in NPS Swasthya subscriber registration today. An insurer that needs a different question set raises it with NPS Central; a new version is then published here.

15 rows

Code	Condition
1	Heart attack
2	Stroke or cerebrovascular disease
3	Thyroid or kidney disease
4	Liver or pancreatic disease
5	Lung disease
6	Blood or gastrointestinal disorder
7	Bone, spine or muscle disorder
8	Cancer or tumour
9	Autoimmune or neurological disorder
10	HIV / AIDS
11	Sudden weight loss
12	Head injury
13	Major burns
14	Type 1 diabetes or on insulin
15	Severe asthma

Condition names above are summaries; the declaration wording shown to the subscriber is the registered master text.

Other code lists

14 rows

Code list	Values	Owner
Insurer (insurerId)	Assigned by NPS Central to each onboarded insurer, e.g. INS001	NPS Central
Product (productId)	Defined by each insurer and registered with NPS Central	Insurer
Plan type	SELF, FAMILY_FLOATER	NPS Central
Gender	M, F, T	NPS Central
Member relation	SELF, SPOUSE, SON, DAUGHTER	NPS Central
Nominee relation	SPOUSE, SON, DAUGHTER, FATHER, MOTHER, BROTHER, SISTER, OTHER	NPS Central
GHD answer	YES (condition present – negative GHD), NO (condition absent – positive GHD)	NPS Central
KYC source	CKYC, AADHAAR_DIGILOCKER	NPS Central
Premium frequency	YEARLY	NPS Central
Document type	POLICY_DOCUMENT, E_CARD, CERTIFICATE, PREMIUM_RECEIPT, INVOICE, TERMS_AND_CONDITIONS	NPS Central
State code	Two-letter state / UT codes of ISO 3166-2:IN (e.g. TN, MH, DL)	NPS Central
Rejection reason	UNDERWRITING_DECLINE, DUPLICATE_POLICY (subscriber already holds an active NPS Swasthya policy), KYC_MISMATCH, MEMBER_INELIGIBLE, PRODUCT_WITHDRAWN, OTHER (insurer to confirm the list)	NPS Central / Insurer
Policy status	ACTIVE, PENDING, EXPIRED, CANCELLED, SUSPENDED	NPS Central
Member status	ACTIVE, INACTIVE	NPS Central

CWhat NPS Central Expects from Each Insurance Company

To be supplied before UAT, and confirmed before production go-live:

Base URLs for UAT and Production, with all paths exactly as in this document.
OAuth client_id for NPS Central per environment, with NPS Central's public key registered against it (3.2).
Egress IP ranges for callbacks, and confirmation of NPS Central IP allow-listing.
The certificate authority the insurer's gateway trusts for NPS Central's mTLS client certificate (or the process to have it issued), per environment (3.1).
JWS signing public key (JWKS) and acceptance of NPS Central's signing key (3.10).
JWE encryption public key (JWKS) for GHD data (3.11).
Confirmation of the rejection reason codes (Annexure B).
Product master: productId, name, plan types, sum insured and deductible options, age bands, maximum members.
Confirmation that the GHD codes in Annexure B are sufficient for underwriting.
Mapping of native errors to Annexure A.
Standard quote validity period, and the maximum time to a final issuance status (5.8).
Document types provided, and when each becomes available after issuance.
Confirmation of the SLA values in 3.9 and the support / escalation matrix.
Whether the Issuance Callback (5.9) will be implemented.
A UAT environment able to produce every status in 5.6 and every error in Annexure A.
Format of the daily premium reconciliation report.

DOpen Items

#	Item	Owner
1	Scope of JWE encryption: GHD data only (as in 3.11), or complete request and response payloads.	PFRDA
2	Insurer rejects issuance after payment and PRAN generation: refund of premium and treatment of other charges.	PFRDA / NPS Central business / Insurers
3	Whether the insurer may rely on the KYC done at NPS Central.	Insurers / Compliance
4	Nominee details: maximum nominees, share percentage, appointee for a minor nominee.	Insurers
5	Whether premium varies by location (pincode); if so a field is added to the Premium Calculation request.	Insurers
6	Permitted relations beyond SELF, SPOUSE, SON, DAUGHTER, and maximum members on a family floater.	Product / Insurers
7	Log and audit retention period.	Compliance
8	Mutual TLS on the NPS Central-hosted Issuance Callback: planned for a later version.	NPS Central

EChange Log

Version	Date	Changes
1.0 draft	10-Oct-2026	Base draft with PCRA field specification.
1.0 draft 2	12-Oct-2026	Field specifications, authentication, data conventions, errors, SLAs and samples completed. Issuance Status API and issuanceRefId added; callback reduced to a notification. Retrieval moved to POST with a subscriber check on every policy identifier. Policy Document API added.
1.0 draft 3	14-Oct-2026	PFRDA IT feedback: mutual TLS made mandatory on insurer-hosted APIs; JWS signing of issuance, status and callback messages; JWE encryption of GHD data; paymentDate replaced by paymentTimestamp and quotes paid before expiry honoured; rejection handling and reason codes; multiple, pending and unavailable policies; document limits, timeouts and revised documents.