fepli
deen
DevelopersAPI resources

Hosts

A host is a club, a company or a municipal department that runs offers. Hosts have contact details, a public description and member accounts.

Endpoints

The host model

  • Name
    uuid
    Type
    string
    Description

    The host's identifier.

  • Name
    name
    Type
    string
    Description

    The host's name.

  • Name
    alias
    Type
    string
    Description

    A URL-safe name. Accepted wherever a host is named, as in ?host=stadtjugendring-elmsbrueck.

  • Name
    email
    Type
    string
    Description

    The public e-mail address.

  • Name
    phone
    Type
    string
    Description

    The phone number.

  • Name
    mobile
    Type
    string
    Description

    The mobile number.

  • Name
    fax
    Type
    string
    Description

    The fax number.

  • Name
    website
    Type
    string
    Description

    The website.

  • Name
    address
    Type
    object
    Description

    The postal address, with street, postalCode, city and country (a two-letter code such as de).

  • Name
    text
    Type
    string
    Description

    The public description of the host.

  • Name
    logo
    Type
    string
    Description

    The URL of the host's logo.

  • Name
    offersCount
    Type
    integer
    Description

    The number of offers of this host, across all editions.

  • Name
    members
    Type
    reference[]
    Access
    admins only
    Description

    The accounts that are members of the host. See Add a member and Host invitations.

  • Name
    createdAt
    Type
    timestamp
    Description

    When the host was created.

GET/hosts

List all hosts

Returns a page of hosts, ordered by name. Admins see every host; host users see those they are a member of.

Optional filters

  • Name
    q
    Type
    string
    Description

    Only hosts whose name or e-mail address contains this text.

  • Name
    edition
    Type
    string
    Description

    Only hosts with an offer in this edition (UUID or alias).

  • Name
    page, itemsPerPage
    Type
    integer
    Description

    See Pagination.

GET/hosts
curl "https://example.fepli.eu/api/hosts?edition=herbstferien-2026" \
  -H "Authorization: Bearer $FEPLI_TOKEN"

Response

[
  {
    "uuid": "01905a7e-8c21-7b3f-a0d4-3e9f1c6b2a02",
    "name": "Stadtjugendring Elmsbrück e.V.",
    "alias": "stadtjugendring-elmsbrueck",
    "email": "info@sjr.example.fepli.eu",
    "phone": "0123 456780",
    "website": "https://sjr.example.fepli.eu",
    "address": {
      "street": "Jugendweg 4",
      "postalCode": "12345",
      "city": "Elmsbrück",
      "country": "de"
    },
    "text": "Der Stadtjugendring ist der Dachverband der Jugendverbände in Elmsbrück.",
    "logo": "https://example.fepli.eu/files/logos/sjr-elmsbrueck.png",
    "offersCount": 23,
    "members": [
      {
        "uuid": "0190f1e2-3a4b-7c5d-8e6f-7a8b9c0d1e15",
        "name": "Jonas Becker"
      }
    ],
    "createdAt": "2024-02-19T11:05:31+01:00"
  }
]
GET/hosts/{uuid}

Retrieve a host

Returns one host. Host users can retrieve only the hosts they are a member of; any other is a 404.

GET/hosts/{uuid}
curl https://example.fepli.eu/api/hosts/01905a7e-8c21-7b3f-a0d4-3e9f1c6b2a02 \
  -H "Authorization: Bearer $FEPLI_TOKEN"
POST/hosts

Create a host

Creates a host. Admins only. The alias is generated from the name.

To add members, add their accounts or invite them by e-mail.

Required attributes

  • Name
    name
    Type
    string
    Description

    The host's name, up to 255 characters.

Optional attributes

  • Name
    email
    Type
    string
    Description

    A valid e-mail address.

  • Name
    phone, mobile, fax
    Type
    string
    Description

    Up to 64 characters each.

  • Name
    website
    Type
    string
    Description

    A full URL, such as https://example.org.

  • Name
    address
    Type
    object
    Description

    street, postalCode, city and country (two letters, defaults to de).

  • Name
    text
    Type
    string
    Description

    The public description.

POST/hosts
curl -X POST https://example.fepli.eu/api/hosts \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kunstschule Elmsbrück",
    "email": "kontakt@kunstschule.example.fepli.eu",
    "website": "https://kunstschule.example.fepli.eu",
    "address": {
      "street": "Atelierstraße 7",
      "postalCode": "12345",
      "city": "Elmsbrück"
    }
  }'

The response (201 Created) holds the new host.

PATCH/hosts/{uuid}

Update a host

Changes a host. Admins can change any host, host users their own. The attributes are the same as for creating a host; send only what you want to change. An empty body is a 422.

address is replaced as a whole: send all its fields, since the ones you leave out are cleared (and country falls back to de). "address": null removes the address.

PATCH/hosts/{uuid}
curl -X PATCH https://example.fepli.eu/api/hosts/01905a7e-8c21-7b3f-a0d4-3e9f1c6b2a02 \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phone": "0123 456789", "fax": null}'
DELETE/hosts/{uuid}

Delete a host

Deletes a host. Admins only. Responds with 204 No Content.

A host that still has offers can't be deleted (409). Move the offers to another host or delete them first.

DELETE/hosts/{uuid}
curl -X DELETE https://example.fepli.eu/api/hosts/0193c9d1-2e3f-7a4b-8c5d-6e7f8a9b0c18 \
  -H "Authorization: Bearer $FEPLI_TOKEN"
POST/hosts/{uuid}/add-member

Add a member

Makes an existing account a member of the host straight away, as the admin does when it assigns an account to a host. Admins only. No invitation and no e-mail: the person simply finds the host in the admin the next time they sign in. The account gets ROLE_HOST if it didn't have it, just like setting hosts on the account. Responds with 200 OK and the host, whose members now include the account.

To ask someone who should decide for themselves, or who has no account yet, send a host invitation instead.

An unknown account is a 422. An account you may not change is a 403: an admin's account needs a super admin, and accounts whose personal data is masked for you can't be changed. An account that is a member already is a 409.

Required attributes

  • Name
    account
    Type
    string
    Description

    The account to add, by UUID or e-mail address.

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

Response (excerpt)

{
  "uuid": "0193c9d1-2e3f-7a4b-8c5d-6e7f8a9b0c18",
  "name": "Kunstschule Elmsbrück",
  "members": [
    {
      "uuid": "0193c9e4-8f9a-7b0c-9d1e-2f3a4b5c6d21",
      "name": "Mira Schneider"
    }
  ],
  "…": "…"
}
POST/hosts/{uuid}/remove-member

Remove a member

Ends an account's access to the host, as Zugriff entziehen on the host's Team tab and Zuordnung entfernen on the account do in the admin. Admins only. The account stops being a member, and loses the single offers of this host that were shared with it (sharedOffers). Its access to other hosts stays, and so does ROLE_HOST. Nobody is notified. Responds with 200 OK and the host.

An unknown account is a 422, an account you may not change a 403. An account that has neither a membership nor a shared offer of this host is a 409.

Required attributes

  • Name
    account
    Type
    string
    Description

    The account to remove, by UUID or e-mail address.

POST/hosts/{uuid}/remove-member
curl -X POST https://example.fepli.eu/api/hosts/0193c9d1-2e3f-7a4b-8c5d-6e7f8a9b0c18/remove-member \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"account": "0193c9e4-8f9a-7b0c-9d1e-2f3a4b5c6d21"}'

Was this page helpful?