Docs
API referenceRosters

List shift swaps

Preview· P9
GET
/shift-swaps

Returns shift swaps, newest first: a published shift someone offered to a colleague (or to anyone who could take it), sometimes for one of the colleague's shifts in return, and where it stands: offered, accepted (taken, waiting for approval), approved, declined, refused (the colleague said no), withdrawn, expired (the shift started first) or cancelled (the shift changed). Filter by site, by a person in it, or by status.

Scope: attendance:read · Plan: Pro and Enterprise in live mode; every plan in test mode.

Authorization

headerAuthorizationBearer <token>

Send Authorization: Bearer <token> on every request. The token is one of:

PrefixWhat it isWhere it may be used
agoo_sk_live_Secret key, live modeYour servers only
agoo_sk_test_Secret key, test modeYour servers only
agoo_pk_live_Publishable key, live modeBrowsers and apps: create pre-registrations and bookings, read public booking types (with their intake questions) and their free slots, read the visit types open for pre-registration with their public forms. Never lists people.
agoo_pk_test_Publishable key, test modeAs above, in test mode

Admins create keys in Console → Developers → API keys and choose each key's scopes. A key is shown once. Never put a secret key in a URL, a browser or a mobile app.

Scope: attendance:read

Query Parameters

limit?integer

How many items to return, from 1 to 100.

Range1 <= value <= 100
Default25
cursor?string

The next_cursor from the previous page. Leave it out for the first page.

Lengthlength <= 512
site_id?string

Only those at this site.

Match^site_[0-7][0-9a-hjkmnp-tv-z]{25}$
Example"site_01kjpt3yw0fz0v414608h9x65s"
person_id?string

Only those this person is in.

Match^person_[0-7][0-9a-hjkmnp-tv-z]{25}$
Example"person_01kjsesxm0e4zbyvkr7bcfxbfg"
status?string

Only those in this state.

Response Body

A page of swaps.

application/json
  1. response
data*array<>
next_cursor*|

Pass this as cursor to get the next page. null on the last page.

Example"b3BhcXVlLWN1cnNvcg"
has_more*boolean
curl -X GET 'https://api.agoo.ardent.africa/v1/shift-swaps?limit=25'
{  "data": [    {      "id": "shift_swap_01m5rqnybsm3s6ta3zbtb975p6",      "site_id": "site_01kjpt3yw0fz0v414608h9x65s",      "status": "offered",      "shift": {        "id": "roster_shift_01m5dk4qexa6kwfsr9nhy4r7w5",        "site_id": "site_01kjpt3yw0fz0v414608h9x65s",        "person_id": "person_01kjsesxm0e4zbyvkr7bcfxbfg",        "open": true,        "on_date": "2019-08-24",        "starts_at": "2019-08-24T14:15:22Z",        "ends_at": "2019-08-24T14:15:22Z",        "start_time": "20:00",        "end_time": "08:00",        "shift_id": "shift_01kn6pqfm0fmasbh61jnr3syze",        "name": "Night gate",        "label": "Main gate",        "colour": "blue",        "break_kind": "none",        "break_minutes": 0,        "break_starts": "string",        "note": "string",        "status": "draft",        "pending_change": true,        "removing": true,        "source": "pattern",        "published_at": "2019-08-24T14:15:22Z",        "created_at": "2019-08-24T14:15:22Z",        "updated_at": "2019-08-24T14:15:22Z"      },      "return_shift": {        "id": "roster_shift_01m5dk4qexa6kwfsr9nhy4r7w5",        "site_id": "site_01kjpt3yw0fz0v414608h9x65s",        "person_id": "person_01kjsesxm0e4zbyvkr7bcfxbfg",        "open": true,        "on_date": "2019-08-24",        "starts_at": "2019-08-24T14:15:22Z",        "ends_at": "2019-08-24T14:15:22Z",        "start_time": "20:00",        "end_time": "08:00",        "shift_id": "shift_01kn6pqfm0fmasbh61jnr3syze",        "name": "Night gate",        "label": "Main gate",        "colour": "blue",        "break_kind": "none",        "break_minutes": 0,        "break_starts": "string",        "note": "string",        "status": "draft",        "pending_change": true,        "removing": true,        "source": "pattern",        "published_at": "2019-08-24T14:15:22Z",        "created_at": "2019-08-24T14:15:22Z",        "updated_at": "2019-08-24T14:15:22Z"      },      "from_person_id": "person_01kjsesxm0e4zbyvkr7bcfxbfg",      "to_person_id": "person_01kjsesxm0e4zbyvkr7bcfxbfg",      "taker_person_id": "person_01kjsesxm0e4zbyvkr7bcfxbfg",      "note": "string",      "decision_note": "string",      "approval": {        "status": "pending",        "step": 0,        "of": 0      },      "created_at": "2019-08-24T14:15:22Z",      "accepted_at": "2019-08-24T14:15:22Z",      "decided_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "next_cursor": "b3BhcXVlLWN1cnNvcg",  "has_more": true}

Publish a site's roster POST

Every draft and change waiting at the site reaches staff: drafts are published, changes applied, removals made. Each person whose shifts still to come changed is told once, and staff who can take a new open shift hear of it. Refused with `conflict` while two of someone's shifts would overlap at any site; a change to a published shift starting within 48 hours needs a `note` (`validation_failed`); nothing waiting is `invalid_state`. `roster.published` fires. **Scope:** `attendance:manage` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.

Get a shift swap GET

Returns one shift swap. **Scope:** `attendance:read` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.