# Get reservation PINs

`GET /v2/bob-box/locations/reservations/pins`

**Base URLs:**

- Production: `https://api.bobbox.co.za`

**Authentication:** Bearer token required (see the Authentication page).

## Example request

```bash
curl -X GET 'https://api.bobbox.co.za/v2/bob-box/locations/reservations/pins' \
  -H "Authorization: Bearer <API_KEY>"
```

Re-fetch the PINs for a reservation.

> **You usually do not need this endpoint.** All three PINs are already in the Create reservation response and in every Get reservations response. Use this when you want just the PINs — for example to re-send one to a customer without pulling the whole reservation.

### Request

**Method:** GET
**URL:** `https://api.bobbox.co.za/v2/bob-box/locations/reservations/pins`

#### Query parameters

| Key | Description | Type | Required |
| --- | --- | --- | --- |
| id | The ID of the reservation. | integer | Yes |

### Response

**Status code:** 200 OK
**Content-Type:** application/json

**Response body example:**

```json
{
    "dropoff_pin": "482150",
    "pickup_pin": "903417",
    "return_pin": "118736"
}
```

#### Response fields

| Key | Description | Type |
| --- | --- | --- |
| dropoff_pin | PIN that opens the compartment for dropoff. | string |
| pickup_pin | PIN that opens the compartment for collection. | string |
| return_pin | PIN that opens the compartment to return the parcel to the sender. | string |

All three PINs are returned, at every reservation status. A field is omitted only when that PIN is genuinely not set on the reservation.

**Counter operators are the exception.** A user with the counter operator role gets exactly one PIN, chosen by reservation type: the `dropoff_pin` for a `client-pickup` reservation, or the `pickup_pin` for a `client-dropoff` one. Any other reservation type returns `400 invalid reservation type to retrieve reservation PIN`.

Every call is recorded as a location event against the calling user.

#### Errors

| Status | Message | Cause |
| --- | --- | --- |
| 400 | `id is required` | No `id` was sent. |
| 400 | `reservation not found` | No reservation exists with that ID. |
| 400 | `invalid reservation type to retrieve reservation PIN` | Counter operators only — see the note above. |