Applicant sessions

Applicant APIs are scoped by the invitation token to one application. They do not accept tenant API keys from frontend code.

Session lifecycle

issued → opened → identity/business → document → liveness → screening → submit → completed

The exact steps come from the pinned workflow. A business workflow can include company evidence, UBO collection and linked controller verification. An individual workflow can add NFC, wallets or ECDD.

Read session state

GET /public/sessions/{token}

The response returns safe tenant branding, application type, current and completed steps, expiry, required consent/privacy version and the permitted capture contract.

Identity or business details

POST /public/sessions/{token}/identity
Content-Type: application/json

{
  "givenName": "Amara",
  "familyName": "Vale",
  "dateOfBirth": "1992-06-14",
  "nationality": "SG",
  "email": "person@example.com",
  "address": "Fictional showcase address"
}

For KYB, use the business step and submit beneficial owners exactly as required by the session contract.

Evidence capture

Document and liveness endpoints use bounded multipart uploads. The server checks declared content type, file signatures, image structure, active content, challenge binding and evidence hashes; production also applies malware scanning and encrypted object storage.

Do not resize, recompress, mirror, overlay or pre-process protected captures unless the SDK explicitly documents that transformation. Capture metadata and bytes are part of the integrity contract.

Liveness challenge

1. Request the current one-time challenge and read captureMode, challengeKind and the expiry.
2. Send bounded, challenge-bound observation frames to /liveness/observe for face framing and pose guidance. Observation frames are analysed but not retained as evidence.
3. Automatically capture the required evidence sequence only when the reported position and requested pose are stable.
4. Send the server-issued nonce, capture timestamps, device context and the three unmodified JPEG evidence frames to /liveness.
5. Never reuse a challenge after success, expiry or failure.

POST /public/sessions/{token}/liveness/observe
Content-Type: multipart/form-data

nonce={server-issued-nonce}
frame=@live-observation.jpg

{
  "ready": true,
  "state": "ready",
  "guidance": "Face position confirmed",
  "face": {
    "score": 98.4,
    "area": 0.21,
    "pose": { "yaw": 0.04, "pitch": 0.57 }
  }
}

The client cannot claim a pass. Assayra recomputes binding, replay/injection, presence, PAD and synthetic-media signals server-side.

Consent and submission

POST /public/sessions/{token}/submit
Content-Type: application/json

{
  "consent": true,
  "privacyNoticeVersion": "privacy-sg-en-v4"
}

Submission rejects a stale or unapproved notice version. The hosted journey always uses the exact version returned by the session.

Frontend security rules

• Accept navigation only on the configured Assayra HTTPS origin.
• Never send invitation URLs to analytics, crash reporters or link unfurlers.
• Do not persist camera/NFC material in general-purpose application storage.
• Treat bridge completion as a UI event and reconcile final state on your backend.
• Honour expiry, revocation and 403 responses without trying to bypass them.