Wingfield Logo
Wingfield Partner API
Booking

List court bookings

GET
/api/v1/external-services/{externalServiceId}/court-bookings

List bookings for an external service.

Sorting: updatedAt desc, id asc. Only non-deleted bookings are returned.

Path Parameters

externalServiceId*string

External service ID (UUID).

Formatuuid

Query Parameters

offset?integer

Number of items to skip.

Default0
Range0 <= value
limit?integer

Maximum number of items to return.

Default50
Range1 <= value <= 100
courtId?string

Optional exact-match filter by court ID.

Formatuuid
externalCourtBookingId?string

Optional exact-match filter by external booking ID.

from?string

Optional ISO 8601 timestamp lower bound.

Formatdate-time
to?string

Optional ISO 8601 timestamp upper bound.

Formatdate-time
updatedFrom?string

Optional lower bound for updated timestamp.

Formatdate-time
updatedTo?string

Optional upper bound for updated timestamp.

Formatdate-time
participantUserId?string

Optional filter for bookings containing this connected user ID.

Formatuuid
participantEmail?string

Optional filter for bookings containing this guest email.

Formatemail

Response

200

Error Responses

400

invalid_schema

Request validation failed.

400

invalid_filter_time_range

A filter time range is ordered incorrectly.

400

invalid_updated_filter_time_range

An updated-at filter range is ordered incorrectly.

401

missing_api_token

No authentication token provided.

401

invalid_api_token

Invalid or expired authentication token.

403

scope_permission_denied

Insufficient permissions for this operation.

403

external_service_access_denied

Token does not match the requested external service.

curl -X GET "https://dev.wingfield.systems/api/v1/external-services/497f6eca-6276-4993-bfeb-53cbbbba6f08/court-bookings"
{
  "items": [
    {
      "externalServiceId": "e8623a0d-39de-4963-9c6c-a25dc38e89c9",
      "courtId": "79ae2927-a9bc-46ed-8f9e-079af32b7616",
      "externalCourtBookingId": "string",
      "startDate": "2019-08-24T14:15:22Z",
      "endDate": "2019-08-24T14:15:22Z",
      "externalUpdatedAt": "2019-08-24T14:15:22Z",
      "participants": [
        {
          "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b"
        }
      ],
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "totalCount": 0
}
{
  "error": {
    "type": "invalid_schema",
    "message": "string",
    "issues": [
      {}
    ]
  }
}
{
  "error": {
    "type": "missing_api_token",
    "message": "string"
  }
}
{
  "error": {
    "type": "scope_permission_denied",
    "message": "string"
  }
}

Get court booking by external ID GET

Get one booking for service + external booking id. Deleted bookings return `404 court_booking_not_found`.

Upsert court booking PUT

Create or update a booking by external booking id with stale-write protection. Notes: - `participants` must contain 1 to 4 unique entries. - Each participant must contain exactly one of `userId` or `email`. - `email` is normalized to lowercase. - Equal `externalUpdatedAt` is idempotent only when the payload is otherwise unchanged. - Overlapping active bookings on the same court are rejected.