> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rxscale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Review Links

> Create single-use, expiring links a pharmacist can open to review a pharmacy order and accept or decline its prescription

# Review Links

Review links let you share a single pharmacy order with a pharmacist who does **not** have a portal login. You create a link over a pharmacy order and send the resulting URL to the pharmacist. When they open it, they see the shop, its icon, and the order's items, and can either **accept and download** the signed prescription PDF or **decline** the order.

Each link is:

* **Single-use** -- once the pharmacist accepts or declines, the link is consumed and cannot be opened again.
* **Expiring** -- links expire after a configurable number of days (7 by default).
* **Revocable** -- you can revoke an unused link at any time.

<Note>
  The plaintext token (and the ready-to-share `url` built from it) is returned **only once**, in the response to the create call. It is stored hashed and cannot be retrieved again. If you lose it, revoke the link and create a new one.
</Note>

## Create Review Link

Create a single-use review link over a pharmacy order.

```bash theme={null}
POST /v1/management/review-links
```

**Required permission:** `review_link:write`

### Request Body

```json theme={null}
{
  "pharmacy_order_uid": "po-abc123",
  "expires_in_days": 7,
  "note": "Please review before end of day"
}
```

| Field                | Type    | Required | Description                                                                         |
| -------------------- | ------- | -------- | ----------------------------------------------------------------------------------- |
| `pharmacy_order_uid` | string  | Yes      | UID of the pharmacy order the link is created over                                  |
| `expires_in_days`    | integer | No       | Days until the link expires. Must be between `1` and `90`. Defaults to `7`          |
| `note`               | string  | No       | Free-text note stored on the link (max 255 characters). Not shown to the pharmacist |

### Example Request

```bash theme={null}
curl -X POST "https://api.rxscale.com/v1/management/review-links" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "pharmacy_order_uid": "po-abc123",
    "expires_in_days": 7,
    "note": "Please review before end of day"
  }'
```

### Response (201 Created)

```json theme={null}
{
  "uid": "rl-def456",
  "token": "kQ8mZ3nR7wF1sT9vB2xY6pJ4hL0aD5cG8eN...",
  "url": "https://api.rxscale.com/v1/pharmacy-api-v1/review/kQ8mZ3nR7wF1sT9vB2xY6pJ4hL0aD5cG8eN...",
  "expires_at": 1735689600
}
```

### Response Fields

| Field        | Type    | Description                                                            |
| ------------ | ------- | ---------------------------------------------------------------------- |
| `uid`        | string  | Unique identifier for the review link. Use it to revoke the link later |
| `token`      | string  | The plaintext link token. **Returned only once**                       |
| `url`        | string  | The ready-to-share URL a pharmacist opens. **Returned only once**      |
| `expires_at` | integer | Unix timestamp (seconds) at which the link expires                     |

<Warning>
  Save the `token` and `url` from this response immediately. They cannot be retrieved again -- listing links never returns the token.
</Warning>

### Error Responses

| Status Code | Description                                                                         |
| ----------- | ----------------------------------------------------------------------------------- |
| `400`       | The pharmacy order has no downloadable prescription, or the request body is invalid |
| `401`       | Missing or invalid API key                                                          |
| `403`       | Missing `review_link:write` permission                                              |
| `404`       | Pharmacy order not found for this organisation                                      |

## List Review Links

List review links for your organisation, optionally filtered to a single pharmacy order. The response includes **revoked** links and their derived status, but **never** the token.

```bash theme={null}
GET /v1/management/review-links
```

**Required permission:** `review_link:read`

### Query Parameters

<ParamField query="pharmacy_order_uid" type="string">
  Restrict the results to a single pharmacy order. When omitted, all review links for the organisation are returned.
</ParamField>

### Example Request

```bash theme={null}
curl -X GET "https://api.rxscale.com/v1/management/review-links?pharmacy_order_uid=po-abc123" \
  -H "X-API-Key: your-api-key-here"
```

### Response (200 OK)

```json theme={null}
{
  "data": [
    {
      "uid": "rl-def456",
      "pharmacy_order_uid": "po-abc123",
      "status": "consumed",
      "expires_at": 1735689600,
      "consumed_at": 1735600000,
      "decision": "accept",
      "note": "Please review before end of day",
      "created_at": 1735084800,
      "visit_count": 2
    },
    {
      "uid": "rl-ghi789",
      "pharmacy_order_uid": "po-abc123",
      "status": "active",
      "expires_at": 1736294400,
      "consumed_at": null,
      "decision": null,
      "note": null,
      "created_at": 1735689600,
      "visit_count": 0
    }
  ]
}
```

### Response Fields

Each object in the `data` array has the following fields:

| Field                | Type            | Description                                                                    |
| -------------------- | --------------- | ------------------------------------------------------------------------------ |
| `uid`                | string          | Unique identifier for the review link                                          |
| `pharmacy_order_uid` | string          | UID of the pharmacy order the link was created over                            |
| `status`             | string          | Current status: `active`, `consumed`, `expired`, or `revoked`                  |
| `expires_at`         | integer         | Unix timestamp (seconds) at which the link expires                             |
| `consumed_at`        | integer \| null | Unix timestamp (seconds) at which the link was used, or `null` if still unused |
| `decision`           | string \| null  | The pharmacist's decision: `accept`, `decline`, or `null` if not yet used      |
| `note`               | string \| null  | The note stored on the link, or `null`                                         |
| `created_at`         | integer         | Unix timestamp (seconds) at which the link was created                         |
| `visit_count`        | integer         | Number of times the link page has been opened                                  |

The `status` field is derived and takes the following values:

| Status     | Meaning                                                                                |
| ---------- | -------------------------------------------------------------------------------------- |
| `active`   | The link has not been used and has not expired or been revoked. It can still be opened |
| `consumed` | The pharmacist has accepted or declined. The link can no longer be opened              |
| `expired`  | The link passed its `expires_at` time without being used                               |
| `revoked`  | The link was revoked via the API before it was used                                    |

### Error Responses

| Status Code | Description                           |
| ----------- | ------------------------------------- |
| `401`       | Missing or invalid API key            |
| `403`       | Missing `review_link:read` permission |

## Revoke Review Link

Revoke an active review link so it can no longer be opened. Only links that are still `active` can be revoked -- revoking an already-used, expired, or revoked link returns `404`.

```bash theme={null}
DELETE /v1/management/review-links/{uid}
```

<ParamField path="uid" type="string" required>
  The UID of the review link to revoke
</ParamField>

**Required permission:** `review_link:write`

### Example Request

```bash theme={null}
curl -X DELETE "https://api.rxscale.com/v1/management/review-links/rl-def456" \
  -H "X-API-Key: your-api-key-here"
```

### Response

Returns `204 No Content` with an empty body on success.

### Error Responses

| Status Code | Description                                                              |
| ----------- | ------------------------------------------------------------------------ |
| `401`       | Missing or invalid API key                                               |
| `403`       | Missing `review_link:write` permission                                   |
| `404`       | Review link not found for this organisation, or not in an `active` state |

## The Pharmacist's View

When a pharmacist opens the link, they do not need to log in. The page walks them through a short, guided flow:

<Steps>
  <Step title="Open the link">
    The pharmacist opens the URL you shared. The page shows the shop's name, its icon, and the list of items in the order -- enough to identify what needs to be reviewed.
  </Step>

  <Step title="Choose an outcome">
    The pharmacist chooses one of two actions:

    * **Accept & download** -- downloads the signed prescription PDF and marks the order as accepted.
    * **Decline** -- marks the order as declined without downloading anything.
  </Step>

  <Step title="Link closes">
    As soon as a decision is made, the link is consumed. Re-opening it shows a "no longer valid" page.
  </Step>
</Steps>

<Note>
  No patient-identifying information is shown on the review page itself. The full prescription -- including patient details -- is only inside the downloaded PDF, which is available exclusively through the **Accept & download** action.
</Note>

If the pharmacist opens a link that has already been used, has expired, or was revoked, they see a page explaining that the link is no longer valid or has already been used, rather than the order details.

You can track how a link was used through the [List Review Links](#list-review-links) endpoint: the `status`, `decision`, `consumed_at`, and `visit_count` fields tell you whether a pharmacist opened the link and what they decided.