Modifications – Changing an existing subscriber's details

In field tables, the presence column shows M for mandatory, O for optional, and C for conditional — mandatory only in the situation the description gives. Money means a decimal string with exactly two places, such as "5000.00".

A person-level change has one value for the subscriber, such as their mobile number. It is all-or-nothing: if any account cannot take it, the whole request is refused. On a session narrowed with pop that left any account out, person-level changes are refused with 422 MODIFICATION_NEEDS_EVERY_ACCOUNT.

Account- and tier-level changes (bank, nominee, Tier II) can go to some accounts and not others. Where some accounts cannot take such a change, the request may be held until the subscriber agrees to go ahead without them (section 7); the status resource reports which policy applied in admissionPolicy.

Some changes may be made only a limited number of times in a financial year, counted across all of the subscriber's accounts. A request over the limit is refused with 409 CHANGE_FREQUENCY_EXHAUSTED; the error carries limit, used, period (for example FY2026-27) and resetsOn, so you can tell the subscriber when they can try again.

CONTACT_UPDATE, BANK_UPDATE and TIER2_ACTIVATION each need an OTP that you send and the subscriber answers immediately before you file the change. status must be VERIFIED and verifiedAt the time the subscriber answered, no more than 5 minutes before the request reaches NPS Central. Anything else is refused with 422 PARTNER_VERIFICATION_REQUIRED.

Where a change requires a verification — a penny drop, an OTP to a new mobile number, an address taken from CKYC — you carry it out and state the result in the request. NPS Central records that statement against your partner account. Keep the evidence on your side; verification.evidenceRef lets you record your own reference for it.

Generate a new Idempotency-Key (up to 128 characters, e.g. a UUID) for each change the subscriber makes. If a request times out or you are unsure whether it arrived, resend it with the same key and the same body; you will get the original response rather than a second request. After a validation error, correct the body and submit with a new key.

{
  "referenceId": "ref_01JA6Z3KQ8M4N7P2R5S9T1V0X7",
  "type": "MODIFICATION",
  "statusUrl": "/api/v1/modification-requests/ref_01JA6Z3KQ8M4N7P2R5S9T1V0X7",
  "acceptedAt": "2026-10-09T10:42:00.000Z",
  "estimatedCompletion": "2026-10-09T10:47:00.000Z"
}

referenceId is the only identifier you need to follow, acknowledge or cancel the request; store it against the subscriber's change in your system. A warnings[] array (code, field, message) is included when a CRA cannot carry a field you sent: the request is still accepted and the value kept in the NPS Central record.

A nominee list holds one to three nominees and always replaces the current list for that tier. Send every nominee, not only the one that changed. Each has ordinal (1–3), name, relationship, age, isMinor, sharePercentage (shares in a tier total 100), and guardian when isMinor is true.

Send only what is changing, and at least one field: mobile, email, landline, smsAlerts, emailAlerts.

{
  "type": "CONTACT_UPDATE",
  "subjectId": "sub_01JA6Z3KQ8M4N7P2R5S9T1V0WZ",
  "scope": { "mode": "ALL_LINKED" },
  "payload": { "mobile": "+919812300000", "email": "ananya.new@example.com" },
  "verification": { "method": "OTP_NEW_CHANNEL", "status": "VERIFIED",
    "verifiedAt": "2026-10-09T10:41:00.000Z" }
}