# 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.

Source: https://docs.bifrostorbit.com/presence/developers/review-requests-api/

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://docs.bifrostorbit.com/presence/everyone/requests-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`:

```bash
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" }
    ]
  }'
```

| Field | What it holds |
| --- | --- |
| `name` | The person's name, up to 120 characters. Required |
| `email` | Their email address |
| `phone` | Their phone number in international form, such as `+47 912 34 567` |
| `location` | The location's id, slug (such as `northwilds-bergen`), code or exact name. Required |
| `channel` | `email`, `sms` or `whatsapp`. Leave it out to use the first channel switched on under **Review requests** that can reach them |
| `language` | The language to write in, such as `nb`. Your main language when it is left out or not one of yours |
| `basis` | Why you may write to them: `customer` (the default) or `consent`. WhatsApp needs `consent` |
| `visitedAt` | 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](https://docs.bifrostorbit.com/presence/everyone/whatsapp-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
  }
}
```

| `status` | Means |
| --- | --- |
| `scheduled` | It will be sent at `sendAt` |
| `skipped` | 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` | 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
```

| Parameter | What it does | Default |
| --- | --- | --- |
| `status` | `waiting`, `sent`, `clicked`, `reviewed` or `feedback` | Every status |
| `location` | A location's id | Every location |
| `channel` | `email`, `sms` or `whatsapp` | Every channel |
| `search` | Part of a name, email address or phone number | |
| `days` | How many days back | `90` |
| `page` | The page, 50 requests each | `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](https://docs.bifrostorbit.com/presence/developers/troubleshooting/) for every status.
