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.

Deleting a user also deletes any published, unexpired card of either type that targets no groups and has that user as its only assigned user. Such a card does not become shown to everyone. A card with other users or with groups only loses that user, and a draft or expired regular card is kept.

Required scope: read:staff_cards, write:staff_cards. The card's article, read or written through the Articles endpoints, takes the staff card scope too: read:articles plus read:staff_cards (or write:staff_cards) to read it, write:articles plus write:staff_cards to write it.

Endpoints

GET

/api/open/v1/staff-cards

List staff cards (published by default, paginated, most recently published first)

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, returns 201)

PATCH

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

Update a staff card (PUT works too; 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`. Any other value returns `422`.
`type`	`regular` or `personal`. Omit for all. Any other value returns `422`.
`since`	ISO 8601 — filter by `created_at` (on or after).
`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. Max 255 characters. Written to the default content locale.
`body`	string	Optional. Max 50,000 characters. 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`. An article that already belongs to other content returns `422`.
`translations`	object	Optional. `{ "title": { "<locale>": "..." } }`, each value max 255 characters — writing a translation activates that locale on the card. Locale keys must be active on the platform, otherwise `422`.
`groups`	array	Optional. Group ids — departments, professions and custom groups can be mixed in one array.
`users`	array	Optional. Distinct, individually assigned user ids.
`type`	string	Optional. `regular` (default) or `personal` — personal cards require exactly one entry in `users` and an empty `groups`, otherwise `422`.
`qr_data`	string	Optional, max 2048. For personal cards the platform generates a QR code image from this value (e.g. a vCard link) and attaches it as media tagged `qr_code`; on a regular card the value is stored but no image is made. `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; only that is checked, not that the media is an image. 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. Returned as `YYYY-MM-DD`.
`expires_time`	string	Optional. `HH:MM`, 24-hour.
`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 and groups each replace the full list — [] clears it.
media_ids replaces the uploaded QR image — [] removes it.
expires_date and expires_time accept null to clear.
is_published: false unpublishes a published card. Publishing a card that has no title in the default content locale returns 422.
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",
      "first_name": "Monotree",
      "last_name": "",
      "title": null,
      "email": "company@example.com",
      "type": "customer",
      "avatar_url": null,
      "is_manager": false,
      "groups": [],
      "hired_at": null,
      "date_of_birth": null,
      "is_away": false,
      "last_active_on": null,
      "registered_at": null,
      "created_at": "2024-01-10T09:00:00+01:00"
    },
    "groups": [],
    "users": [
      {
        "id": 501,
        "name": "Jane Doe",
        "first_name": "Jane",
        "last_name": "Doe",
        "title": "Sales Manager",
        "email": "jane@example.com",
        "type": "default",
        "avatar_url": null,
        "is_manager": false,
        "groups": [ { "id": 4, "name": "Sales", "type": "department", "is_manager": false, "created_at": "2025-02-01T10:00:00+01:00" } ],
        "hired_at": "2025-03-01",
        "date_of_birth": null,
        "is_away": false,
        "last_active_on": "2026-06-30T08:12:00.000000Z",
        "registered_at": "2025-03-01T09:00:00+01:00",
        "created_at": "2025-02-20T09:00:00+01:00"
      }
    ],
    "media": [
      {
        "id": 77,
        "type": "image",
        "mime_type": "image/png",
        "filename": "qr_6687a1.png",
        "size": 1840,
        "url": "https://cdn.example.com/qr.png",
        "width": 300,
        "height": 300,
        "tag": "qr_code",
        "created_at": "2026-07-01T10:00:00+02:00"
      }
    ],
    "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+02:00",
    "created_at": "2026-07-01T10:00:00+02:00",
    "updated_at": "2026-07-01T10:00:00+02:00"
  }
}

author and each users[] entry are the same user object as the users endpoints, without roles. The author is the company account (type customer), or the system user on platforms without one.
groups[] entries carry id, name, type and created_at.
media[] entries are the media object. tag is qr_code for the generated QR image and media for an uploaded one.
body is plain text from the article's first three headers and paragraphs, "" when the article is empty.

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