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