# Cliento API reference: Staff

Base URL: `https://api.cliento.com`

Staff are the people who work at a location. Other calls refer to a staff member to say who did
something, such as who took stock out.

A staff member is not the same as a resource. A resource is what gets booked in the calendar. A
staff member can be linked to one or more resources, or to none.

## Staff

The Staff API lists the people who work at a location. Use it when another call needs to say who
did something, such as who took stock out or who mixed a colour. Those calls take a staff id
(`stf_...`).

A staff member is not the same as a resource. A resource is what gets booked in the calendar. A
staff member can be linked to one or more resources, or to none.

**PIN check.** If staff use your application, they can identify themselves with the PIN they
already use in Cliento's point of sale. Send the typed PIN to
`POST /v1/locations/{locationId}/staff/pin-check` and you get the staff member back. The check
signs nobody in: you still send the staff id on the calls that take one. PINs are never returned.
The check needs the scope `staff:pin-check`.

A location chooses whether its staff use PINs. `pinsInUse` in the staff list says which. An
`Idempotency-Key` is ignored on the check: every check runs.

### List staff

`GET /v1/locations/{locationId}/staff`

Scope: `staff:read`

Stability: preview

The location's staff members, sorted by name. Use a staff id to say who did something, for example who took stock out. PINs are never returned; `hasPin` says whether a person has one.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | StaffList |
| default | Any failure. See the Errors section. | Error |

### Check a PIN

`POST /v1/locations/{locationId}/staff/pin-check`

Scope: `staff:pin-check`

Stability: preview

Says whose PIN was typed, so your own screen can let staff identify themselves with the PIN they already use at the point of sale. A PIN belongs to one person at a location. Nothing is signed in and no token is issued: send the staff id on the calls that take one. A PIN nobody has is refused with `pin_not_recognised`. An `Idempotency-Key` is ignored here.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |

**Request body**: PinCheck

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | PinCheckResult |
| default | Any failure. See the Errors section. | Error |

## Staff hours

**Coming soon.** Read the hours staff have worked, and record them from your own time clock.

## Schemas

### Error

The body of every non-2xx response.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | Yes | Stable, machine-readable error code. Values today: `invalid_request`, `validation_failed`, `entity_not_found`, `duplicate`, `merchant_required`, `code_already_used`, `gift_card_already_used`, `pin_not_recognised`, `insufficient_stock`, `not_allowed`, `request_in_progress`, `idempotency_key_reused`, `unauthenticated`, `forbidden`, `account_blocked`, `rate_limited`, `route_not_found`, `method_not_allowed`, `internal_error`. |
| `details` | object of any value | No | Extra detail. For `validation_failed`, `fieldErrors` maps each rejected field to the reason. |
| `message` | string | Yes | Human-readable explanation. Not stable; do not parse it. |

### PinCheck

A PIN typed by a person at your screen.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `pin` | string | Yes | The PIN, digits only. Example: `4711`. |

### PinCheckResult

Whose PIN it is.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | No | The person's name. Left out when none is registered. Example: `Clara Nyberg`. |
| `staffId` | string | Yes | Staff id. Example: `stf_7Qm2xLd9Kc4Vb1Ts8HpWzE`. |

### Staff

Represents a person who works at a location, and belongs to that location. Other data refers to a staff id to record who made a sale or a stock withdrawal. A staff member is not a resource; a resource is what gets booked, and a staff member can be linked to one or more resources, or to none.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `hasPin` | boolean | Yes | Whether the person has a PIN for the point of sale. The PIN itself is never returned. Example: `true`. |
| `id` | string | Yes | Staff id. Example: `stf_7Qm2xLd9Kc4Vb1Ts8HpWzE`. |
| `name` | string | No | The person's name. Left out when none is registered. Example: `Clara Nyberg`. |
| `resourceIds` | array of string | Yes | The resources the person is linked to. Often one, and can be empty. Example: `["res_4Hn7pQw2Zt9Lk3Vd6XyRbA"]`. |

### StaffList

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of Staff | Yes | The staff of the location, sorted by name. At most 500. |
| `pinsInUse` | boolean | Yes | Whether the location has switched PINs on at its point of sale. When false, staff pick their name from a list there, and a PIN a person happens to have is not asked for. Example: `true`. |