API for external management systems

1. What the APIs allow

With an API key you can, from your software, read and write to the calendar of your venues:

• read venues and courts with their identifiers, which are required for all other calls;
• read bookings for a period, a venue or a single court, to align them with your database;
• create bookings externally (for example when a customer books from your website), with the same overlap and panel closure checks;
• modify or cancel an existing booking (change of time or court, payment collection, notes, cancellation);
• read the availability of a court on a given day: slots already booked, opening hours and extraordinary closures, so you can offer free slots without replicating the rules;
• read the price list of a court to show prices to the end customer.

Organisers' requests for court use in tournaments (approved from the app), the creation of facilities and courts, and the saving of timetables, closures and price lists are not part of these APIs: these are operations of the manager panel.

2. Requirements and activation

1. A VolleyFriends court manager account with at least one facility and one court.
2. An active subscription with a plan that includes the 'API for external management systems' feature. The entire v1 — even read-only requests — is reserved for those who have this feature: it is a paid feature, not an add-on of the panel.
3. An API key generated from the management panel: admin.volleyfriends.com → Settings → API Keys → New key.

The key has the format vfk_ followed by 40 hexadecimal characters (44 characters in total) and is shown only once, immediately after creation: only its sha256 hash remains in the database, so it cannot be recovered in any way. If you lose it, revoke it and generate a new one. In the panel list you only see the prefix (e.g. vfk_9f2c), the creation date and the last used date.

3. Authentication

Each request must be authenticated with the X-Api-Key header. No tokens, logins, expirations or renewals are needed: the key remains valid until you revoke it.

# The keys on this page are examples: replace with your own.
curl -s https://www.volleyfriends.com/api/manager-api/v1/venues   -H "X-Api-Key: vfk_9f2c41a7b83d05e6c19af4728b60d35e1c9a7f42"

In the following examples, the key is read from the VF_API_KEY environment variable, as should also be done in production.

Header missing, shorter than 12 characters, unknown or belonging to a revoked key: the response is 401 with this body.

{
  "error": "invalid_key",
  "message": "Chiave API mancante o non valida (header X-Api-Key)."
}

4. Base URL

https://www.volleyfriends.com/api

The paths documented below must be appended to the base. The /api prefix belongs to the reverse proxy, so the full address of an endpoint is, for example:

GET https://www.volleyfriends.com/api/manager-api/v1/availability

All responses are application/json with UTF-8 encoding. Requests with a body (POST, PATCH) must have Content-Type: application/json.

5. Rate limiting

The limit is 120 requests per minute per API key (1-minute sliding window). The count is per key, not per IP address: management systems are often behind the same provider address and an IP-based limit would penalise different managers hosted on the same infrastructure. If the X-Api-Key header is missing entirely, the count falls back to the IP address.

Every response reports the status of the counter in the x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset headers (seconds to reset). When exceeded, retry-after is also added.

Response when exceeded — 429

{
  "error": "rate_limited",
  "message": "Limite di 120 richieste al minuto superato per questa chiave API."
}

6. Endpoints

Six endpoints, all under /manager-api/v1. Every call goes through the same chain of checks, in order: valid API key → "API for external management systems" feature included in the plan → rate limit → parameter validation → verification that the resource is yours.

6.1 Venues and courts

Lists your venues, each with its own nested courts. This is the starting call: the court ids (courtId) are needed for all other endpoints. Venues are ordered by name, courts by name.

Parameters

None.

Example request

curl -s https://www.volleyfriends.com/api/manager-api/v1/venues   -H "X-Api-Key: $VF_API_KEY"

Example response — 200

{
  "venues": [
    {
      "id": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
      "name": "Centro Sportivo Aurora",
      "city": "Verona",
      "address": "Via delle Palestre 12",
      "verified": true,
      "courts": [
        {
          "id": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
          "venueId": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
          "name": "Campo 1",
          "surface": "parquet",
          "indoor": true,
          "lighting": true
        },
        {
          "id": "e2a71f64-9c03-4bd8-b512-38f6cd90a7e1",
          "venueId": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
          "name": "Campo 2 beach",
          "surface": "sabbia",
          "indoor": false,
          "lighting": true
        }
      ]
    }
  ]
}

Response fields

If the account has no venues yet, the response is {"venues": []}.

Specific errors

None other than the general ones.

6.2 Bookings list

Returns the bookings of your venues, sorted by ascending start time. The list is paginated: maximum limit rows per call (default 500, cap 1000) — if you receive exactly limit rows, call again with an increased offset for the next page. In production, always filter by date range at least.

Parameters (query string)

Example request

curl -s -G https://www.volleyfriends.com/api/manager-api/v1/bookings   -H "X-Api-Key: $VF_API_KEY"   --data-urlencode "courtId=7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05"   --data-urlencode "from=2026-08-01"   --data-urlencode "to=2026-08-31"

Example response — 200

{
  "bookings": [
    {
      "id": "9d51c7b4-0e28-4f3a-a6d9-72b48e105c3f",
      "venueId": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
      "courtId": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
      "courtName": "Campo 1",
      "startsAt": "2026-08-12T16:00:00.000Z",
      "endsAt": "2026-08-12T17:30:00.000Z",
      "customerName": "Marta Bellini",
      "customerPhone": "+39 340 1122334",
      "customerEmail": "marta.bellini@example.com",
      "priceCents": 3000,
      "playersCount": null,
      "status": "confirmed",
      "paymentMethod": null,
      "paymentLink": null,
      "notes": "Prenotato dal sito della struttura",
      "source": "api",
      "recurrenceId": null,
      "createdAt": "2026-07-28T09:14:02.517Z",
      "updatedAt": "2026-07-28T09:14:02.517Z"
    }
  ],
  "limit": 500,
  "offset": 0
}

Booking fields

The same structure is returned by POST and PATCH (inside the booking key).

Specific errors

6.3 New booking

Creates a booking on one of your courts. The booking is created with source: "api", so it can be distinguished in the panel from those entered manually, and the manager receives a "New booking" push notification on the app.

The same rules as the panel are applied, in order:

1. extraordinary closure of the venue on the start date → 409 venue_closed;
2. overlap with another non-cancelled booking on the same court → 409 overlap;
3. price missing → calculated from the court's price list (null if the start time does not fall within any slot). If the slot has a price per person, playersCount is also required: without it, the request is rejected with 400 players_required (unless an explicit priceCents is specified).

The opening hours do not block creation: they are informative, the manager remains in full control of their court. If you want to prevent out-of-hours bookings, check the hours returned by /availability before calling the POST.

Request body (JSON)

Example request

curl -s -X POST https://www.volleyfriends.com/api/manager-api/v1/bookings   -H "X-Api-Key: $VF_API_KEY"   -H "Content-Type: application/json"   -d '{
    "courtId": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
    "startsAt": "2026-08-12T18:00:00+02:00",
    "endsAt": "2026-08-12T19:30:00+02:00",
    "customerName": "Marta Bellini",
    "customerPhone": "+39 340 1122334",
    "customerEmail": "marta.bellini@example.com",
    "notes": "Prenotato dal sito della struttura"
  }'

Response example — 201

{
  "booking": {
    "id": "9d51c7b4-0e28-4f3a-a6d9-72b48e105c3f",
    "venueId": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
    "courtId": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
    "courtName": "Campo 1",
    "startsAt": "2026-08-12T16:00:00.000Z",
    "endsAt": "2026-08-12T17:30:00.000Z",
    "customerName": "Marta Bellini",
    "customerPhone": "+39 340 1122334",
    "customerEmail": "marta.bellini@example.com",
    "priceCents": 3000,
    "playersCount": null,
    "status": "confirmed",
    "paymentMethod": null,
    "paymentLink": null,
    "notes": "Prenotato dal sito della struttura",
    "source": "api",
    "recurrenceId": null,
    "createdAt": "2026-07-28T09:14:02.517Z",
    "updatedAt": "2026-07-28T09:14:02.517Z"
  }
}

In the example, priceCents was not specified: 90 minutes in a 20,00 €/hour slot results in 3000 cents (the calculation is proportional to the actual minutes, using the rate of the slot in which the booking starts).

Specific errors

// 409 — overlap
{ "error": "overlap", "message": "Il campo è già prenotato in quell'orario." }

// 409 — extraordinary closure (the reason, if specified by the manager, is in the message)
{ "error": "venue_closed", "message": "Struttura chiusa in quella data (manutenzione)." }

6.4 Update booking

Updates an existing booking. It is a partial update: send only the fields that change, the others remain unchanged. The body must contain at least one field.

There is no deletion endpoint: to cancel a booking, set status: "cancelled". The history remains in the panel and the slot becomes free again (cancelled bookings do not occupy the court and do not generate overlap).

Path parameter

Request body (JSON)

All fields are optional. Those marked "nullable" accept null to clear the value.

Example request — rescheduling and revenue

curl -s -X PATCH   https://www.volleyfriends.com/api/manager-api/v1/bookings/9d51c7b4-0e28-4f3a-a6d9-72b48e105c3f   -H "X-Api-Key: $VF_API_KEY"   -H "Content-Type: application/json"   -d '{
    "startsAt": "2026-08-12T19:00:00+02:00",
    "endsAt": "2026-08-12T20:30:00+02:00",
    "status": "paid",
    "paymentMethod": "cash",
    "priceCents": 3000
  }'

Example request — cancellation

curl -s -X PATCH   https://www.volleyfriends.com/api/manager-api/v1/bookings/9d51c7b4-0e28-4f3a-a6d9-72b48e105c3f   -H "X-Api-Key: $VF_API_KEY"   -H "Content-Type: application/json"   -d '{ "status": "cancelled" }'

Example response — 200

The updated booking, in the same format as the POST:

{
  "booking": {
    "id": "9d51c7b4-0e28-4f3a-a6d9-72b48e105c3f",
    "venueId": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
    "courtId": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
    "courtName": "Campo 1",
    "startsAt": "2026-08-12T17:00:00.000Z",
    "endsAt": "2026-08-12T18:30:00.000Z",
    "customerName": "Marta Bellini",
    "customerPhone": "+39 340 1122334",
    "customerEmail": "marta.bellini@example.com",
    "priceCents": 3000,
    "playersCount": null,
    "status": "paid",
    "paymentMethod": "cash",
    "paymentLink": null,
    "notes": "Prenotato dal sito della struttura",
    "source": "api",
    "recurrenceId": null,
    "createdAt": "2026-07-28T09:14:02.517Z",
    "updatedAt": "2026-07-28T11:02:47.883Z"
  }
}

Specific errors

6.5 Court availability on a day

Returns, for a court and a day, the occupied slots, the opening hours for that day of the week, and any extraordinary closure. This is the endpoint to use to calculate free slots on an external site without duplicating the management system's rules: subtract bookings from the opening window.

All slots occupying the court are listed, in any status except cancelled: therefore including online booking requests that are still pending. The day is the local Italian day and the intervals are half-open: a booking ending exactly at midnight belongs to the previous day. A booking spanning midnight appears in both days it intersects, with its actual times (which may fall outside the requested day).

Parameters (query string)

Example request

curl -s -G https://www.volleyfriends.com/api/manager-api/v1/availability   -H "X-Api-Key: $VF_API_KEY"   --data-urlencode "courtId=7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05"   --data-urlencode "date=2026-08-12"

Example response — 200

{
  "courtId": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
  "venueId": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
  "date": "2026-08-12",
  "timezone": "Europe/Rome",
  "hours": {
    "weekday": 2,
    "openMinute": 540,
    "closeMinute": 1380,
    "closed": false,
    "configured": true
  },
  "closure": null,
  "bookings": [
    {
      "startsAt": "2026-08-12T16:00:00.000Z",
      "endsAt": "2026-08-12T17:30:00.000Z",
      "status": "confirmed"
    },
    {
      "startsAt": "2026-08-12T18:00:00.000Z",
      "endsAt": "2026-08-12T19:00:00.000Z",
      "status": "paid"
    },
    {
      "startsAt": "2026-08-12T19:00:00.000Z",
      "endsAt": "2026-08-12T20:30:00.000Z",
      "status": "pending"
    }
  ]
}

Response fields

Specific errors

6.6 Court rates

The court rates in read-only mode: used to show prices to the customer before booking, with the same time slots that the management system uses to calculate the automatic price. Time slots can only be modified from the dashboard. They are sorted by ascending fromMinute.

Parameters (query string)

Example request

curl -s -G https://www.volleyfriends.com/api/manager-api/v1/rates   -H "X-Api-Key: $VF_API_KEY"   --data-urlencode "courtId=7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05"

Example response — 200

{
  "courtId": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
  "rates": [
    {
      "id": "4a1e0b72-6d35-4c81-93af-0b7e2d5814c6",
      "label": "Mattina infrasettimanale",
      "daysMask": 31,
      "fromMinute": 480,
      "toMinute": 840,
      "pricePerHourCents": 1500,
      "pricingMode": "court",
      "minPlayers": null
    },
    {
      "id": "c07d9b31-8f42-4a05-b6e9-15d3c8017a2b",
      "label": "Serale",
      "daysMask": 127,
      "fromMinute": 1080,
      "toMinute": 1380,
      "pricePerHourCents": 600,
      "pricingMode": "person",
      "minPlayers": 10
    }
  ]
}

Response fields

Specific errors

A court without a price list returns 200 with "rates": [].

7. Data conventions

7.1 Dates and times

• Inbound timestamps are ISO 8601 strings with a mandatory offset: 2026-08-12T18:00:00+02:00 or 2026-08-12T18:00:00Z. A string without an offset (2026-08-12T18:00:00) is rejected with 400: it would be ambiguous, and for a calendar, this ambiguity results in bookings being off by an hour.
• Outbound timestamps are always normalized to UTC with a Z suffix and milliseconds: "2026-08-12T16:00:00.000Z". Convert them to the local time zone before displaying them.
• Plain dates (date, closure.from, closure.to, and from/to when used in day format) are AAAA-MM-GG and refer to the local Italian day.
• Intervals are half-open [inizio, fine): 18:00–19:00 and 19:00–20:00 are not in conflict.

7.2 Time zone

Bookings are stored as absolute timestamps, but all calendar rules — day of the week, price list tiers, opening hours, closing dates, day boundaries — are evaluated in the Europe/Rome time zone, with daylight saving time handled automatically. The timezone field in the /availability response explicitly declares this. If your server runs in UTC or another time zone, do not manually convert the minutes: they are already expressed in local Italian time.

7.3 Minutes from midnight

"Calendar" times (openMinute, closeMinute, fromMinute, toMinute) are integers from 0 to 1440 counting the minutes from local midnight. Conversions: ore = ⌊m / 60⌋, minuti = m mod 60.

7.4 Amounts

All amounts are integers in euro cents (priceCents, pricePerHourCents): no floating-point values, no currency symbols. 2000 = 20,00 €. On a booking, priceCents: null means "price to be defined" and is different from 0, which means "free of charge".

7.5 Booking statuses

7.6 Source and payment method

Both are text domains: new values may be added in the future without changing the version, so your code must not fail on an unknown value.

7.7 Customers' personal data

Name, phone number and email that you send in the bookings are personal data of your customers: you are the data controller, VolleyFriends stores them on your behalf as a data processor pursuant to art. 28 GDPR. Only send what is necessary for court management and inform your customers. Details can be found in the privacy policy.

8. General errors

Every error has the same body: a stable code in error, designed for your code, and a message in Italian, designed for people. Base your decisions on error and the HTTP status, not on the message text, which may change.

{
  "error": "overlap",
  "message": "Il campo è già prenotato in quell'orario."
}

Validation errors add issues, the detailed list of problems field by field:

{
  "error": "invalid_input",
  "message": "Dati non validi",
  "issues": [
    {
      "code": "invalid_string",
      "validation": "datetime",
      "path": ["startsAt"],
      "message": "Invalid datetime"
    }
  ]
}

A non-existent path under the base returns 404; the same applies to an unsupported method on an existing path:

{
  "error": "not_found",
  "message": "Risorsa non trovata"
}

The 502, 503 and 504 responses come from the reverse proxy when the API is unreachable (restart or maintenance): in those cases the body is not guaranteed to be in JSON format. Treat them as temporary errors and retry with backoff, without attempting to read their content.

9. Versions and compatibility

The version is in the path: /manager-api/v1. There are no version headers or release dates to specify: the only version currently published is v1.

What we can change without notifying you

• Adding fields to existing responses.
• Adding optional parameters to requests, with a default value that preserves the current behaviour.
• Adding new endpoints under /v1.
• Adding values to open text fields (source, paymentMethod, surface).
• Reformulating the message of errors, keeping the error codes unchanged.

What does not change within v1

• No fields will be removed or renamed from responses.
• No fields will change type or meaning.
• No parameters that are currently optional will become mandatory.
• The error codes and HTTP statuses documented here remain the same.

Any change that breaks these guarantees will arrive on a new prefix (/v2), with v1 kept in service and advance notice given to the managers using it.

Changelog

10. Integration support

For technical questions, unexpected behaviour or requests for endpoints not found here, write to us from the Contact page. To get straight to the point, please include in your message:

• the endpoint and method you are calling;
• the date and time of the call (including timezone) and the HTTP code received;
• the error code and response message;
• the prefix of the key used (e.g. vfk_9f2c).

If you need to test the integration without affecting the live calendar, create a test venue with a dedicated court and use that: all calls are restricted to the venues of the key owner, so the rest of your account is not affected.