End-customer authentication methods. Get access tokens required for some API operations.
- Validate Booking Parameters
Altegio REST API (1.0.1)
This is an official document describing the interaction with the Altegio business managment platform. API allows third-party developers to perform most operations with the Altegio data. When designing methods, we tried to adhere to the REST architecture.
- All interaction with protocol are transpire by TLS encryption (from 1.2 version)
- Limits are
200requests per minute or5requests per second per IP address - URL API:
https://api.alteg.io/apiIf you encounter difficulties when working with the API, please carefully review the documentation, including the required headers, parameters, and the structure of the request body in the JSON example.
If you're having trouble resolving the issue on your own, feel free to contact us at api@alteg.io. Please include the request URL, headers, request body, and the response you received in your message.
The API uses URL path versioning. Currently available versions:
- V1 (
/v1/...) - Stable, full-featured API - V2 (/v2/...) - New endpoints with improved design Both versions are production-ready. New features may be released in V2 only. V1 endpoints are maintained for backward compatibility. Base URL:https://api.alteg.io/apiExample requests: - V1:GET https://api.alteg.io/api/v1/companies- V2:GET https://api.alteg.io/api/v2/companies/{id}/tags
- Data exchange with automation, accounting or CRM software
- Integration of Online Booking into third-party websites and mobile applications. Allows embedding of Online Booking forms into external platforms, such as business catalogs, branded apps, and other partner services.
- Data collection and analysis for business intelligence systems / Development of custom reporting and analytics tools
- Chat bots and virtual assistants for appointment scheduling and client management
The Altegio integration API includes two groups of methods:
- Methods that require both user authorization and partner authorization
- Methods that require partner authorization only (no user authorization)
The most of dates in the API are represented as strings in ISO 8601 format. Exluding cases specified otherwise in outdated or deprecated methods.
"2026-09-21T23:00:00.000-05:00"Service durations and other time-related values are provided in seconds. For example, a 15-minute service should be represented as:
{ "length": 900 }The API allows to work with most of the platform's entities. However, please note that there are inconsistencies in the technical terminology: method and variable names, as well as terminology, may differ between the user interface and the documentation
A Location is an individual business unit that operates within the platform. Each Location belongs to a Chain. For single-location businesses, the platform still creates a single-location Chain.
Also known as: company, branch, filial, salon
A Chain is a group of multiple Locations managed as a single business network. Chain-level settings, promotions, service catalogs, and loyalty rules may be inherited by all child Locations while each Location can still override them where needed.
Also known as: groups, networks, salon_groups
A User is an account that provides authenticated access to one or more Locations. Access scope is defined by Roles, which are predefined sets of Access Rights. If a User does not have access to a module or method, the API returns HTTP 403. Users can also be linked to Chains, which provide a different set of access rights and are required for certain Chain-level requests. Each User is linked to one Team Member within a Location and may be linked to different Team Members across multiple Locations. Operational context (available Services, Schedule, permissions) depends on the current Location and Team Member binding. Most API methods require the User to be authorised (a valid token obtained) and to have explicit access to the target Location.
A Team Member is an individual within a Location who participates in operational processes: provides Services within Appointments, creates or manages reservations, or works with financial and analytical data (for example, a professional, cashier, administrator, or accountant). Team Members do not directly define access rights in the API, but they determine the business role and workload of a person inside a Location. Positions are logical groups of Team Members (similar to folders) that help structure staff by departments, functions, or specialisation. In some configurations, Positions are used to filter available reports.
Also known as: employee, staff, staff_member, master
Resources are limited items required to provide Services (rooms, chairs, devices, machines). A Resource cannot be used in parallel for multiple Appointments; it is reserved when a Service linked to that Resource is booked.
A Schedule is a set of time intervals during which a Team Member or Resource is available to provide Services. A Time Slot is a specific available interval within the Schedule that can be booked online for an Appointment with a Team Member.
An Appointment is a scheduled time interval during which a specific Team Member provides one or more Services or sells Products to a specific Client. A Visit is a group of one or more Appointments that take place during a single Client presence at a Location. Grouping rules depend on the Location settings.
Also known as: record, booking
An Event is a scheduled time slot for a group Service where multiple Clients can book simultaneously. Unlike individual Appointments, an Event has a capacity limit defining the maximum number of participants. Events are used for group classes, workshops, webinars, and any service that can serve multiple Clients at the same time with a single Team Member.
Also known as: activity, group event
A Client is an individual who books, receives, or has received Services or Products from a Location. Client data is used for scheduling, communication, and analytics.
A Service is a predefined type of work or procedure that can be provided to a Client by a Team Member within a Location. Each Service has key parameters such as duration, price (or price range), and applicable resources. Service Categories are logical groups used to organise Services for configuration, reporting, and client-facing catalogs.
A Product is a tangible or consumable item that can be sold to a Client or used as part of a Service. Product Categories are logical groups used to organise Products for inventory management, reporting, and sales operations.
Also known as: goods, items
Inventories represent physical or logical Warehouses used to store and track Products and consumables. Inventory operations (receipts, write-offs, transfers) ensure that product usage in Visits is reflected in stock levels and financial reports.
Also known as: storages, warehouses
Suppliers and Partners are counterparties used in Inventory and Finance modules to track product purchases, settlements, and mutual transactions with external companies.
Also known as: partners
Location Accounts are accounts (cash registers or bank accounts) attached to a specific Location. They are used to record payments for Visits, product sales, and other financial operations, and they define how money flows are grouped in financial reports.
Also known as: cashdesks, cash registers
Payment methods define how payments are recorded in the system (cash, card, bank transfer, online acquiring, loyalty instruments). Each method is linked to specific Accounts and can have its own commission and reporting logic.
Payroll rules define how staff compensation is calculated based on Visits, Products, Memberships, tips, and other metrics. They describe commission schemes, fixed payments, and deductions.
A Client Card is a unified profile that stores balances, active memberships, certificates, and participation in loyalty programs for a specific Client across one Location or an entire Chain.
A Membership is a prepaid product that gives a Client the right to receive a set number of services or discounts over a defined period. Membership Types define the rules: which services are included, how many visits are available, validity period, and usage restrictions. Also known as: abonements
A Certificate is a prepaid value or service voucher that can be used to pay for Services and Products. Certificate Types define how certificates are sold, accounted for, and redeemed, including validity period and usage restrictions.
Loyalty programs combine bonus accrual, cumulative discounts and referral promotions to increase repeat visits and average spend. Any loyalty instrument must be linked to a specific Client Card so that bonuses, discounts, and balances are applied consistently across Visits.
Client Accounts are internal balances (deposits) stored on the Client Card. They are used to prepay future Visits, store overpayments, or keep store credit that can be partially or fully redeemed in subsequent Visits and sales.
Also known as: deposits
Subdivisions are higher-level groups used to organise Services across a Chain (for example, "Hair", "Nails", "Spa"). They help structure large catalogs, simplify analytics, and control visibility of Services in online booking.
Custom fields are additional attributes configured by the Location to store extra data in Visits or other entities (for example, medical notes, internal IDs). They extend the standard schema without changing the core data model.
Also known as: additional fields
Integrations HUB is a catalog of external applications and services connected to Altegio (telephony, messaging, CRM, loyalty, etc.). It standardises how integrations are discovered, installed, configured, and monetised.
Request
The sessions available for booking object has the following fields:
| Field | Type | Description |
|---|---|---|
| time | string | Session time (17:30 for example) |
| session_length | number | Session duration in seconds |
| datetime | datetime | Date and time of the session in ISO8601 format (must be passed when creating the appointment) |
The following filters are available:
- service_ids: Array of service IDs. If you need sessions, when can you book these services
- Mock serverhttps://developer.alteg.io/_mock/en/v1/book_times/{location_id}/{team_member_id}/{date}
- https://api.alteg.io/api/v1/book_times/{location_id}/{team_member_id}/{date}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://developer.alteg.io/_mock/en/v1/book_times/{location_id}/{team_member_id}/{date}?service_ids%5B%5D=string' \
-H 'Accept: application/vnd.api.v2+json' \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: string'OK
Array of objects with data
{ "success": true, "data": [ { … }, { … }, { … }, { … }, { … } ], "meta": [] }
Request
After generating the appointment parameters, you can validate them to ensure the appointment can be successfully created.
The JSON object containing the Online Booking parameters includes the following fields:
| Field | Type | Mandatory | Description |
|---|---|---|---|
| appointments | Array of objects | YES | Booking options (services, team members...) |
The appointments array consists of objects that have the following fields:
| Field | Type | Mandatory | Description |
|---|---|---|---|
| id | number | Yes | Appointment ID for post-save feedback (see response to request). |
| services | array of numbers | NO | Array of IDs of the services the client wants to sign up for |
| staff_id | number | YES | ID of the team member the client wants to book with (0 if any team member is selected) |
| datetime | datetime | YES | Session date and time in ISO8601 format (passed for each session in the book_times resource) |
In response to the parameter check request, an empty response with the code 201 will be returned if the booking parameters are in order and bookings can be created:
If the response is JSON with an HTTP code other than 201, then the booking parameters are out of order, and bookings cannot be created.
The server may return the following errors during appointment creation:
Selected time slot is already taken. Returned with HTTP status code 422 and error code 433.
No team members available for booking. Occurs if a default team member was selected but none are available. Returned with HTTP status code 422 and error code 436.
Booking time conflict within the same request. One of the selected booking times overlaps with another booking created in the same request. Returned with HTTP status code 422 and error code 437, including the conflicting booking’s id in the appointments array.
Service not available for booking The selected service is no longer available (e.g. removed by the location). Returned with HTTP status code 422 and error code 438.
- Mock serverhttps://developer.alteg.io/_mock/en/v1/book_check/{location_id}
- https://api.alteg.io/api/v1/book_check/{location_id}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
'https://developer.alteg.io/_mock/en/v1/book_check/{location_id}' \
-H 'Accept: application/vnd.api.v2+json' \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"appointments": [
{
"id": 1,
"services": [
331
],
"staff_id": 6544,
"datetime": "2026-09-21T23:00:00.000-05:00"
},
{
"id": 2,
"services": [
99055
],
"staff_id": 6544,
"datetime": "2026-09-21T23:00:00.000-05:00"
}
]
}'{ "success": true, "meta": { "message": "Created" } }
Request
To create a session appointment, provide a JSON object containing the online booking parameters. The object includes the following fields:
| Field | Type | Mandatory | Description |
|---|---|---|---|
| phone | string | YES | Client's phone number (eg +13155550175) |
| full name | string | YES | Client name |
| string | NO | Postal address of the client | |
| appointments | Array of objects | YES | Booking options (services, team members...) |
| code | string | NO | Phone number confirmation code sent via SMS (only needed if you need to confirm the number) |
| notify_by_sms | number | NO | Number of hours in advance to send an SMS reminder for the appointment (set to 0 to disable reminders). |
| notify_by_email | number | NO | Number of hours in advance to send an email reminder for the appointment (set to 0 to disable the reminder). |
| comment | string | NO | Appointment Comment |
| api_id | string | NO | External Appointment ID |
The appointments array consists of objects that have the following fields:
| Field | Type | Mandatory | Description |
|---|---|---|---|
| id | number | Yes | Appointment ID for post-save feedback (see response to request). |
| services | array of numbers | NO | Array of IDs of the services the client wants to sign up for |
| staff_id | number | YES | ID of the team member the client wants to book with (0 if any team member is selected) |
| datetime | datetime | YES | Session date and time in ISO8601 format (passed for each session in the book_times resource) |
| custom_fields | key-value object | NO | Custom field values that are returned with the appointment |
Custom fields in the appointments array
When custom appointment fields are created (see the "Custom Fields" section), you can pass custom values for them during appointment creation. These fields are unique to each location. Once the custom fields are set up, their values can be included in the optional custom_fields parameter. This should be passed as a key–value object, where each key corresponds to the code of the custom field. Example:
- location created an custom appointment field with code="my_custom_field" type="number", and a second field code="some_another_field" type="list"
- When creating an appointment, another attribute was passed in the appointments array element: "" appointments: [{ ... }, { ... custom_fields: { "my_custom_field": 123, "some_another_field": ["first value", "second value"] } }]"
- When this appointment is received by the GET method later, the same value of custom fields will be returned in the response
In response to the request to create an appointment, an array of objects will come (the number of objects is equal to the number of objects in the appointments array) with the following fields:
| Field | Type | Description |
|---|---|---|
| id | number | The appointment ID as passed in the original appointments array |
| record_id | number | The unique identifier of the appointment created in the system |
| record_hash | string | A temporary ID used for deleting the appointment immediately after creation |
Errors to be handled:
Incorrect SMS verification code. Returned with HTTP status 422 and error code 432. The SMS verification code entered by the user is invalid.
Selected time slot is already taken. Returned with HTTP status 422 and error code 433. The selected appointment time is unavailable. The response includes the id of the conflicting appointment from the appointments array.
User is blacklisted. Returned with HTTP status 403 and error code 434. The user with the specified phone number is blacklisted and cannot book an appointment.
Invalid phone number format. Returned with HTTP status 422 and error code 431. The user's phone number is not in a valid format.
Missing client name. Returned with HTTP status 422 and error code 435. The client's name was not provided.
No available team members. Returned with HTTP status 422 and error code 436. No team members are available at the selected time (commonly occurs when using a default team member setting).
Overlapping appointments in request. Returned with HTTP status 422 and error code 437. One of the selected times overlaps with another appointment in the same request. The response includes the id of the conflicting appointment from the appointments array.
SMS confirmation code for verifying the phone number. This field is required if the location has phone_confirmation = true
Specifies how many hours before the visit an SMS reminder should be sent to the client. Set to 0 if no reminder is needed.
Specifies how many hours before the visit an email reminder should be sent to the client. Set to 0 if no reminder is needed.
Appointment options (session, services, team member)
- Mock serverhttps://developer.alteg.io/_mock/en/v1/book_record/{location_id}
- https://api.alteg.io/api/v1/book_record/{location_id}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
'https://developer.alteg.io/_mock/en/v1/book_record/{location_id}' \
-H 'Accept: application/vnd.api.v2+json' \
-H 'Authorization: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"phone": "+13155550175",
"fullname": "James Smith",
"email": "j.smith@example.com",
"code": 38829,
"comment": "test appointment!",
"type": "mobile",
"notify_by_sms": 6,
"notify_by_email": 24,
"api_id": 777,
"appointments": [
{
"id": 1,
"services": [
331
],
"staff_id": 6544,
"datetime": "2026-09-21T23:00:00.000-05:00",
"custom_fields": {
"my_custom_field": 123,
"some_another_field": [
"first value",
"next value"
]
}
},
{
"id": 2,
"services": [
99055
],
"staff_id": 6544,
"datetime": "2026-09-21T23:00:00.000-05:00",
"custom_fields": {
"my_custom_field": 456,
"some_another_field": [
"next value",
"last value"
]
}
}
]
}'{ "success": true, "data": [ { … }, { … } ], "meta": [] }
Locations
Locations in the product knowledge base
Location management. Create, read, update locations and their settings.
Services
Services in the product knowledge base
Service and service category management. Define services offered by your locations.
Team Members
Team members in the product knowledge base · Positions in the product knowledge base
Team member management, including positions, service assignments, and team member profiles.
Clients
Clients in the product knowledge base
Client management including search, bulk operations, files, comments, and visit history.
Users & Permissions
Users in the product knowledge base
User account management, roles, permissions, and invitations. Control access to location features.
Appointments
Visits in the product knowledge base
Appointment and visit management.
Key concepts:
- Appointment (record) — A single scheduled service for a client with a specific team member at a specific time
- Visit — A container that groups multiple appointments when a client books several services in one session
Example: Client books haircut + coloring → 1 visit containing 2 appointments
This section covers creating, modifying, and managing both individual appointments and visit containers.
Events
Events in the product knowledge base
Manage Events — scheduled time slots for group Services where multiple Clients can book simultaneously. Create, update, search, and duplicate Events with customizable capacity, duplication strategies, and Team Member assignments.
Schedule & Resources
Schedule in the product knowledge base · Resources in the product knowledge base
Work schedules, available time slots, resources, and timetable management for team members and facilities.
Products
Products in the product knowledge base
Product catalog management. Define products available for sale and organize them into categories.
Inventory
Inventory in the product knowledge base
Stock management including storage locations, inventory documents, stock movements, and consumables tracking.
Payments
Payment methods in the product knowledge base · Accounts in the product knowledge base
Financial operations including location accounts, payment transactions, and all monetary movements.
Deposits
Client accounts in the product knowledge base
Client deposit account management and operations.
Loyalty Cards
Client cards in the product knowledge base
Loyalty card management including card types, manual transactions, and card assignments.
Subscriptions & Certificates
Memberships in the product knowledge base · Certificates in the product knowledge base
Membership and certificate management including creation, freezing, and balance operations.
Loyalty Programs
Loyalty programs in the product knowledge base
Loyalty programs and loyalty transaction management.
Salary
Payroll in the product knowledge base
Salary calculations, payroll management, and compensation tracking for team members.
Custom Fields
Custom fields in the product knowledge base
Additional custom field definitions for extending entity data structures.
Chain Management
Chains in the product knowledge base
Chain-level operations for managing multiple locations within a business chain.
Chain Loyalty Programs
Loyalty programs in the product knowledge base
Chain-level loyalty program management including programs, transactions, and message templates.
Marketplace
Integrations in the product knowledge base
Application marketplace integration for third-party applications.
Integration workflow:
- Partner provides domain name, registration URL, and callback URL
- User authorizes and is redirected to partner registration page
- Partner redirects back to Altegio after successful registration
- Partner confirms service activation via payment callback