fepli
API resources

Invitations

An invitation asks someone by e-mail to join an organiser's team, or to register a new organiser. The e-mail carries a personal link; following it, the person creates their access. The API sends, lists, resends and withdraws invitations the way the admin does with Einladen on an organiser's team page and Veranstaltende einladen on the organisers list.

Admins see every invitation. Organiser users see the invitations into the organisers they belong to, and can send, resend and withdraw those. Invitations to register a new organiser are for admins only.

To put an account that already exists into a team straight away, without an e-mail, an admin uses Add a team member instead.

The invitation model

  • Name
    uuid
    Type
    string
    Description

    The invitation's identifier.

  • Name
    email
    Type
    string
    Description

    The invited address, in lower case.

  • Name
    host
    Type
    reference
    Description

    The organiser whose team the person joins. null for an invitation to register a new organiser.

  • Name
    invitedBy
    Type
    reference
    Description

    The account that sent the invitation. null if a service account sent it or the account was deleted since.

  • Name
    status
    Type
    string
    Description

    open (sent, not yet answered, still valid), accepted or expired.

  • Name
    createdAt
    Type
    timestamp
    Description

    When the invitation was first sent.

  • Name
    expiresAt
    Type
    timestamp
    Description

    When the link stops working. How long an invitation stays valid is set per installation, 14 days unless configured otherwise. Sending the invitation again pushes this out.

  • Name
    acceptedAt
    Type
    timestamp
    Description

    When the person followed the link and joined.

GET/host-invitations

List all invitations

Returns a page of invitations, newest first, whatever their status. The admin shows only the open ones; filter with status=open for the same list.

Optional filters

  • Name
    host
    Type
    string
    Description

    Only invitations into this organiser's team (UUID or alias).

  • Name
    status
    Type
    string
    Description

    Only invitations in this state: open, accepted or expired.

  • Name
    email
    Type
    string
    Description

    Only invitations to exactly this address.

  • Name
    page, itemsPerPage
    Type
    integer
    Description

    See Pagination.

Request

GET·/host-invitations
curl "https://ferienpass-musterstadt.de/api/host-invitations?host=kunstschule-musterstadt&status=open" \
  -H "Authorization: Bearer $FEPLI_TOKEN"

Response

[
  {
    "uuid": "01995e3a-7b4c-7d8e-9f0a-1b2c3d4e5f61",
    "email": "l.wagner@kunstschule-musterstadt.de",
    "host": {
      "uuid": "0193c9d1-2e3f-7a4b-8c5d-6e7f8a9b0c18",
      "name": "Kunstschule Musterstadt",
      "alias": "kunstschule-musterstadt"
    },
    "invitedBy": {
      "uuid": "0193c9e4-8f9a-7b0c-9d1e-2f3a4b5c6d21",
      "name": "Mira Schneider"
    },
    "status": "open",
    "createdAt": "2026-09-15T10:12:44+02:00",
    "expiresAt": "2026-09-29T10:12:44+02:00",
    "acceptedAt": null
  }
]
GET/host-invitations/{uuid}

Retrieve an invitation

Returns one invitation. An invitation you may not see is a 404: for organiser users, that is every invitation into another organiser and every invitation to register a new one.

Request

GET·/host-invitations/{uuid}
curl https://ferienpass-musterstadt.de/api/host-invitations/01995e3a-7b4c-7d8e-9f0a-1b2c3d4e5f61 \
  -H "Authorization: Bearer $FEPLI_TOKEN"
POST/hosts/{uuid}/invitations

Invite someone into a team

Invites someone into an organiser's team. fepli e-mails them its Einladung zur Mitarbeit notification with a personal link, in your name: the default text reads "Sie wurden von Mira Schneider eingeladen …". Following the link, the person signs in or registers and joins the team, with access to everything the organiser has. Admins find the e-mail in the outbox.

Admins and the organiser's own members can invite. Anyone else gets a 403.

  • In whose name. With a personal token, the e-mail names you. With a service account, it names the service account where the text names the inviter ("Sie wurden von Support-Team eingeladen …"), so give it a name that means something to the recipient. The invitation's invitedBy stays null then.
  • Once per address. If an invitation to this address into this organiser is still open, it is renewed rather than duplicated: the same uuid with a new expiresAt, and the e-mail goes out again. If the earlier one has expired, a new invitation is created.
  • Whether the address already has a fepli account doesn't matter: either way the person ends up in the team.

An invalid address is a 422. An address that already belongs to a member of this organiser (ignoring case) is a 409.

Required attributes

  • Name
    email
    Type
    string
    Description

    The address to invite.

Request

POST·/hosts/{uuid}/invitations
curl -X POST https://ferienpass-musterstadt.de/api/hosts/0193c9d1-2e3f-7a4b-8c5d-6e7f8a9b0c18/invitations \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "l.wagner@kunstschule-musterstadt.de"}'

Response (201 Created)

{
  "uuid": "01995e3a-7b4c-7d8e-9f0a-1b2c3d4e5f61",
  "email": "l.wagner@kunstschule-musterstadt.de",
  "host": {
    "uuid": "0193c9d1-2e3f-7a4b-8c5d-6e7f8a9b0c18",
    "name": "Kunstschule Musterstadt",
    "alias": "kunstschule-musterstadt"
  },
  "invitedBy": {
    "uuid": "0193c9e4-8f9a-7b0c-9d1e-2f3a4b5c6d21",
    "name": "Mira Schneider"
  },
  "status": "open",
  "createdAt": "2026-09-15T10:12:44+02:00",
  "expiresAt": "2026-09-29T10:12:44+02:00",
  "acceptedAt": null
}
POST/host-invitations

Invite a new organiser

Invites someone to register a new organiser. Admins only. fepli sends the e-mail the admin's Veranstaltende einladen sends, to one address, with a personal link. Following it, the person describes their organisation and creates their access; the organiser and its account only come into being then. The e-mail is sent in the background and appears in the outbox.

Without subject and text, the e-mail uses the admin's default wording, which invites the organiser to submit offers for the edition and is signed with sender: your name, or the service account's name.

  • If an invitation to this address is still open, it is renewed (same uuid, new expiresAt) and the e-mail goes out again.
  • An address whose account already belongs to an organiser is a 409: registering would make a second organiser. Invite them into the other team instead. An account without an organiser is fine; registering adds the new organiser to it.
  • If the edition asks organisers to sign a confidentiality declaration, you must have signed it before you write to organisers about that edition, as in the admin. Otherwise the request is a 409. This doesn't apply to service accounts.
  • An invalid address, an unknown edition or a text without {{ inviteLink }} is a 422.

Required attributes

  • Name
    email
    Type
    string
    Description

    The address to invite.

Optional attributes

  • Name
    edition
    Type
    string
    Description

    The edition the invitation is about (UUID or alias). Defaults to the edition whose editing phase for organisers is open.

  • Name
    subject
    Type
    string
    Description

    The subject line, up to 255 characters. Defaults to "Einladung: Ferienpass edition – jetzt Angebote einreichen".

  • Name
    text
    Type
    string
    Description

    The message, in Markdown; HTML is removed. It must contain {{ inviteLink }}, which becomes the recipient's personal link. It may use {{ edition.name }} and {{ sender }}. The default text says the link is valid for 14 days: if your installation keeps invitations valid for longer or shorter, write your own text.

Request

POST·/host-invitations
curl -X POST https://ferienpass-musterstadt.de/api/host-invitations \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "info@tanzschule-am-markt.de",
    "edition": "herbstferien-2026",
    "text": "Guten Tag,\n\nhaben Sie Lust, in den Herbstferien einen Schnupperkurs anzubieten? Hier legen Sie Ihren Zugang an:\n\n{{ inviteLink }}\n\nViele Grüße\n{{ sender }}"
  }'

Response (201 Created)

{
  "uuid": "01995e41-2c3d-7e4f-8a5b-6c7d8e9f0a72",
  "email": "info@tanzschule-am-markt.de",
  "host": null,
  "invitedBy": {
    "uuid": "0190a1b2-c3d4-7e5f-8a6b-7c8d9e0f1a22",
    "name": "Sabine Krüger"
  },
  "status": "open",
  "createdAt": "2026-09-15T11:03:09+02:00",
  "expiresAt": "2026-09-29T11:03:09+02:00",
  "acceptedAt": null
}
POST/host-invitations/{uuid}/resend

Send an invitation again

E-mails an invitation again and pushes its expiresAt out, as Erneut senden does in the admin. The request has no body. Responds with 200 OK and the invitation.

  • Team invitations follow the rules for inviting someone into a team: you must be allowed to change the organiser, and the e-mail goes out in your name (or the service account's). If the person has joined the team in the meantime, the request is a 409.
  • Invitations to register a new organiser are for admins only. fepli doesn't keep the text of the first e-mail, so the default text goes out, about the edition whose editing phase is open. The same 409s apply as when inviting.

If the invitation had already expired, a new one is created and returned, with its own uuid; the expired one stays in the list. An accepted invitation can't be sent again (409).

Request

POST·/host-invitations/{uuid}/resend
curl -X POST https://ferienpass-musterstadt.de/api/host-invitations/01995e3a-7b4c-7d8e-9f0a-1b2c3d4e5f61/resend \
  -H "Authorization: Bearer $FEPLI_TOKEN"

Response (excerpt)

{
  "uuid": "01995e3a-7b4c-7d8e-9f0a-1b2c3d4e5f61",
  "status": "open",
  "expiresAt": "2026-10-06T09:40:02+02:00",
  "…": "…"
}
DELETE/host-invitations/{uuid}

Withdraw an invitation

Withdraws an invitation: it is deleted and no longer shows as invited in the admin. Responds with 204 No Content. The same people may withdraw an invitation as may send it again.

The e-mail can't be recalled, but its link stops working: an invitation link only works while its invitation is open, and only once. Following a withdrawn, expired or already used link shows "Diese Einladung gilt nicht mehr".

An accepted invitation can't be withdrawn (409).

Request

DELETE·/host-invitations/{uuid}
curl -X DELETE https://ferienpass-musterstadt.de/api/host-invitations/01995e3a-7b4c-7d8e-9f0a-1b2c3d4e5f61 \
  -H "Authorization: Bearer $FEPLI_TOKEN"

Was this page helpful?