Log in Register
Partner API

Integration

Integrate The Receptionist booking into your platform. Use our API from PHP, Laravel, CodeIgniter, React, Node.js, Python, and more.

1

How to get your API key

  1. Log in to The Receptionist as a Super Admin.
  2. Go to Partner API in the sidebar (or log in first).
  3. Click "Create API Key" and give it a name (e.g. "My Mobile App", "Website Integration").
  4. Copy the key immediately – it is shown only once and cannot be retrieved later.
  5. Store the key securely (environment variables, secrets manager). Never expose it in client-side code.
Log in to get API key
2

Base URL and authentication

All API requests use this base URL. Include your API key in every request.

https://thereceptionist.saavatar.click/api/v1/partners
Send your API key in one of these ways:
  • Authorization: Bearer YOUR_API_KEY
  • X-API-Key: YOUR_API_KEY
  • ?api_key=YOUR_API_KEY (query parameter)
3

Integration flow (3 steps)

To complete a booking from your platform, follow these three API calls:

1. Search merchants

Find businesses by city, zipcode, service type, and date.

2. Get slots

Get available time slots for the chosen merchant and service.

3. Create booking

Create the booking with customer details.

API reference

GET /merchants

Search for merchants by location, service, and date.

Parameters:

  • city – City name (required if zipcode not provided)
  • zipcode – Postal code (required if city not provided)
  • service – Service keywords (e.g. haircut, massage)
  • date – Date in Y-m-d format
  • limit – Max results (optional, default 10)

Example request:

GET https://thereceptionist.saavatar.click/api/v1/partners/merchants?city=Espoo&zipcode=02600&service=haircut&date=2026-03-20
Authorization: Bearer YOUR_API_KEY

Example response:

{
  "merchants": [
    {
      "merchant_profile_id": 12,
      "company_name": "Salon Example",
      "address": "Main St 1, 02600",
      "city": "Espoo",
      "zipcode": "02600",
      "services": [
        {"id": 5, "name": "Haircut", "duration": 30, "price": 25.00}
      ]
    }
  ]
}

GET /merchants/{id}/slots

Get available time slots for a merchant and service.

Parameters: service_id, date

GET https://thereceptionist.saavatar.click/api/v1/partners/merchants/12/slots?service_id=5&date=2026-03-20
Authorization: Bearer YOUR_API_KEY

Example response:

{
  "slots": [
    {"time": "09:00", "staff_id": null, "staff_name": null},
    {"time": "09:30", "staff_id": 3, "staff_name": "Anna"}
  ]
}

POST /bookings

Create a booking. Send JSON in the request body.

Body parameters:

  • merchant_profile_id, service_id – Required
  • staff_id – Optional, use when slot has staff_id
  • starts_at_date, starts_at_time – Required
  • customer_email – Required
  • customer_name, customer_phone – Optional
POST https://thereceptionist.saavatar.click/api/v1/partners/bookings
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "merchant_profile_id": 12,
  "service_id": 5,
  "staff_id": null,
  "starts_at_date": "2026-03-20",
  "starts_at_time": "09:30",
  "customer_email": "customer@example.com",
  "customer_name": "John Doe",
  "customer_phone": "+358401234567"
}

Code examples

Works with PHP, CodeIgniter, Laravel, React, Node.js, Python, and any platform that can send HTTP requests.

$apiKey = getenv('RECEPTIONIST_API_KEY');
$ch = curl_init('https://thereceptionist.saavatar.click/api/v1/partners/merchants?city=Espoo&service=haircut&date=2026-03-20');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Accept: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
$data = json_decode($response, true);

$client = \Config\Services::curlrequest();
$response = $client->get('https://thereceptionist.saavatar.click/api/v1/partners/merchants', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('RECEPTIONIST_API_KEY'),
        'Accept' => 'application/json',
    ],
    'query' => ['city' => 'Espoo', 'service' => 'haircut', 'date' => '2026-03-20'],
]);
$data = json_decode($response->getBody(), true);

use Illuminate\Support\Facades\Http;

$response = Http::withToken(config('services.receptionist.api_key'))
    ->get('https://thereceptionist.saavatar.click/api/v1/partners/merchants', [
        'city' => 'Espoo',
        'service' => 'haircut',
        'date' => '2026-03-20',
    ]);
$data = $response->json();

const res = await fetch(
  `https://thereceptionist.saavatar.click/api/v1/partners/merchants?city=Espoo&service=haircut&date=2026-03-20`,
  {
    headers: {
      'Authorization': `Bearer ${process.env.REACT_APP_API_KEY}`,
      'Accept': 'application/json',
    },
  }
);
const data = await res.json();
// Note: Never expose API keys in client-side code. Use a backend proxy.

import requests
import os

r = requests.get(
    'https://thereceptionist.saavatar.click/api/v1/partners/merchants',
    headers={
        'Authorization': f'Bearer {os.environ["RECEPTIONIST_API_KEY"]}',
        'Accept': 'application/json',
    },
    params={'city': 'Espoo', 'service': 'haircut', 'date': '2026-03-20'},
)
data = r.json()

Best practices

  • Store API keys in environment variables or a secrets manager. Never commit them to version control.
  • Never expose API keys in client-side code (React, Vue, etc.). Use a backend server to make API calls.
  • Use HTTPS for all requests.
  • Handle errors gracefully. The API returns 401 for invalid keys and 422 for validation errors.
  • Create separate API keys for different environments (development, staging, production).
Log in to get started