Venue API Reference

Overview

The Venue API exposes the same in-house guest identification that powers Fotiqo's self-service kiosk, so your own access-control, POS, or ride-exit system can link the identifier it already reads — an NFC/RFID tag, a QR wristband, or a hotel room number — to the guest's Fotiqo gallery and get back a magic-link URL to hand them. It's hardware-agnostic: keep the readers you own; Fotiqo handles matching, the gallery, and delivery.

Authentication

Every request is authenticated with a venue API key sent as a Bearer token. Generate and revoke keys in Dashboard → Settings → Integrations. Keys are scoped to your organisation — a key can only ever read your own venue's guests and galleries. Keep keys server-side; never embed them in a browser or mobile app.

Authorization: Bearer fq_live_xxxxxxxxxxxxxxxxxxxxxxxx

GET /v1/venue/locations

List your organisation's locations to resolve the location_id the other endpoints require. Start here.

Example request

curl "https://www.fotiqo.com/api/v1/venue/locations" \
  -H "Authorization: Bearer fq_live_xxxxxxxxxxxx"

Example response (200)

{
  "status": "success",
  "locations": [
    {
      "id": "loc_abc123",
      "name": "Marhabaclub Sousse",
      "city": "Sousse",
      "country": "Tunisia",
      "currency": "TND",
      "type": "HOTEL",
      "active": true
    }
  ]
}

POST /v1/venue/identify

Look up a guest's gallery by the identifier your hardware reads, and receive the magic-link gallery URL to deliver to them.

Request body

Example request

curl -X POST "https://www.fotiqo.com/api/v1/venue/identify" \
  -H "Authorization: Bearer fq_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "nfc",
    "value": "04:6B:2C:8A:1F:45:90",
    "location_id": "loc_abc123"
  }'

Example response (200)

{
  "status": "success",
  "guest_id": "cus_77492x",
  "guest_name": "A. Guest",
  "gallery": {
    "id": "gal_881a",
    "status": "PREVIEW_ECOM",
    "gallery_url": "https://www.fotiqo.com/gallery/9f3c…",
    "photos": 24,
    "purchased": 0,
    "expires_at": "2026-07-04T00:00:00.000Z"
  }
}

If the guest has no gallery yet, gallery is null. Hand the gallery_url to the guest (QR, SMS, or print) — it's the passwordless magic link to their photos.

GET /v1/venue/galleries

List your organisation's galleries (newest first) so a POS or CRM can sync or poll them. Cursor-paginated. Optional query params: location_id, status (a GalleryStatus like PAID), limit (1–100, default 50), and cursor (a gallery id from the previous page's next_cursor).

Example request

curl "https://www.fotiqo.com/api/v1/venue/galleries?location_id=loc_abc123&limit=50" \
  -H "Authorization: Bearer fq_live_xxxxxxxxxxxx"

Example response (200)

{
  "status": "success",
  "galleries": [
    {
      "id": "gal_881a",
      "status": "PAID",
      "customer_name": "A. Guest",
      "location_id": "loc_abc123",
      "photos": 24,
      "purchased": 24,
      "gallery_url": "https://www.fotiqo.com/gallery/9f3c…",
      "created_at": "2026-06-20T10:00:00.000Z",
      "expires_at": "2026-07-04T00:00:00.000Z"
    }
  ],
  "next_cursor": "gal_7720"
}

Pass next_cursor back as ?cursor= to fetch the next page; a null next_cursor means you've reached the end.

GET /v1/venue/galleries/{id}

Fetch one gallery's current status, photo + purchase counts, and magic-link URL — handy for a webhook-free status poll after a sale. Org-isolated: a key can only read its own venue's galleries.

Example request

curl "https://www.fotiqo.com/api/v1/venue/galleries/gal_881a" \
  -H "Authorization: Bearer fq_live_xxxxxxxxxxxx"

Errors

Rate limits

Requests are limited to 120 per minute per API key (a coarser per-source-IP cap also applies as abuse protection). A 429 response includes a retry_after field (seconds). Need higher throughput for a large venue? Talk to us.