Skip to content

Review requests API

Ask customers for a review from your till, booking or shop system with a secret key, what Presence Orbit checks before it sends, and how to list the requests you sent.

Reference5 min read

The review requests API sends the same requests as Requests in Presence Orbit, from your own systems: for example, the till in the Northwilds Bergen shop asks each customer who left an email address. It is in the Growth plan and above.

Bookings, orders and appointments in Travel Orbit, Commerce Orbit and Booking Orbit need no code: see Ask for reviews after trips and orders.

Text
https://app.bifrostorbit.com/presence/api/v1/organisations/{organisationId}/requests

{organisationId} is the id in Presence Orbit's address: /presence/o/{organisationId}.

Keys

An Admin creates keys under API keys in the sidebar. Every key is a secret key and starts with pre_sk_. Older public keys, starting pre_pk_, are still listed with the note Public key, no longer accepted: they get 403 here, so revoke them.

Send it as Authorization: Bearer pre_sk_… or X-Api-Key: pre_sk_…. The key is shown once, when it is created; only a hash is stored. Choose when it expires: never, in 30 or 90 days, or in a year. API keys shows each key's requests in the last 30 days and when it was last used. A revoked or expired key gets 401 from its next request.

A secret key can read your customers' names, email addresses and phone numbers, so never put it in a browser or an app. Presence Orbit refuses a secret key from a browser: a call that carries an Origin header, or a Sec-Fetch-Site header of cross-site or same-site, gets 403 with 'A secret key can only be used from a server, never from a browser.' Calls from your server send neither.

Send requests

Text
POST /requests

Send one person, or up to 100 in requests:

Shell
curl -X POST "https://app.bifrostorbit.com/presence/api/v1/organisations/{organisationId}/requests" \  -H "Authorization: Bearer pre_sk_…" \  -H "Content-Type: application/json" \  -d '{    "requests": [      { "name": "Ingrid Berg", "email": "ingrid@example.com", "location": "northwilds-bergen", "visitedAt": "2026-11-07T14:30:00Z" },      { "name": "Lars Haugen", "phone": "+47 912 34 567", "location": "northwilds-bergen", "channel": "sms" }    ]  }'
name
What it holds
The person's name, up to 120 characters. Required
email
What it holds
Their email address
phone
What it holds
Their phone number in international form, such as +47 912 34 567
location
What it holds
The location's id, slug (such as northwilds-bergen), code or exact name. Required
channel
What it holds
email, sms or whatsapp. Leave it out to use the first channel switched on under Review requests that can reach them
language
What it holds
The language to write in, such as nb. Your main language when it is left out or not one of yours
basis
What it holds
Why you may write to them: customer (the default) or consent. WhatsApp needs consent
visitedAt
What it holds
When they visited. The delay counts from here. Now when it is left out

Every person needs an email address or a phone number. Text messages and WhatsApp need the Growth plan and a Twilio account under Review requests; WhatsApp also needs an approved template. See WhatsApp review requests.

When it is sent

Presence Orbit doesn't send at once. It waits the delay set under Review requests, counted from visitedAt, and moves the time out of the quiet hours, in the location's time zone. A reminder follows if one is set. Everyone gets the same review page, with every review site you use and a way to tell you privately.

The answer

The answer is 200 with one result per person, in the order you sent them:

JSON
{  "data": {    "results": [      { "index": 0, "status": "scheduled", "reason": null, "requestId": "6aee50932701b762d49187a3", "sendAt": "2026-11-08T09:00:00.000Z" },      { "index": 1, "status": "invalid", "reason": "Text messages need the Growth plan and a Twilio account under Review requests.", "requestId": null, "sendAt": null }    ],    "scheduled": 1  }}
scheduled
Means
It will be sent at sendAt
skipped
Means
Not sent, on purpose. reason says why, such as 'They were asked on … The next request is allowed from …', 'They opted out on …', 'A request to them is already waiting to be sent.' or 'The same person appears earlier in this list.'
invalid
Means
Something is missing or wrong, such as 'There is no location called …' or 'Add an email address or a phone number.'

A request skipped because the person opted out, was asked recently or already has one waiting still appears under Requests, with its reason. Nothing is created for an invalid row or a repeat in the same list. How often one person can be asked is set under Review requests, and counts requests from your team as well as from the API.

List requests

Text
GET /requests
status
What it does
waiting, sent, clicked, reviewed or feedback
Default
Every status
location
What it does
A location's id
Default
Every location
channel
What it does
email, sms or whatsapp
Default
Every channel
search
What it does
Part of a name, email address or phone number
days
What it does
How many days back
Default
90
page
What it does
The page, 50 requests each
Default
1

The answer is { "data": { "rows": [...], "total": 120, "page": 1, "perPage": 50 } }, newest first. Each row has id, name, contact (the email address or phone number it went to), location (the name), channel, status, reason, trigger (api, manual, import, qr or orbit), sendAt, sentAt, clickedSource (the review site they chose), reviewId and feedbackId.

Errors

Errors have the shape { "error": { "code": "…", "message": "…" } }. A body that doesn't fit, such as an unknown channel or more than 100 people, gets 422 with code: "invalid" and the problems under issues; nothing is sent. See Troubleshooting for every status.

Was this page helpful?

Read next