# List free slots

`GET https://app.pozyskajpacjenta.pl/api/v1/booking/slots` · operationId `getSlots` · since 1.2.0 · tag Booking

Free slots of a service, counted live from schedules, time off and booked visits; optionally of one specialist. The range is at most 31 days. Without `resource` you get the slots of every specialist who performs the service. Responses are never cached (`Cache-Control: no-store`): availability changes live.

## Request

Authorization: `Bearer <the clinic's key>`.

### Query parameters

- `service` (`string`, required): The booking service id (catalog `services[].id`).
- `resource` (`string`): The specialist id (catalog `resources[].id`); omit for any specialist.
- `from` (`string (date)`, required): First day, a local date YYYY-MM-DD (inclusive).
- `to` (`string (date)`, required): Last day, a local date YYYY-MM-DD (inclusive).

### cURL

```bash
curl "https://app.pozyskajpacjenta.pl/api/v1/booking/slots?service=bsvc_konsultacja&resource=bres_piotr&from=2026-10-05&to=2026-10-05" \
  -H "Authorization: Bearer $PP_API_KEY"
```

### TypeScript

```ts
import { PozyskajPacjentaClient } from "@pozyskajpacjenta/sdk";

const client = new PozyskajPacjentaClient({
  apiKey: process.env.PP_API_KEY ?? "",
  baseUrl: "https://app.pozyskajpacjenta.pl",
});

const { slots } = await client.getSlots({
  serviceId: "bsvc_konsultacja",
  resourceId: "bres_piotr",
  from: "2026-10-05",
  to: "2026-10-05",
});
```

### PHP

```php
<?php
$response = wp_remote_get(
    'https://app.pozyskajpacjenta.pl/api/v1/booking/slots?service=bsvc_konsultacja&resource=bres_piotr&from=2026-10-05&to=2026-10-05',
    array(
        'headers' => array( 'Authorization' => 'Bearer ' . getenv( 'PP_API_KEY' ) ),
        'timeout' => 10,
    )
);
if ( is_wp_error( $response ) ) {
    error_log( $response->get_error_message() );
    return;
}
$status = wp_remote_retrieve_response_code( $response );
$data   = json_decode( wp_remote_retrieve_body( $response ), true );
```

## Response

### 200: Free slots, earliest first.

- `slots` (`Slot[]`, required): The slots.
  - `resourceId` (`string`, required): The specialist, an id from the catalog's `resources`.
  - `startAt` (`integer`, required): Start, epoch seconds (UTC). Send it as `startAt` to book.
  - `endAt` (`integer`, required): End, epoch seconds (UTC).
  - `localDate` (`string`, required): Local date, YYYY-MM-DD.
  - `localStartMin` (`integer`, required): Local minute of the day (e.g. 570 = 9:30).

Example (Free slots of one specialist on one day (trimmed to three)):

```json
{
  "slots": [
    {
      "resourceId": "bres_piotr",
      "startAt": 1791180000,
      "endAt": 1791181800,
      "localDate": "2026-10-05",
      "localStartMin": 480
    },
    {
      "resourceId": "bres_piotr",
      "startAt": 1791180900,
      "endAt": 1791182700,
      "localDate": "2026-10-05",
      "localStartMin": 495
    },
    {
      "resourceId": "bres_piotr",
      "startAt": 1791181800,
      "endAt": 1791183600,
      "localDate": "2026-10-05",
      "localStartMin": 510
    }
  ]
}
```

## Errors

| Status | code | When |
| --- | --- | --- |
| 400 |  | A required parameter is missing |
| 400 |  | More than 31 days |
| 400 |  | Unknown service or specialist |
| 400 | `nfz_phone_only` | An NFZ service (phone booking only) |
| 401 |  | No Authorization header |
| 401 |  | Unknown or rotated key |
| 429 |  | Over 120 requests in this minute |

400 (A required parameter is missing):

```json
{
  "error": "wymagane parametry: service, from (YYYY-MM-DD), to (YYYY-MM-DD)"
}
```

400 (More than 31 days):

```json
{
  "error": "nieprawidłowy zakres dat (max 31 dni)"
}
```

400 (Unknown service or specialist):

```json
{
  "error": "nie znaleziono usługi lub specjalisty"
}
```

400 (An NFZ service (phone booking only)):

```json
{
  "error": "usługa NFZ — rejestracja telefoniczna",
  "code": "nfz_phone_only"
}
```

401 (No Authorization header):

```json
{
  "error": "missing Authorization: Bearer <klucz z panelu Ustawienia>"
}
```

401 (Unknown or rotated key):

```json
{
  "error": "invalid key"
}
```

429 (Over 120 requests in this minute):

```json
{
  "error": "przekroczono limit 120 zapytań/min"
}
```

## Rate limit

- 120 requests per minute per key, shared by every endpoint.

## SDK method

`client.getSlots(params: { serviceId, resourceId?, from, to }): Promise<{ slots: Slot[] }>`

Throws ApiError 400; `code: "nfz_phone_only"` for an NFZ service.