Developers & Integrations

Oakline provides a Public Sessions API to allow tenants to display their session catalogue on external websites or mobile apps. This guide assumes technical knowledge of HTTP APIs and web development.

Overview

The API is read-only and publicly accessible. It exposes:

Session Templates: Types of sessions (e.g., "Holiday Club", "Forest School").
Occurrences: Specific dates and times for these sessions.
Availability: Capacity and remaining spaces.

Important: The API does not allow booking creation. The "Book Now" action must redirect the user to your Oakline portal (e.g., https://your-name.oakline.app) to complete the secure checkout process.

Integration Options

1. Pre-built Widget (Coming Soon)

We are developing a drop-in widget that requires no coding. You simply paste a snippet of HTML into your website. Status: In Development.

2. Custom Integration (API)

Build a completely custom display using our JSON API. This offers maximum flexibility for design and user experience.

Pros:

Full control over look and feel.
SEO benefits (content appears native to your site).
No iframes or external styling conflicts.

Cons:

Requires developer implementation.

API Reference (v1)

Base URL

https://oakline.app/api/v1/public/tenants/{tenant_slug}

{tenant_slug}: Your unique Oakline subdomain identifier (e.g., forestfamilies for forestfamilies.oakline.app).

Authentication & Security

Auth: None required (Public Data).
CORS: Requests are allowed from whitelisted domains only. Please contact support to add your website's domain to the allowlist.
Data Scope: Only returns sessions marked as "Public" in the Admin Panel. No customer data is ever exposed.

1. List Sessions

Get a list of upcoming session occurrences.

Endpoint: GET /sessions

Parameters:

Name	Type	Required	Description
`from`	string	No	Start date (ISO format `YYYY-MM-DD`). Defaults to today.
`to`	string	No	End date (ISO format `YYYY-MM-DD`).
`limit`	int	No	Max results (Default: 50, Max: 200).
`cursor`	string	No	Pagination token for the next page.

Example Request:

GET /api/v1/public/tenants/forestfamilies/sessions?from=2024-06-01

Example Response:

{
  "data": [
    {
      "id": 101,
      "title": "Summer Camp",
      "start_at": "2024-06-15T09:00:00",
      "price": { "amount": 25.00, "currency": "GBP" },
      "capacity": { "total": 20, "remaining": 5, "is_full": false },
      "image_url": "https://...",
      "booking_url": "https://forestfamilies.oakline.app/booking?session_id=101"
    }
  ],
  "pagination": { "has_more": false }
}

2. Get Single Session

Get details for a specific session occurrence.

Endpoint: GET /sessions/{id}

Best Practices

Linking to Booking

When a user clicks "Book Now", you should redirect them to the booking_url provided in the API response. This ensures they land on the correct checkout page within the secure Oakline environment.

Rate Limiting

The API is subject to fair use policies.

Limit: Currently ~60 requests per minute per IP.
Exceeded: Returns 429 Too Many Requests.

Caching

Responses include ETag and Cache-Control headers.

TTL: Data is typically cached for 60 seconds.
clients should respect 304 Not Modified responses to save bandwidth.

Requesting Access

To enable the API for your tenant or whitelist your domain for CORS/Widgets:

Go to Admin > Settings > Integrations (or contact support).
Provide your Website URL where the catalogue will be hosted.
We will enable the headers for your domain.