Skip to content
/
Create an Online Booking

Online Booking (1.0.0)

Public API for client-facing online booking integration. This API enables third-party developers to embed online booking functionality into external platforms such as business catalogs, branded apps, and partner services. Base URL: https://api.alteg.io/api

Authentication

All requests require partner authorization via Bearer token in the HTTP header: Authorization: Bearer <partner_token> To obtain a partner token, register in the Altegio Marketplace.

Rate Limits

  • 200 requests per minute per IP address - 5 requests per second per IP address
Download OpenAPI description
openapi.json
openapi.yaml
Overview
License
Altegio API Agreement
Terms of Service
Languages
Servers
Mock server
https://developer.alteg.io/_mock/en/public/openapi/
Production server
https://api.alteg.io/api/v1/

Authentication

User authentication and verification endpoints for online booking

Operations

Online Booking

Endpoints for booking form, services, staff, availability, and appointment management

Operations

Validate Booking Parameters

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:

FieldTypeMandatoryDescription
appointmentsArray of objectsYESBooking options (services, team members...)

The appointments array consists of objects that have the following fields:

FieldTypeMandatoryDescription
idnumberYesAppointment ID for post-save feedback (see response to request).
servicesarray of numbersNOArray of IDs of the services the client wants to sign up for
staff_idnumberYESID of the team member the client wants to book with (0 if any team member is selected)
datetimedatetimeYESSession 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:

  1. Selected time slot is already taken. Returned with HTTP status code 422 and error code 433.

  2. 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.

  3. 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.

  4. 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.

Security
BearerPartner
Path
location_idnumberrequired

location ID

Headers
Acceptstringrequired

e.g. application/vnd.api.v2+json

Example: application/vnd.api.v2+json
Content-Typestringrequired

application/json

Authorizationstringrequired

Bearer partner_token

Bodyapplication/jsonrequired
appointmentsArray of objectsrequired

appointment options (services, team members...)

Example: [{"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"}]
curl -i -X POST \
  'https://developer.alteg.io/_mock/en/public/openapi/book_check/{location_id}' \
  -H 'Accept: application/vnd.api.v2+json' \
  -H 'Authorization: Bearer <YOUR_Bearer {PartnerToken}_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"
      }
    ]
  }'

Responses

Created

Bodyapplication/json
successboolean

Execution success status (true)

Example: true
datanull

Always null for this response

metaobject

metadata

Example: {"message":"Created"}
Response
application/json
{
  "success": true,
  "meta": {
    "message": "Created"
  }
}

Create an Online Booking

Request

To create a session appointment, provide a JSON object containing the online booking parameters. The object includes the following fields:

FieldTypeMandatoryDescription
phonestringYESClient's phone number (eg +13155550175)
full namestringYESClient name
emailstringNOPostal address of the client
appointmentsArray of objectsYESBooking options (services, team members...)
codestringNOPhone number confirmation code sent via SMS (only needed if you need to confirm the number)
notify_by_smsnumberNONumber of hours in advance to send an SMS reminder for the appointment (set to 0 to disable reminders).
notify_by_emailnumberNONumber of hours in advance to send an email reminder for the appointment (set to 0 to disable the reminder).
commentstringNOAppointment Comment
api_idstringNOExternal Appointment ID

The appointments array consists of objects that have the following fields:

FieldTypeMandatoryDescription
idnumberYesAppointment ID for post-save feedback (see response to request).
servicesarray of numbersNOArray of IDs of the services the client wants to sign up for
staff_idnumberYESID of the team member the client wants to book with (0 if any team member is selected)
datetimedatetimeYESSession date and time in ISO8601 format (passed for each session in the book_times resource)
custom_fieldskey-value objectNOCustom 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:

FieldTypeDescription
idnumberThe appointment ID as passed in the original appointments array
record_idnumberThe unique identifier of the appointment created in the system
record_hashstringA temporary ID used for deleting the appointment immediately after creation

Errors to be handled:

  1. Incorrect SMS verification code. Returned with HTTP status 422 and error code 432. The SMS verification code entered by the user is invalid.

  2. 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.

  3. 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.

  4. Invalid phone number format. Returned with HTTP status 422 and error code 431. The user's phone number is not in a valid format.

  5. Missing client name. Returned with HTTP status 422 and error code 435. The client's name was not provided.

  6. 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).

  7. 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.

Security
BearerPartner
Path
location_idnumberrequired

location ID

Headers
Acceptstringrequired

e.g. application/vnd.api.v2+json

Example: application/vnd.api.v2+json
Content-Typestringrequired

application/json

Authorizationstringrequired

Bearer partner_token

Bodyapplication/jsonrequired
fullnamestringrequired

Client name

Example: "James Smith"
phonestringrequired

Customer phone

Example: "+13155550175"
emailstring

Postal address of the client

Example: "j.smith@example.com"
codenumber

SMS confirmation code for verifying the phone number. This field is required if the location has phone_confirmation = true

Example: 38829
commentstring

Commentary on the post

Example: "test appointment!"
typestring

Appointment source

Example: "mobile"
notify_by_smsnumber

Specifies how many hours before the visit an SMS reminder should be sent to the client. Set to 0 if no reminder is needed.

Example: 6
notify_by_emailnumber

Specifies how many hours before the visit an email reminder should be sent to the client. Set to 0 if no reminder is needed.

Example: 24
api_idnumber

Appointment ID from external system

Example: 777
appointmentsArray of objects

Appointment options (session, services, team member)

Example: [{"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"]}}]
curl -i -X POST \
  'https://developer.alteg.io/_mock/en/public/openapi/book_record/{location_id}' \
  -H 'Accept: application/vnd.api.v2+json' \
  -H 'Authorization: Bearer <YOUR_Bearer {PartnerToken}_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"
          ]
        }
      }
    ]
  }'

Responses

Created

Bodyapplication/json
successboolean

Execution success status (true)

Example: true
dataArray of objects

Data (array of objects)

Example: [{"id":1,"record_id":2820023,"record_hash":"567df655304da9b98487769426d4e76e"},{"id":2,"record_id":2820024,"record_hash":"34a45ddabdd446d5d33bdd27fbf855b2"}]
metaArray of objects

Metadata (empty array)

Example: []
Response
application/json
{
  "success": true,
  "data": [
    { … },
    { … }
  ],
  "meta": []
}

Get Online Booking Details

Request

Security
BearerPartner
Path
location_idnumberrequired

location ID

record_idnumberrequired

Post ID (enough to view the post if the user is logged in)

Example: 22123
record_hashstringrequired

HASH appointments (required to view the appointment if the user is not authorized)

Example: 'dawd4fs09rhf0s9fafef0'
Headers
Acceptstringrequired

e.g. application/vnd.api.v2+json

Example: application/vnd.api.v2+json
Content-Typestringrequired

application/json

Authorizationstringrequired

Bearer partner_token, User user_token

curl -i -X GET \
  'https://developer.alteg.io/_mock/en/public/openapi/book_record/{location_id}/22123/'\''dawd4fs09rhf0s9fafef0'\''' \
  -H 'Accept: application/vnd.api.v2+json' \
  -H 'Authorization: Bearer <YOUR_Bearer {PartnerToken}_HERE>' \
  -H 'Content-Type: string'

Responses

OK

Bodyapplication/json
idnumber

Appointment ID

Example: 13132699
servicesArray of objects

Service ID List

Example: [{"id":389043,"title":"Correction of extended nails","cost":2300,"price_min":2300,"price_max":2300,"discount":0,"amount":1,"seance_length":1800}]
companyobject

location parameters

Example: {"id":4564,"title":"Nail studio","country_id":7,"country":"United States","city_id":2,"city":"New York","phone":"+13155550175","phones":[],"timezone":"12","address":"New York, 787 Jackson Drive","coordinate_lat":40.73061,"coordinate_lon":-73.935242,"allow_delete_record":true,"allow_change_record":true,"site":"www.example.com","currency_short_title":"USD","allow_change_record_delay_step":0,"allow_delete_record_delay_step":0}
staffobject

team member parameters

Example: {"id":55436,"name":"Natalie Parker","specialization":"Team Member in manicure and pedicure","position":{"id":446,"title":"Manicurist"},"show_rating":1,"rating":4.84,"votes_count":0,"avatar":"http://example.com/image.png","comments_count":37}
clients_countinteger(int32)
Example: 1
datestring(date-time)

04-02T12:00:00Z' (required, string) - Session date

Example: "2026-09-21T23:00:00.000-05:00"
datetimestring(date-time)

Session date in ISO

Example: "2026-10-24T17:30:00-0500"
create_datestring(date-time)

04-02T12:00:00Z' (required, string) - Appointment creation date

Example: "2026-10-20T21:40:24-0500"
commentstring

Appointment Comment

deletedboolean

Whether the appointment was made (true if removed)

Example: true
attendancenumber

2 - the user confirmed the appointment, 1 - the user came, the services were provided, 0 - the user was waiting, -1 - the user did not show'

lengthnumber

Session duration

Example: 1800
notify_by_smsnumber

Specifies how many hours in advance an SMS reminder should be sent before the appointment. Set to 0 to disable SMS reminders

notify_by_emailnumber

Specifies how many hours in advance an email reminder should be sent before the appointment. Set to 0 to disable email reminders

master_requestedboolean

Indicates whether a specific team member was selected for the appointment. Set to false if the "any team member" option was chosen.

onlineboolean

Indicates whether the appointment was created online by the client (true) or manually by an administrator (false)

Example: true
api_idstring

External appointment ID

last_change_datestring(date-time)

The date and time when the appointment was last modified

Example: "2026-10-24T23:54:02-0500"
prepaidboolean

Indicates whether online payment is available for the appointment

prepaid_confirmedboolean

Online payment status

activity_idnumber

group event ID

Response
application/json
{
  "id": 13132699,
  "services": [
    { … }
  ],
  "company": {
    "id": 4564,
    "title": "Nail studio",
    "country_id": 7,
    "country": "United States",
    "city_id": 2,
    "city": "New York",
    "phone": "+13155550175",
    "phones": [],
    "timezone": "12",
    "address": "New York, 787 Jackson Drive",
    "coordinate_lat": 40.73061,
    "coordinate_lon": -73.935242,
    "allow_delete_record": true,
    "allow_change_record": true,
    "site": "www.example.com",
    "currency_short_title": "USD",
    "allow_change_record_delay_step": 0,
    "allow_delete_record_delay_step": 0
  },
  "staff": {
    "id": 55436,
    "name": "Natalie Parker",
    "specialization": "Team Member in manicure and pedicure",
    "position": { … },
    "show_rating": 1,
    "rating": 4.84,
    "votes_count": 0,
    "avatar": "http://example.com/image.png",
    "comments_count": 37
  },
  "clients_count": 1,
  "date": "2026-09-21T23:00:00.000-05:00",
  "datetime": "2026-10-24T17:30:00-0500",
  "create_date": "2026-10-20T21:40:24-0500",
  "comment": "",
  "deleted": true,
  "attendance": 0,
  "length": 1800,
  "notify_by_sms": 0,
  "notify_by_email": 0,
  "master_requested": false,
  "online": true,
  "api_id": "",
  "last_change_date": "2026-10-24T23:54:02-0500",
  "prepaid": false,
  "prepaid_confirmed": false,
  "activity_id": 0
}

Client Personal Cabinet

Client account management and booking history

Operations