GuestLens API

Run your site

The API

The API lets other software manage your GuestLens site: create hosts, give them plans, create events, and read upload counts. New in version 3.0. The Perfex CRM connector uses it, and you can use it from your own code. It answers in JSON.

Turn it on and make a key

The API card in Settings: a switch to turn on the API, how many keys there are, and a Manage API keys button.
Admin, Settings, API.
  1. Open Admin, Settings, tick Turn on the API, and press Save settings. While the API is off, every API address answers Not Found.
  2. Press Manage API keys.
  3. Give the key a name, such as "Perfex CRM", and choose its access:
    • Read only can only read.
    • Full access can also create, change, and sign in as hosts.
  4. Press Make the key and copy it. The key is shown only once. GuestLens keeps only a scrambled copy, so a lost key cannot be shown again. Delete it and make a new one.
The API keys page: the list of keys with access and last use, a form to make a key, how to connect, and safety notes.
Admin, Settings, API keys.
  1. Keys: each key's name, access, last four characters, and when it was last used, with a Delete button.
  2. Make a key.
  3. How to connect: the address and the header to send.
  4. Keep keys safe.
A full access key can sign in as any host. Give it only to software you trust, and only over https. A key acts as the admin who made it, so it stops working if that admin is removed.

Sending requests

The address is your site with /api/v1 at the end. Send the key in the Authorization header, as the word Bearer, a space, and the key: 

curl https://photos.example.com/api/v1 \
  -H "Authorization: Bearer gl_your_key_here" \
  -H "Accept: application/json"

What it can do

RequestWhat it does
GET /api/v1The key's name and access, the GuestLens version, and the event themes and types. Use it to test a connection.
GET /plansEvery plan.
GET /hostsHosts, newest first. Filter with search (name, email, company), email (one exact address), or status.
POST /hostsCreate a host: name, email, password, password_confirmation, and optional company and phone. The same rules as Admin, Hosts, New host.
GET /hosts/{id}One host, with their event credits and number of events.
POST /hosts/{id}/suspend and /unsuspendThe admin's Suspend button.
POST /hosts/{id}/plansGive a host a plan, like the admin's Give plan button.
POST /hosts/{id}/sign-in-linkA one-time sign-in link. Optional event_id.
GET /hosts/{id}/eventsA host's events, with upload counts.
POST /hosts/{id}/eventsCreate an event: name, theme, and optional type, event_date, venue. It uses one of the host's event credits, like their own form, and answers 409 when none is left.
GET /events/{id}One event, with the guest link, upload counts, and the QR code as a PNG in base64. qr_size sets its size, from 180 to 2000 pixels.

The paths in the table come after /api/v1. Reading needs any key. Everything else needs a full access key.

A sign-in link opens the host area as that host, with no password. It works once, for 60 seconds. It is refused for a suspended host and for an admin. Software that asks for one should open it in the person's browser at once, because a link preview that opens it first uses it up.

Try it on the demo

The live demo has the API on, with a read-only key you can use:

curl https://guestlens-demo.jawad.work/api/v1/hosts \
  -H "Authorization: Bearer gl_demoReadOnlyKeyForTheGuestLensDocumentation00001" \
  -H "Accept: application/json"

Changes through the API are turned off on the demo, whatever the key.