# Bookings

Appointments the AI booked into your calendar or field-service software. Needs `bookings:read`.

Base URL: `https://vocenya.com/api/public/v1`. Authenticate with `Authorization: Bearer $VOCENYA_API_KEY`.

- [List bookings](#list-bookings): `GET /bookings`
- [Get a booking](#get-booking): `GET /bookings/{booking}`

## List bookings

`GET https://vocenya.com/api/public/v1/bookings`

Required scope: `bookings:read`

Appointments the AI booked, most recently booked first. Filter by appointment time.

### Query parameters

- `starts_after` (string (date-time), optional): Appointments starting at or after this time (ISO 8601).
- `starts_before` (string (date-time), optional): Appointments starting before this time (ISO 8601).
- `per_page` (integer, optional): How many items per page, 1 to 100. Minimum 1. Maximum 100.
- `cursor` (string or null, optional): The `meta.next_cursor` (or `meta.prev_cursor`) of the previous page. Up to 1024 characters.

### Responses

- `200`: Paginated set of `BookingResource`
- `401`: The API key is missing, invalid, expired or revoked.
- `403`: The key does not have the `bookings:read` scope.
- `422`: Validation error
- `429`: Too many requests for this key. Wait for the `Retry-After` seconds.

### Response attributes (200)

- `data` (array of objects, required)
  - `id` (integer, required)
  - `livemode` (boolean, required): `true` for live data, `false` for test data (created with a `vk_test_` key).
  - `provider` (string, required): The calendar or software the appointment was booked into. One of: `google_calendar`, `microsoft_calendar`, `jobber`, `housecall_pro`, `servicetitan`, `acuity`.
  - `external_reference` (string or null, required): The appointment's id in that calendar or software.
  - `starts_at` (string, required)
  - `duration_minutes` (integer, required)
  - `name` (string or null, required)
  - `phone_number` (string or null, required)
  - `call_id` (integer or null, required)
  - `outbound_call_id` (integer or null, required)
  - `created_at` (string or null, required)
- `links` (object, required)
  - `first` (string or null, required)
  - `last` (string or null, required)
  - `prev` (string or null, required)
  - `next` (string or null, required)
- `meta` (object, required)
  - `path` (string or null, required): Base path for paginator generated URLs.
  - `per_page` (integer, required): Number of items shown per page. Minimum 0.
  - `next_cursor` (string or null, required): The "cursor" that points to the next set of items.
  - `prev_cursor` (string or null, required): The "cursor" that points to the previous set of items.

### Example request

```bash
curl https://vocenya.com/api/public/v1/bookings \
  -H "Authorization: Bearer $VOCENYA_API_KEY"
```

```javascript
const response = await fetch('https://vocenya.com/api/public/v1/bookings', {
  headers: {
    Authorization: `Bearer ${process.env.VOCENYA_API_KEY}`,
  },
});

const data = await response.json();
console.log(data);
```

```php
$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://vocenya.com/api/public/v1/bookings', [
    'headers' => ['Authorization' => 'Bearer '.getenv('VOCENYA_API_KEY')],
]);

$data = json_decode((string) $response->getBody(), true);
print_r($data);
```

```python
import os

import requests

response = requests.get(
    "https://vocenya.com/api/public/v1/bookings",
    headers={"Authorization": f"Bearer {os.environ['VOCENYA_API_KEY']}"},
)

print(response.json())
```

### Example response (200)

```json
{
  "data": [
    {
      "id": 1,
      "livemode": true,
      "provider": "google_calendar",
      "external_reference": "string",
      "starts_at": "2026-10-02T14:03:11+00:00",
      "duration_minutes": 1,
      "name": "Maria Rivera",
      "phone_number": "+15125550123",
      "call_id": 1,
      "outbound_call_id": 1,
      "created_at": "2026-10-02T14:03:11+00:00"
    }
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "path": "string",
    "per_page": 1,
    "next_cursor": "string",
    "prev_cursor": "string"
  }
}
```


## Get a booking

`GET https://vocenya.com/api/public/v1/bookings/{booking}`

Required scope: `bookings:read`

### Path parameters

- `booking` (integer, required): The booking id.

### Responses

- `200`: `BookingResource`
- `401`: The API key is missing, invalid, expired or revoked.
- `403`: The key does not have the `bookings:read` scope.
- `404`: No record with that id belongs to your account.
- `429`: Too many requests for this key. Wait for the `Retry-After` seconds.

### Response attributes (200)

- `data` (object, required)
  - `id` (integer, required)
  - `livemode` (boolean, required): `true` for live data, `false` for test data (created with a `vk_test_` key).
  - `provider` (string, required): The calendar or software the appointment was booked into. One of: `google_calendar`, `microsoft_calendar`, `jobber`, `housecall_pro`, `servicetitan`, `acuity`.
  - `external_reference` (string or null, required): The appointment's id in that calendar or software.
  - `starts_at` (string, required)
  - `duration_minutes` (integer, required)
  - `name` (string or null, required)
  - `phone_number` (string or null, required)
  - `call_id` (integer or null, required)
  - `outbound_call_id` (integer or null, required)
  - `created_at` (string or null, required)

### Example request

```bash
curl https://vocenya.com/api/public/v1/bookings/64 \
  -H "Authorization: Bearer $VOCENYA_API_KEY"
```

```javascript
const response = await fetch('https://vocenya.com/api/public/v1/bookings/64', {
  headers: {
    Authorization: `Bearer ${process.env.VOCENYA_API_KEY}`,
  },
});

const data = await response.json();
console.log(data);
```

```php
$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://vocenya.com/api/public/v1/bookings/64', [
    'headers' => ['Authorization' => 'Bearer '.getenv('VOCENYA_API_KEY')],
]);

$data = json_decode((string) $response->getBody(), true);
print_r($data);
```

```python
import os

import requests

response = requests.get(
    "https://vocenya.com/api/public/v1/bookings/64",
    headers={"Authorization": f"Bearer {os.environ['VOCENYA_API_KEY']}"},
)

print(response.json())
```

### Example response (200)

```json
{
  "data": {
    "id": 1,
    "livemode": true,
    "provider": "google_calendar",
    "external_reference": "string",
    "starts_at": "2026-10-02T14:03:11+00:00",
    "duration_minutes": 1,
    "name": "Maria Rivera",
    "phone_number": "+15125550123",
    "call_id": 1,
    "outbound_call_id": 1,
    "created_at": "2026-10-02T14:03:11+00:00"
  }
}
```