Staff Cards

Staff cards are informational cards about the company or individual employees, shown in the employee app. They can also be used as bonuses or coupons that employees redeem — typically with a QR code and an expiry date. A card is targeted via groups (departments, professions and custom groups), via individually assigned users, or shown to everyone when neither is set. Rich content lives on the card's article — the body convenience field covers simple text-only cards.

Cards come in two types: regular (the default) and personal. A personal card belongs to exactly one user (e.g. a digital business card) — it must target exactly one user via users and can never target groups. Deleting that user also deletes the card.

Required scope: read:staff_cards, write:staff_cards.

Endpoints

GET

/api/open/v1/staff-cards

List staff cards (published by default, paginated)

GET

/api/open/v1/staff-cards/{id}

Get a single staff card

POST

/api/open/v1/staff-cards

Create a staff card (draft by default)

PUT|PATCH

/api/open/v1/staff-cards/{id}

Update a staff card (changes only the fields you send)

DELETE

/api/open/v1/staff-cards/{id}

Soft delete a staff card (returns 204)

List

curl "https://customer.monotree.com/api/open/v1/staff-cards?status=published" \
  -H "Authorization: Bearer mono_your_token_here"

Query param	Notes
`status`	`published` (default), `draft` or `all`.
`type`	`regular` or `personal`. Omit for all.
`since`	ISO 8601 — filter by `created_at`.
`page`, `per_page`	Standard pagination — `per_page` max 50.

Expired cards stay in the list — expiry only hides cards in the employee app.

Create

curl -X POST https://customer.monotree.com/api/open/v1/staff-cards \
  -H "Authorization: Bearer mono_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Fire safety officer",
    "type": "regular",
    "body": "Contact reception for the fire safety plan.",
    "translations": { "title": { "da": "Brandvagt" } },
    "groups": [4, 9],
    "users": [501],
    "expires_date": "2026-12-31",
    "expires_time": "17:00",
    "is_visible_for_managers": true,
    "is_published": true
  }'

Request body

Field	Type	Notes
`title`	string	Required. Written to the default content locale.
`body`	string	Optional. Plain text, becomes a single article paragraph. Cannot be combined with `article_id`.
`article_id`	integer	Optional. Attach a pre-built standalone article created via `POST /articles`.
`translations`	object	Optional. `{ "title": { "<locale>": "..." } }` — writing a translation activates that locale on the card. Locale keys must be active on the platform.
`groups`	array	Optional. Group ids — departments, professions and custom groups can be mixed in one array.
`users`	array	Optional. Individually assigned user ids.
`type`	string	Optional. `regular` (default) or `personal` — personal cards require exactly one entry in `users` and an empty `groups`.
`qr_data`	string	Optional, max 2048, personal cards only. The platform generates a QR code image from this value (e.g. a vCard link) and attaches it as media tagged `qr_code`. `null` clears it and removes the generated image.
`media_ids`	array	Optional, max 1. An uploaded image rendered as a QR code in the bottom-right corner of the card. Requires the `write:media` scope and media uploaded by this token. An uploaded QR image and `qr_data` are alternatives — use one or the other.
`expires_date`	date	Optional. Together with `expires_time` (`HH:MM`), the moment the card disappears from the app.
`expires_time`	string	Optional. `HH:MM`.
`is_visible_for_managers`	boolean	Optional. Also show the card to managers viewing the card owner's profile.
`is_published`	boolean	Optional. Defaults to `false` (draft). Publishing notifies targeted employees.

Create a personal card

A digital business card for a single employee — the QR code is generated from qr_data:

curl -X POST https://customer.monotree.com/api/open/v1/staff-cards \
  -H "Authorization: Bearer mono_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Jane Doe — Business card",
    "type": "personal",
    "users": [501],
    "qr_data": "https://example.com/vcard/jane"
  }'

Update

PUT and PATCH accept the same fields as create (minus article_id) — all optional, only the fields you send change.

curl -X PATCH https://customer.monotree.com/api/open/v1/staff-cards/12 \
  -H "Authorization: Bearer mono_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "is_published": true }'

users replaces the full assignment list — [] clears it.
expires_date and expires_time accept null to clear.
Once a card's article carries rich content, body writes are rejected (422) — use PUT /articles/{id}/elements instead.
When switching a card to personal, the resolved state is validated: the card must end up with exactly one user and no groups (clear groups in the same request if needed).

Response

{
  "data": {
    "id": 12,
    "article_id": 240,
    "title": "Fire safety officer",
    "translations": { "title": { "en": "Fire safety officer", "da": "Brandvagt" } },
    "body": "Contact reception for the fire safety plan.",
    "author": { "id": 8, "name": "Monotree", "type": "customer" },
    "groups": [],
    "users": [ { "id": 501, "name": "Jane Doe", "email": "jane@example.com" } ],
    "media": [ { "id": 77, "type": "image", "url": "https://cdn.example.com/qr.png", "tag": "qr_code" } ],
    "is_published": true,
    "is_visible_for_managers": false,
    "type": "personal",
    "qr_data": "https://example.com/vcard/jane",
    "expires_date": "2026-12-31",
    "expires_time": "17:00",
    "published_at": "2026-07-01T10:00:00+00:00",
    "created_at": "2026-07-01T10:00:00+00:00",
    "updated_at": "2026-07-01T10:00:00+00:00"
  }
}

Rich card content (headers, images, videos, documents) is managed through the card's article_id via the Articles endpoints.