Skip to content
VenueGo Protect Events

API reference

Add VenueGo to your application

Instructions for a coding agent adding VenueGo age and identity checks to an existing signup, membership, or checkout.

Give this page to the coding agent that already has your repository. It should change your signup or checkout. It should not rebuild VenueGo, and it should not put an API key in the browser.

Download the integration pack

The file is one markdown document: this task, then the API reference (authentication, sessions, webhooks, results, and errors). Paste it into the agent, or save it in the repo as VENUEGO.md and tell the agent to follow it.

Task

You are adding VenueGo to an existing SaaS application. VenueGo checks a guest’s age and identity on their phone when they sign up or buy. Your job is to start that check from the server you already have, send the guest to the URL VenueGo returns, and grant access only when a signed webhook or a GET says approved.

Read this task, then Authentication, Sessions, Webhooks, Results, and Errors, before you edit code. In the downloaded pack those pages follow this task. Use only the endpoints, fields, and status values written there. If something is not specified, leave it out.

The check reads a passport or driving licence in the camera. It does not look up DVLA, the passport office, or any other government database, and it does not read a passport chip. Do not write copy that says it does. A clear result is not proof a document is genuine. Documents in scope are United Kingdom (GB), Ireland (IE), and United States (US) passports (photo page) and driving licences (front and back).

Where it sits

Find the server-side place that creates a signup, membership, or order. That record needs a stable id you control. After that record exists, create one VenueGo session with sessionId set to that id.

Do this on the server. The guest’s browser only receives the url from the create response. On a desktop, VenueGo shows a QR code so the guest continues on their phone. Do not embed a camera in your app. Do not upload images to the VenueGo API.

Base URL: https://verify.venuego.co.uk/api/v1. The same API is on verify.venueora.com.

What to store

On the signup, membership, or order, store:

  • sessionId you sent (your own id)
  • url from the response, so you can send the guest back to the same check
  • status from the latest webhook or GET
  • when that status last changed

Keep the API key and the webhook secret in the server environment. Suggested names: VENUEGO_API_KEY and VENUEGO_WEBHOOK_SECRET. Never ship either to the client, a mobile app, or a ticket email.

What to build

  1. Create. POST /api/v1/verification-sessions with Authorization: Bearer and a JSON body. sessionId is required, 1–191 printable ASCII characters, no spaces. Prefix it if your id would not fit, and store the value you sent. Pass minimumAge when this signup has its own age. Otherwise the account default is used. A guest under that age is declined and cannot retry.
  2. Send the guest to url. A button or redirect is enough. Tell them the check takes about two minutes on their phone, and that they need a UK, Irish, or US passport or driving licence.
  3. Webhook. Add a public HTTPS endpoint. Read the raw body bytes before you parse JSON. Verify X-VerifyMe-Signature with the endpoint secret (whsec_…) if you registered the URL in Developers, or with the account’s per-session secret if you passed webhookUrl on the session. Reject timestamps more than 5 minutes off. Reply 2xx within 10 seconds. Use the event id so a retry does not grant access twice.
  4. Grant access only on approved. Update your stored status from data.status. needs_review means a person still has to decide. Do not grant access, and do not tell the guest they failed. declined means do not grant access. decision.retryableStep means the guest can try that step again while attempts remain.
  5. Revoke a later decline. verification.decision_changed can arrive after an approval. If a later event declines, remove the access you granted.
  6. Confirm before you trust the browser. successUrl and failureUrl are optional pages for the guest. Anyone with the link can open them. Before you unlock a paid feature, read the webhook you verified, or GET /api/v1/verification-sessions/:sessionId.
  7. Same sessionId is the retry key. A new session returns 201 and "created": true. Repeating an open id returns 200 and "created": false with the current payload. A finished id returns 409 session_closed: create a new id. A 5xx or a timeout on create is safe to retry with the same id. 402 means the VenueGo account has used its allowance. Show that to the operator, not as a guest failure.
  8. Cancel an open session if the signup or order is abandoned: POST /api/v1/verification-sessions/:sessionId/cancel. A finished session returns 409 not_open.

What not to do

  • Do not call any URL that is not in this reference.
  • Do not send the API key from the guest’s phone.
  • Do not treat successUrl as the result.
  • Do not approve the guest locally while status is needs_review, processing, in_progress, or created.
  • Do not describe the check as a government database lookup, a chip read, or proof the document is genuine.
  • Do not put document numbers in metadata. Metadata comes back on the webhook. It is not shown to the guest.

Done when

  • Creating a signup or order on the server creates or reuses one VenueGo session and stores url and status.
  • The guest can open url from your product. Your UI does not ask for the camera.
  • The webhook verifies the signature, ignores duplicate event ids, and updates status.
  • Access is granted only for approved, and removed if a later event declines.
  • The API key and webhook secret are read from the server environment.
  • A repeated create with the same open sessionId does not create a second check.
  • Guest-facing copy names the document types and does not claim a government lookup.