# Using Postman

Import any Bookable OpenAPI specification into Postman to explore endpoints, test requests, and prototype integrations without writing code first.

## Available specs

| Spec | Download |
|  --- | --- |
| TMS Gateway API | [OperatorApi.yml](https://bookable.redocly.app/_spec/apis/OperatorApi.yml?download) |
| Bookings API | [BookingApi.yml](https://bookable.redocly.app/_spec/apis/BookingApi.yml?download) |
| Register Webhook Events | [WebhookApi.yml](https://bookable.redocly.app/_spec/apis/WebhookApi.yml?download) |
| Handling Webhook Events | [BookableWebhookApi.yaml](https://bookable.redocly.app/_spec/apis/BookableWebhookApi.yaml?download) |


All specs follow the OpenAPI 3.0 format and can be imported into Postman individually or together.

## Import a spec

1. Open **Postman** and click **Import** (`Ctrl+O` / `⌘+O`).
2. Choose how you want to import:
  - **File** — download the YAML file from the repository and upload it directly
  - **Link** — paste the raw URL of the spec file
3. Click **Continue**, then **Import**.


Postman will create a new collection with all endpoints, request bodies, and parameter schemas pre-populated.

Repeat for each spec you want to import. You can keep them as separate collections or merge them.

## Configure collection variables

After importing, set up collection-level variables so every request shares the same base URL and credentials. These variables apply to any Bookable collection.

1. Click the collection name in the left panel.
2. Go to the **Variables** tab.
3. Add the following variables:


| Variable | Initial value | Description |
|  --- | --- | --- |
| `baseUrl` | `https://api-sandbox.bookabletech.com` | Switch to `https://api.bookabletech.com` for production |
| `clientId` | *(your client_id)* | From the [Bookable Portal](https://portal.bookabletech.com) |
| `clientSecret` | *(your client_secret)* | From the [Bookable Portal](https://portal.bookabletech.com) |
| `accessToken` | *(leave blank)* | Populated automatically by the pre-request script |


1. Click **Save**.


If a collection's requests use a hardcoded base URL after import, update them to `{{baseUrl}}`.

## Pre-request script for automatic token refresh

Add this script to the **Pre-request Script** tab of any Bookable collection. It automatically fetches and caches a token before every request, refreshing it when it is about to expire.


```javascript
// Bookable — auto token refresh pre-request script

const tokenUrl = pm.variables.get('baseUrl')
  .replace('api-sandbox', 'auth-sandbox')
  .replace('api.bookabletech', 'auth.bookabletech')
  + '/oauth/token';

const tokenExpiresAt = pm.collectionVariables.get('tokenExpiresAt');
const accessToken = pm.collectionVariables.get('accessToken');

// Reuse cached token if still valid (with 60s buffer)
if (accessToken && tokenExpiresAt && Date.now() < parseInt(tokenExpiresAt) - 60000) {
  return;
}

pm.sendRequest(
  {
    url: tokenUrl,
    method: 'POST',
    header: { 'Content-Type': 'application/json' },
    body: {
      mode: 'raw',
      raw: JSON.stringify({
        grant_type: 'client_credentials',
        client_id: pm.variables.get('clientId'),
        client_secret: pm.variables.get('clientSecret'),
        audience: 'api.bookabletech.com',
      }),
    },
  },
  (err, response) => {
    if (err) { console.error('Token fetch error:', err); return; }
    const body = response.json();
    pm.collectionVariables.set('accessToken', body.access_token);
    pm.collectionVariables.set('tokenExpiresAt', String(Date.now() + body.expires_in * 1000));
  }
);
```

The script derives the correct auth URL from `baseUrl` automatically, so it works for both sandbox and production without changes.

## Set up the Authorization header

1. Click the collection name and go to the **Authorization** tab.
2. Set **Type** to **Bearer Token**.
3. Set **Token** to `{{accessToken}}`.
4. Click **Save**.


All requests in the collection inherit this setting. Individual requests can override it if needed.

## Switching between sandbox and production

Update the `baseUrl` variable on the collection to switch environments. The pre-request script and auth URL update automatically.

| Environment | `baseUrl` |
|  --- | --- |
| Sandbox | `https://api-sandbox.bookabletech.com` |
| Production | `https://api.bookabletech.com` |


## Related

- [Authentication](/getting-started/auth) — OAuth 2.0 token flow and code examples
- [API Reference](/apis/production/bookingapi) — OpenAPI specs
- [Quickstart](/getting-started/quickstart) — make your first booking