OneID Hotel API

Verify guest identity at check-in with one API call. Base URL: http://localhost:4100

Authentication

Every request carries your API key in the x-api-key header. Issue keys from the Hotel Portal → API Keys (hotel admins, after platform approval). Keys can be hotel-wide (pass propertyId per request) or scoped to one property.

The flow

Guest opens their OneID wallet and generates a 6-digit share code (5-min TTL, single use).
Your system calls POST /v1/verify with the guest's OneID + code.
You receive an attested guest card and a consentId.
Create the check-in with POST /v1/checkins — the digital guest register entry and (for foreign guests) the Form C payload are generated automatically.

Data minimization by design: you never receive full ID numbers, document images, address, or phone. Every access is recorded in a DPDP consent artifact visible to the guest, who can revoke it.

POST/v1/verify

Redeem a guest's share code and receive the attested guest card.

curl -X POST http://localhost:4100/v1/verify \
  -H "x-api-key: oneid_live_..." \
  -H "content-type: application/json" \
  -d '{
    "oneId": "OID-7K2M-9Q4X",
    "shareCode": "482913",
    "propertyId": "<uuid>"   // omit if your key is property-scoped
  }'

{
  "success": true,
  "data": {
    "card": {
      "oneId": "OID-7K2M-9Q4X",
      "fullName": "Ravi Kumar",
      "dob": "1992-03-10T00:00:00.000Z",
      "gender": "M",
      "nationality": "IN",
      "idType": "digilocker_aadhaar",
      "idMaskedNumber": "XXXX XXXX 3210",
      "idIssuer": "UIDAI",
      "verificationLevel": "verified",
      "verifiedAt": "2026-07-11T11:47:44.065Z",
      "attestedBy": "OneID"
    },
    "consentId": "7c481412-...",
    "consentExpiresAt": "2026-08-10T11:47:44.328Z"
  }
}

Share codes are single use: a second call with the same code returns SHARE_CODE_USED. Expired codes return SHARE_CODE_EXPIRED.

POST/v1/checkins

Create the check-in (guest-register entry) from a consent. Foreign guests auto-generate a Form C payload.

{
  "consentId": "7c481412-...",
  "propertyId": "<uuid>",          // omit if key is property-scoped
  "roomNumber": "204",             // optional
  "expectedCheckout": "2026-07-14T10:00:00Z"  // optional, ISO-8601
}

{
  "success": true,
  "data": {
    "checkin": { "id": "...", "status": "checked_in", "isForeignGuest": false },
    "formC": null   // populated + FRRO payload when nationality != IN
  }
}

POST/v1/checkins/:id/checkout

Mark the guest checked out. Body: { "propertyId": "<uuid>" } (hotel-wide keys only).

GET/v1/checkins/:id

Fetch one check-in with its attested guest snapshot and Form C record.

Error codes

API_KEY_MISSING / API_KEY_INVALID	401 — check the x-api-key header
HOTEL_INACTIVE	403 — hotel pending approval or suspended
GUEST_NOT_FOUND	404 — OneID does not exist
SHARE_CODE_INVALID / _USED / _EXPIRED	400 — ask the guest for a fresh code
CONSENT_REVOKED / CONSENT_EXPIRED	403 — guest withdrew consent
PROPERTY_FORBIDDEN	403 — property does not belong to your hotel
ALREADY_CHECKED_IN	409 — consent already used for a check-in
QUOTA_EXCEEDED	402 — monthly plan quota exhausted; upgrade your plan
RATE_LIMITED	429 — slow down; per-minute limit hit

All responses use the envelope { success, data, meta } / { success: false, error: { code, msg, details } }.