Skip to content

Subject APIs

A subject is a client of the bank known to LightCMS — a cardholder or a card owner (owner of the card account). These can be different subjects: e.g. a parent owns the account and a child holds a card issued to it. A cardholder is always a person; a card owner can be a person or a company.

LightCMS is not the master of subject data. The subject is mastered by the external system (typically CRM). LightCMS keeps a copy of the subject data it needs for issuing and managing cards, and passes them on to the card processor. The subject APIs are about keeping this copy up to date.

Call Direction API contract Purpose
POST /v3/subjectUpdate External system → LightCMS Provided External system reports a change of subject data
GET /v3/subject/{subjectExternalId} LightCMS → External system Required LightCMS reads the current subject data from the External system
POST /v3/subjectUpdateResult LightCMS → External system Required LightCMS asks the external system to resend an update it could not process

How a subject gets into LightCMS

There is no separate API to create a subject. A subject becomes known to LightCMS when the first card linked to it is created (see Card creation) — the card creation request carries the cardholder and the account owner. Right after that, LightCMS reads the current data of the subject from the CBS (GET /v3/subject/{subjectExternalId}), so from the very beginning the subject data in LightCMS are those of the master.

A subject is identified by its external ID — the ID the master external system knows the client under. When a further card is issued to a subject that already exists in LightCMS, the existing subject is used and its data are not changed by the card creation request.

An update of a subject that is not linked to any card is of no interest to LightCMS and is ignored.

Keeping the subject up to date

Whenever the data of a subject change in the external system — e.g. the client moves, changes the phone number or the e-mail, or the name changes — the external system should report it via POST /v3/subjectUpdate.

  • The update always carries the complete current data of the subject, not just the change. Data that are not sent are treated as no longer valid — e.g. an update without a mailing address removes the mailing address the subject had.
  • LightCMS passes the updated data on to the card processor, so the card processor always works with the current data of the subject.
  • Both persons and companies can be updated. The update states the type of the subject and carries the data relevant for it — a person is described by its name and birth date, a company by its name and business ID (IČO).
  • The type of a subject (person or company) cannot be changed by an update — a person cannot become a company or vice versa.
  • A 2xx response means LightCMS has accepted the update. If LightCMS later fails to process it, it calls POST /v3/subjectUpdateResult with status: NOT_PROCESSED and the x-idempotency-key of the update — the external system should then resend the update.

Why the data matter

The subject data are used in the life of the card, e.g.:

  • the holder's name to identify the cardholder towards the card processor,
  • the addresses for delivering card plastics by post,
  • the contact details (phone number, e-mail) passed on to the card processor.

Outdated subject data may therefore lead e.g. to undelivered cards — reporting every change promptly is in the interest of both the bank and the client.