Recipients

Subjects: creating them idempotently, finding them, and what deleting one means.

The people credentials are about are subjects, and they are keyed by your own externalId rather than by an identifier we invent. That is the whole reason a sync can be re-run without producing two of everybody.

PUT/v1/subjects

Create or update, idempotent on externalId. Send the same payload twice and you get the same subject.

Body

{
  "externalId": "crm_example_001",
  "displayName": "Alex Morgan",
  "email": "alex@example.com",
  "status": "active",
  "attributes": { "tier": "Platinum", "department": "Operations" },
  "attributesMode": "merge"
}

attributes is where anything a template reads from lives. attributesMode decides whether the payload is merged into what is already there or replaces it — merge when a system owns one field, replace when it owns the whole record.

Send what a credential needs, and no more

attributes accepts anything, which is why the shortest route — pushing the whole record your system already has — is the one to avoid. A credential is a public-facing object: what goes in it can end up printed on a pass, shown on a verification page, exported, and answered for later.

  • Send the fields a template reads. If no field, rule or design refers to it, it does not belong in the credential.
  • Leave sensitive records where they are. Government identifiers, health data, salary, notes — none of that is needed to prove somebody is a member, a student or an employee.
  • Use externalId as the join. It is your own key for that person, so your system stays the place where the full record lives and Nomi holds a projection of it.
  • Pick attributesMode deliberately. merge when one system owns one field; replace when it owns the whole set and a missing field means *removed*.
  • Deactivate rather than delete, and delete from your own system first: what is never sent cannot leak and does not have to be cleaned up here.

GET/v1/subjects

List, with status and free-text q over name, email and external id.

GET/v1/subjects/{id}

One subject, with a count of the credentials they hold.

DELETE/v1/subjects/{id}

Only for somebody who holds no credentials — answers 409 otherwise.

Photos

PUT /v1/subjects/{id}/photo attaches the portrait an employee or student ID shows. GET /v1/subjects/{id}/photo/{density} serves it at the density a device asks for.

Groups

/v1/groups collects subjects into cohorts — a class, a department, an intake. A group is also what a policy decides on, which is what makes adding somebody to one issue their credential.

Verification

Asking whether one is good.

REST API

Connecting your own system.