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.
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
POST /requestsSend one person, or up to 100 in requests:
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" } ] }'nameemailphone+47 912 34 567locationnorthwilds-bergen), code or exact name. Requiredchannelemail, sms or whatsapp. Leave it out to use the first channel switched on under Review requests that can reach themlanguagenb. Your main language when it is left out or not one of yoursbasiscustomer (the default) or consent. WhatsApp needs consentvisitedAtEvery 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:
{ "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 }}scheduledsendAtskippedreason 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.'invalidA 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
GET /requestsstatuswaiting, sent, clicked, reviewed or feedbacklocationchannelemail, sms or whatsappsearchdays90page1The 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?