fepli
deen
DevelopersAPI resources

Host invitations

A host invitation asks someone by e-mail to become a member of a host, or to register a new host. The e-mail carries a personal link; following it, the person creates their access. The API sends, lists, resends and withdraws host invitations the way the admin does with Einladen on the hosts list, Konto einladen in a host's row and Mitglied einladen on a host's Team tab.

Endpoints

Admins see every invitation. Host users see the invitations into the hosts they are a member of, and can send, resend and withdraw those. Invitations to register a new host are for admins only.

To make an account that already exists a member of a host straight away, without an e-mail, an admin uses Add a member instead.

The host 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 host the person becomes a member of. null for an invitation to register a new host.

  • 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 and 30 days at most. 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 host 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 host (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.

GET/host-invitations
curl "https://example.fepli.eu/api/host-invitations?host=kunstschule-elmsbrueck&status=open" \
  -H "Authorization: Bearer $FEPLI_TOKEN"

Response

[
  {
    "uuid": "01995e3a-7b4c-7d8e-9f0a-1b2c3d4e5f61",
    "email": "l.wagner@kunstschule.example.fepli.eu",
    "host": {
      "uuid": "0193c9d1-2e3f-7a4b-8c5d-6e7f8a9b0c18",
      "name": "Kunstschule Elmsbrück",
      "alias": "kunstschule-elmsbrueck"
    },
    "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 a host invitation

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

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

Invite a member

Invites someone to become a member of a host. 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 becomes a member, with access to everything the host has. Admins find the e-mail among the sent messages.

Admins and the host'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-Agent 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 host 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 a member of the host.

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

Required attributes

  • Name
    email
    Type
    string
    Description

    The address to invite.

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

Response (201 Created)

{
  "uuid": "01995e3a-7b4c-7d8e-9f0a-1b2c3d4e5f61",
  "email": "l.wagner@kunstschule.example.fepli.eu",
  "host": {
    "uuid": "0193c9d1-2e3f-7a4b-8c5d-6e7f8a9b0c18",
    "name": "Kunstschule Elmsbrück",
    "alias": "kunstschule-elmsbrueck"
  },
  "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 host

Invites someone to register a new host. Admins only. fepli sends the e-mail that Einladen on the admin's hosts list sends, to one address, with a personal link. Following it, the person enters the host's details and creates their access; the host and its account only come into being then. The e-mail is sent in the background and appears among the sent messages.

Without subject and text, the e-mail uses the admin's default wording, which invites the recipient 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 is already a member of a host is a 409: registering would make a second host. Invite them as a member of another host instead. An account without a host is fine; registering adds the new host to it.
  • If the edition asks hosts to sign a confidentiality declaration, you must have signed it before you write to hosts about that edition, as in the admin. Otherwise the request is a 409. A service account can't sign the declaration, so its request is a 409 as well: send the invitation from the admin, or with the personal token of a colleague who signed.
  • 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 host_editing_stage task is active.

  • Name
    subject
    Type
    string
    Description

    The subject line, up to 255 characters. Defaults to "Einladung: 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 how many days the link is valid, as your installation sets it.

POST/host-invitations
curl -X POST https://example.fepli.eu/api/host-invitations \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "info@tanzschule.example.fepli.eu",
    "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.example.fepli.eu",
  "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 a host 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.

  • Invitations to become a member follow the rules for inviting a member: you must be allowed to change the host, and the e-mail goes out in your name (or the service account's). If the person has become a member in the meantime, the request is a 409.
  • Invitations to register a new host are for admins only. The default text goes out, even if the first e-mail had its own subject or text, about the edition whose host_editing_stage task is active. 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).

POST/host-invitations/{uuid}/resend
curl -X POST https://example.fepli.eu/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 a host 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).

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

Was this page helpful?