Skip to content

Person Passes (/person_pass)

Person Passes

An administrator (admin, super_admin) can create person passes of any category and type via /person_pass, and cancel them.

Categories

CategoryWhoRequired fields
Guest (guest)A resident’s visitorName, property, host resident
Staff (staff)An employeeName; organization and position optional
Contractor (contractor)A contractorName; organization and position optional

Types and validity

TypeValidity
one_timeUntil the end of the current day (Moscow); burned on first entry
temporaryA chosen date (≥ tomorrow, ≤ 31 Dec of the current year)
permanentUntil 31 Dec of the current year

Creation (admin)

/person_pass

Flow:

  1. Category — Guest / Staff / Contractor.
  2. Type — One-time / Temporary / Permanent.
  3. Full name — up to 200 characters.
  4. Expiration date — Temporary only.
  5. Organization, position — for Staff/Contractor (/skip allowed).
  6. Property, purpose — for Guest; then the host resident’s Telegram ID (required).
  7. Confirmation.

For a guest pass hostUserId is required: an administrator specifies the host resident; a resident is set to themselves automatically.

Access code

The 6-digit code is generated automatically. If you set a code manually and it is already taken by an active pass, the system generates a new one and warns: “The code was taken, a new one was generated.”

Verification

Use /verify_person — by 6-digit code or name.

Cancellation

Cancellation is done via the API POST /internal/person-passes/:id/cancel (internal route). Only an active pass can be cancelled; a used/expired/cancelled one returns a conflict.

Audit

All actions are recorded in the audit log: person_pass.created, person_pass.verified, person_pass.cancelled.