Integrating with OGIVS

Overview

OGIVS issues two distinct kinds of credential, and it is worth being clear about which direction each one points:

Both are owned by an organization, both come in Test and Live modes, and both follow the same disclosure rule: the plaintext value is returned exactly once, at the moment it is minted.

Implementation status

Key anatomy

A key is minted from 32 cryptographically random bytes, base64-encoded with the non-alphanumeric characters stripped. The first eight characters of that secret are reused as a searchable prefix:

Test & live modes

Mode is an enum taking Test or Live. An organization may hold one active key per mode — so one test key and one live key concurrently.

Attempting to create a second active key in a mode that already has one returns 409 Conflict. This is deliberate: replacing a key is an explicit rotation, so a compromised key cannot quietly remain valid beside its replacement. Use the regenerate endpoint instead.

Creating a key

The organization is resolved from the authenticated caller, never taken from the request body — an organization admin cannot mint a key against somebody else's organization. Requires the ApiKeysCreate permission.

Response — 201 Created

{
  "id": "01a03d0e-b6b8-7d0b-a182-633ece0736aa",
  "organizationId": "01a03d0e-9c21-7f4a-b8e2-1d4f8a2c6b90",
  "mode": "Live",
  "keyPrefix": "sk_live_A7f2Kq9x",
  "scopes": ["guests:read", "stays:read", "stays:write"],
  "isActive": true,
  "createdAt": "2026-08-26T11:04:22.417+00:00",
  "rawKey": "sk_live_A7f2Kq9x_A7f2Kq9xT3nR8vC1wE5yU0iO6pS4dF2gH9jK7lZ3xQ"
}

Scopes

At least one scope is required. Scopes are persisted as a comma-separated, deduplicated, ordinally sorted string, so two identical grants compare equal.

Scopes on an existing key are replaced wholesale — the request body is the new complete set, not a delta:

Rotation & revocation

API key endpoints

All paths are relative to /api/v{version}. Available on v1 and v2.

Platform administration

Acting on a named organization rather than the caller's own:

Usage & billing

Booking-desk calls are metered per organization and accrued onto a monthly usage row. Reads are charged as well as writes — an occupancy sheet costs the same lookup as the booking. Platform staff are excluded, since they act on organizations rather than as one.

Signing secrets

A webhook secret is the shared key that outbound deliveries are signed with, so your endpoint can verify a payload originated from OGIVS and was not altered in transit. It is generated identically to an API key — 32 random bytes, prefix retained, SHA-256 hash stored — but carries the whsec marker.

Unlike an API key, a secret is bound to an organization at creation and is always organization-scoped.

Event types

A secret may be narrowed to particular events. An empty event-type list means the secret covers every event — it is not an inert secret.

Event types are replaced wholesale, as scopes are:

Creating a secret

Response — 201 Created

{
  "id": "01a03d0e-c4d2-7a1b-9f83-52ab7c9e4d11",
  "organizationId": "01a03d0e-9c21-7f4a-b8e2-1d4f8a2c6b90",
  "mode": "Live",
  "secretPrefix": "whsec_live_Bq4Lp2m8",
  "eventTypes": ["stay.checked_in", "stay.checked_out"],
  "isActive": true,
  "createdAt": "2026-08-26T11:07:03.882+00:00",
  "rawSecret": "whsec_live_Bq4Lp2m8_Bq4Lp2m8N6vX1cZ8kW3rT5yH0jL9dG2fS7aQ4pM"
}

import crypto from "node:crypto";

app.post("/webhooks/ogivs",
  express.raw({ type: "application/json" }),   // raw bytes, not parsed JSON
  (req, res) => {
    const signature = req.get("X-OGIVS-Signature");

    const expected = crypto
      .createHmac("sha256", process.env.OGIVS_WEBHOOK_SECRET)
      .update(req.body)
      .digest("hex");

    const ok =
      signature &&
      signature.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));

    if (!ok) return res.status(401).send("bad signature");

    const event = JSON.parse(req.body.toString());
    // Handle, then acknowledge quickly.
    res.status(204).end();
  });

Webhook secret endpoints

Platform administration

Listings

A listing is one rentable space — a room, a hall, a pitch, a desk. Stays are booked against them, so an organization registers its spaces once and then books guests into them.

The type describes the space, not the organization. A hotel is a hotel, but it may list guest rooms and a conference hall side by side, and each is a listing of its own kind.

Every listing also carries a publicId — a ULID minted by the server. Use it when referring to a space from outside the system; the internal id stays for API calls.

Adding spaces

One call adds one space, or a hundred. Everything except the codes is shared across the batch, so a hotel registers rooms 001–100 as a hundred listings that share a name, rate and description while each keeps its own room number.

Passing one code creates one listing; passing none creates a single listing with no code. Up to 500 codes in a request — generous for a large hotel, and a bound on what a mistyped range can insert.

The rate is copied onto a stay when the booking is taken, so repricing a space later does not restate what an earlier guest was charged. Amend a listing with PUT /listings/{id}.

Listing & filtering

Returns the calling organization's own spaces, paginated and newest first. Narrow with any combination of the filters below.

A single space reads back by id at GET /listings/{id}, or by its ULID at GET /listings/by-public-id/{publicId} — useful when the reference came from a booking confirmation or a sign on the door rather than from the API.

Availability

A space out of service is deactivated rather than deleted. Bookings already taken against it keep their history, and it can be brought back when the repairs are done.

Deleting is for a space added by mistake, not one taken out of service — DELETE /listings/{id}.

Listing endpoints

Registering a guest

Three calls, in order. Each one hands the next what it needs, so nothing is typed twice and the document a guest presented stays attached to the record it proves.

Before any of them, check whether the guest is already known. Looking someone up is free, whether by phone, email or a photograph of their document; reading their document and verifying the number are both charged. So the lookup is what saves a returning guest from being registered — and paid for — twice.

Before you start · Is the guest already known?

Two free lookups, either of which can end the whole exercise. A guest registered by any organization is the same person at yours — that is the point of guests being shared — so a returning traveller should be booked in, not registered again.

By phone number or email

Whichever detail the guest offered. Which one it is is worked out from the value, so there is nothing to declare: an address contains an @ and a number does not.

Numbers are matched in stored form, so +2348031234567 and 08031234567 find the same guest. An email is matched with its domain lowercased. Responds 404 when nobody holds it — which is the answer that means it is safe to register someone new.

By document image

When the guest has handed over a document rather than a phone number. Upload the photograph as in step 1, then pass its file id here: the number is read off the image and looked up in one call, so nobody types it. It asks whether that exact document is already on file, and where its checking stands.

This is the scan a desk should run before registering anyone: it is what tells you whether the person handing over a document is new, or already a guest somewhere and simply needs booking in. Skipping it does not stop registration — it only means paying to verify someone who was already on file.

Accepts the same two documents the reader handles anywhere else — NationalIdentityNumber and InternationalPassport.

Response — 200 OK

{
  "found": true,
  "documentType": "NationalIdentityNumber",
  "documentNumber": "52306459347",
  "guest": {
    "id": "01a04911-c401-77ee-9ed4-2b24ffdef02a",
    "fullName": "Kolade Oluwafemi",
    "uniqueId": "01M11A2JHPR3RMHPAM03ZQW0XS",
    "onboardedByOrganizationName": "Lagoon Suites"
  },
  "status": "Verified",
  "isVerified": true,
  "verifiedAt": "2026-08-28T11:04:22.417+00:00",
  "documentExpiryDate": null,
  "isExpired": false,
  "identityRecordId": "01a048a8-73ad-7e00-a7ce-d007e825d3ac"
}

Once the image reads, this answers 200 either way — not finding a document is an answer, not a failure, so branch on found rather than on the status code. The number that was read comes back in documentNumber whether or not anybody holds it, ready to carry into the register flow.

What to do with the answer

Step 1 · Upload the document

Post the photograph of the guest's document and keep the id that comes back. A JPEG or PNG photographed at a reasonable size reads best; the reader enlarges a small image before it gives up on it, but it cannot recover detail a camera never captured.

Step 2 · Read & verify it

Send the file id and the document type. For a NIN this does two things in one call: it reads the number off the slip, then checks that number against the issuing authority and returns the register's own record of the person.

Response — 200 OK

{
  "fileId": "01a04437-6a48-7de2-bc81-6b90da2f3b03",
  "documentType": "NationalIdentityNumber",
  "succeeded": true,
  "verified": true,
  "fromCache": false,
  "identityRecordId": "01a048a8-73ad-7e00-a7ce-d007e825d3ac",
  "firstName": "SAMUEL",
  "middleName": "ADEKUNLE",
  "lastName": "ODEJINMI",
  "documentNumber": "52306459347",
  "dateOfBirth": "1996-12-12",
  "gender": "M",
  "verification": { "isMasked": false, "photo": "/9j/4AAQ…", … },
  "ocr": { "firstName": "KOLADE", "rawText": "…", … }
}

The top-level fields carry the register's answer where a lookup succeeded; the ocr block keeps what the reader made of the photograph alongside it, so a desk can see where the card and the register disagree. On a document type with no register to check against, the top-level fields are the reader's own transcription and verified is false.

Verifying a NIN with no image

When the desk has the eleven digits themselves — typed, read out, or copied from another record — rather than a slip to photograph. This checks the number against the issuing authority directly, skipping the reading step entirely, and returns exactly the record step 2 would have for the same NIN.

Response — 200 OK

{
  "identityRecordId": "01a048a8-73ad-7e00-a7ce-d007e825d3ac",
  "number": "52306459347",
  "verified": true,
  "fromCache": false,
  "details": { "isMasked": false, "firstName": "SAMUEL", "lastName": "ODEJINMI", … }
}

identityRecordId is the same field step 2 returns and goes to the same place — straight into step 3. There is no ocr block here: nothing was read off an image, so there is nothing to compare the register's answer against.

Step 3 · Register the guest

Pass the identityRecordId from step 2 along with the guest's contact details. Either an email or a phone number is required.

documentNumber is not sent: it is taken from the identity record, so what is filed is always the number that was actually verified. proofId is optional too — leave it out and the slip already held on the identity record is filed as the proof.

The guest's own identifier is minted by the server and cannot be supplied. Responds 409 when the email or phone already belongs to a guest, naming which of the two collided.

Verified or pending

What the document is decides where the verification starts, and that is the whole difference between the two paths.

The outcome of a manual review is recorded by OGIVS on PATCH /guest-verifications/{id}/status, which moves a pending document to Verified, Failed or Expired. A failure carries a note saying why, so the desk knows what to send instead.

Amending a document

A document that has not passed can be corrected or re-uploaded. One that has passed cannot.

Guest & verification endpoints

Guest stays

A stay is one booking: a guest, optionally a space, and the dates they hold it for. It is the record the desk works from and the one the law asks about, which is why a guest must be registered and their document filed before a stay can be taken against them.

Every endpoint in this section is scoped to the calling organization. A stay belonging to somebody else reads back as 404 rather than 403 — an organization is not told which booking references exist elsewhere.

Who may be booked in

A booking is refused unless the guest has an identity document on file. What that document is decides how far it goes.

The one-stay allowance counts stays that are not cancelled. A guest whose pending booking was cancelled may book again; one who is checked in may not, until the document is reviewed.

A refusal arrives as 409 Conflict and says which of these it was, so the message can be shown to the clerk as it stands.

Taking a booking

The guest and the dates are required. The space is not — a booking may be taken before a room is assigned, and the listing added later by amending the stay.

Response — 200 OK

{
  "id": "01a04b77-1f52-7a93-8c04-2ed9b7451a60",
  "bookingReference": "HTL42-20260831T142201",
  "organizationProfileId": "01a03f18-9c44-7bb1-a0d5-71c2e8930b4e",
  "organizationCode": "HTL42",
  "organizationName": "Ikoyi Suites",
  "guest": { "id": "01a04a12-…", "firstName": "SAMUEL", "lastName": "ODEJINMI", "primaryPhone": "+2348012345678" },
  "listing": { "id": "01a0491f-…", "publicId": "01K9WQ…", "name": "Deluxe Room", "code": "204" },
  "checkInDate": "2026-09-04T14:00:00Z",
  "checkOutDate": "2026-09-07T11:00:00Z",
  "rate": 45000,
  "ratePeriod": "Night",
  "totalAmount": 135000,
  "status": "Pending",
  "createdAt": "2026-08-31T14:22:01.482Z"
}

Rates & totals

The rate and period are copied onto the stay when it is taken, not read from the listing afterwards. Repricing a room later does not restate what a guest was already charged.

Send totalAmount to charge an agreed figure. Omit it and the total is worked out from the rate, the period and the dates — rounded up, so a stay that runs into a further night is charged for it.

With no rate at all, the total is null — a booking held before terms are agreed. The period belongs to the price, not to the space: the same hall may be hired by the hour one day and as a session the next.

Arrival & departure

A stay opens as Pending and moves forward one step at a time. Each transition is its own endpoint, so a mistyped date cannot silently check somebody out.

Pending ──check-in──▶ CheckedIn ──check-out──▶ CheckedOut
   │                      │
   └──── cancel ──────────┘──▶ Cancelled

Any transition out of turn is 409 Conflict, naming the state the stay is actually in. Each returns the whole stay, so there is no need to read it back afterwards.

Amending a booking

Dates, space, rate and total can be changed while a stay is Pending or CheckedIn. A stay that is checked out or cancelled is a record, and amending one would rewrite it — 409.

Omitted fields are left alone, so a single date can be moved without restating the booking. The dates are then checked against what is stored rather than against each other, so moving check-out behind an unchanged check-in is caught. Moving to a different space re-checks availability, and the space must be one of yours and active.

Listing & filtering

Returns the calling organization's own stays, paginated. Narrow with any combination of the filters below.

A single stay reads back at GET /stays/{id}, or by the reference the guest quotes at GET /stays/reference/{reference}.

Stay webhooks

Before relying on stay notifications, ask whether your organization is actually set up to receive them. The readiness endpoint answers in one call rather than leaving you to infer it from silence.

Response — 200 OK

{
  "ready": false,
  "hasLiveApiKey": true,
  "hasLiveWebhookSecret": true,
  "hasCallbackUrl": false,
  "callbackUrl": null,
  "secretPrefix": "whsec_live_9f2a",
  "subscribedEvents": ["stay.created", "stay.checked_in"],
  "missing": ["No callback URL is set on the live webhook secret"]
}

missing lists what is left to do in words, so a failing integration can be diagnosed without reading each flag. All of live API key, live webhook secret and callback URL must be in place before ready is true.

Send a test event

Delivers a specimen stay.created to your callback URL so you can confirm the endpoint answers and your signature check passes, without waiting for a real booking.

{
  "deliveryId": "01a04c03-5d19-7f44-9a6b-3c81e0d7b295",
  "eventType": "stay.created",
  "delivered": true,
  "statusCode": 200,
  "attempts": 1,
  "latencyMs": 412,
  "nextAttemptAt": null,
  "error": null
}

Replay a stay

Re-sends the event for one real booking — for when your endpoint was down, or a delivery was lost. Replays carry the same payload as the original.

A delivery that fails is retried with a widening gap; attempts and nextAttemptAt say where it has got to. If nothing is configured, both endpoints answer 409 listing exactly what is missing rather than reporting a delivery that never left.

Guest stay endpoints

The stay endpoints need stays:read or stays:write; the three webhook endpoints need webhooks:read and webhooks:write.

Errors

Failures are rendered as RFC 7807 ProblemDetails by the global exception handler.

Versioning

Every endpoint here is published on both v1 and v2. Select a version by URL segment, /api/v1/…, or by the X-Api-Version header. Responses report the versions they support.