Plinth
Plinth

Endpoints

Bookings

Bookings API Documentation

Overview

The Bookings API allows you to retrieve booking information for events, including associated member profile data. This API supports filtering, pagination, and selective field retrieval.

Endpoint

GET /api/v1/bookings

Authentication

This endpoint requires authentication via either:

  • API Key: Pass your API key in the x-api-key header

Query Parameters

Required Parameters

  • organisationId (string) - Required for Firebase authentication. The ID of the organisation whose bookings you want to retrieve.

Optional Parameters

Filtering

You can filter bookings by any field in the booking document. Common filters include:

  • eventId (string) - Filter bookings for a specific event
  • date (string) - Filter bookings for a specific date (format: YYYY-MM-DD)
  • memberId (string) - Filter bookings for a specific member
  • attending (boolean) - Filter by attendance status (true/false)
  • userStatus (string) - Filter by user status
  • orgStatus (string) - Filter by organisation status
  • bookingType (string) - Filter by booking type

Multiple filters can be combined in a single request.

Pagination

  • limit (number) - Maximum number of bookings to return (default: 100, max: 250)
  • offset (number) - Number of bookings to skip for pagination (default: 0)

Profile Fields Selection

  • profileFields (string) - Comma-separated list of profile field IDs to include in the response
    • Default fields: "Full Name", "Postcode", "Email", "Phone"
    • The profileId is always included regardless of this parameter
    • Field IDs must match exactly as defined in your organisation's schema
    • To get available field IDs, use the Schemas API endpoint (see below)

Response Format

Success Response (200 OK)

{
  "bookings": [
    {
      "bookingId": "abc123def456",
      "managedBy": "org123",
      "date": "2025-01-20",
      "eventId": "event789",
      "memberId": "member456",
      "funderMemberId": null,
      "slotId": null,
      "ticketId": null,
      "ticketName": null,
      "ticketSeries": null,
      "funderProgrammeId": null,
      "name": "John Smith Booking",
      "type": "individual",
      "user": "user123",
      "userEmail": "john.smith@example.com",
      "userName": "John Smith",
      "userStatus": "confirmed",
      "orgStatus": "approved",
      "attending": true,
      "bookingType": "standard",
      "booker": "member456",
      "created": "2025-01-15T10:30:00.000Z",
      "updated": "2025-01-15T10:30:00.000Z",
      "start": "2025-01-20T14:00:00.000Z",
      "end": "2025-01-20T16:00:00.000Z",
      "duration": 120,
      "orderId": null,
      "childEventId": null,
      "customPrice": null,
      "profile": {
        "memberId": "profile789",
        "fields": [
          {
            "key": "profileId",
            "label": "Profile ID",
            "value": "profile789",
            "type": "string"
          },
          {
            "key": "Full Name",
            "label": "Full Name",
            "value": "John Smith",
            "type": "string"
          },
          {
            "key": "Postcode",
            "label": "Postcode",
            "value": "SW1A 1AA",
            "type": "string"
          },
          {
            "key": "Email",
            "label": "Email Address",
            "value": "john.smith@example.com",
            "type": "string"
          },
          {
            "key": "Phone",
            "label": "Phone Number",
            "value": "+44 20 7123 4567",
            "type": "string"
          }
        ]
      }
    }
  ],
  "offset": 0,
  "limit": 100,
  "total": 1
}

Error Responses

400 Bad Request

Returned when:

  • Invalid date format provided (must be YYYY-MM-DD)
  • Missing organisation ID for Firebase users

401 Unauthorized

Returned when:

  • Invalid or missing authentication credentials
  • Firebase user not authorised for the specified organisation

500 Internal Server Error

Returned when:

  • Organisation schema is unavailable
  • Database errors occur

Usage Examples

Example 1: Get all bookings with default profile fields

curl -X GET "https://www.plinth.org.uk/api/v1/bookings?organisationId=org123" \
  -H "x-api-key: your-api-key"

Example 2: Get bookings for a specific event

curl -X GET "https://www.plinth.org.uk/api/v1/bookings?organisationId=org123&eventId=event789" \
  -H "x-api-key: your-api-key"

Example 3: Get bookings for a specific date

curl -X GET "https://www.plinth.org.uk/api/v1/bookings?organisationId=org123&date=2025-01-20" \
  -H "x-api-key: your-api-key"

Example 4: Get bookings with custom profile fields

curl -X GET "https://www.plinth.org.uk/api/v1/bookings?organisationId=org123&profileFields=Full Name,Email,Date of Birth,Emergency Contact" \
  -H "x-api-key: your-api-key"

Example 5: Combine multiple filters with pagination

curl -X GET "https://www.plinth.org.uk/api/v1/bookings?organisationId=org123&eventId=event789&attending=true&limit=50&offset=0" \
  -H "x-api-key: your-api-key"

Example 6: Get bookings for a specific member with minimal profile data

curl -X GET "https://www.plinth.org.uk/api/v1/bookings?organisationId=org123&memberId=member456&profileFields=Email" \
  -H "x-api-key: your-api-key"

Example 7: Using Firebase authentication

curl -X GET "https://www.plinth.org.uk/api/v1/bookings?organisationId=org123" \
  -H "Authorization: Bearer your-firebase-token"

Getting Available Field IDs

To discover which field IDs are available for use in the profileFields parameter, use the Schemas API:

Schemas Endpoint

GET /api/v1/schemas/{organisationId}

Example: Get Schema Information

curl -X GET "https://www.plinth.org.uk/api/v1/schemas/org123" \
  -H "x-api-key: your-api-key"

Schema Response Example

{
  "schema": {
    "organisationId": "org123",
    "schemaId": "master",
    "name": "Master Schema",
    "fields": [
      {
        "id": "Full Name",
        "name": "Full Name",
        "label": "Full Name",
        "type": "text",
        "order": 1
      },
      {
        "id": "Email",
        "name": "Email",
        "label": "Email Address",
        "type": "email",
        "order": 2
      },
      {
        "id": "Phone",
        "name": "Phone",
        "label": "Phone Number",
        "type": "phone",
        "order": 3
      },
      {
        "id": "Postcode",
        "name": "Postcode",
        "label": "Postcode",
        "type": "text",
        "order": 4
      },
      {
        "id": "Date of Birth",
        "name": "Date of Birth",
        "label": "Date of Birth",
        "type": "date",
        "order": 5
      }
    ]
  }
}

Use the id field from each field definition when specifying the profileFields parameter in your bookings API request.

Notes

  1. Timestamps: All timestamp fields are returned in ISO 8601 format (e.g., "2025-01-15T10:30:00.000Z")

  2. Field IDs: When using the profileFields parameter, ensure you use the exact field IDs as defined in your organisation's schema. These are case-sensitive and can be obtained from the Schemas API endpoint.

  3. Performance: For better performance when dealing with large datasets:

    • Use specific filters to reduce the result set
    • Limit the profile fields to only what you need
    • Use pagination to retrieve data in chunks

  4. Rate Limiting: This API may be subject to rate limiting. Check response headers for rate limit information.

  5. Data Types: When filtering with query parameters:

    • Boolean values: Use "true" or "false" (case-insensitive)
    • Numbers: Will be automatically parsed
    • Strings: Used as-is

Support

For additional support or to report issues, please contact your system administrator or refer to the main API documentation.

Previous
Recurrence
Next
Programmes