# Developer Tools

APIs for partners building integrations with the Altegio platform.
**Base URL:** `https://api.alteg.io/api`
## Start here
Building your first marketplace app? Follow [Install & test your app before moderation](marketplace-quickstart.md). It explains which IDs and tokens you need, how the two-step installation works, and how to verify your first authenticated call.
To manage your own Integrations Hub application from an AI client, use the [Integrations Hub MCP](integrations-hub-mcp.md). It offers a hosted connection and plan-first tools for the application lifecycle.
## Available Methods
**Marketplace** — Manage your marketplace applications: list connected locations, configure tariffs, handle billing, process installation/uninstallation callbacks.
**Webhooks** — Configure event notifications for your integrations. Receive real-time updates when appointments, clients, or other entities change.
**VoIP Integration** — Connect telephony systems to match incoming calls with client records and log call history.
**Dictionaries** — Reference data for building forms and validations: countries, cities, business types.

Version: 1.0.0
License: Altegio API Agreement

## Servers

Production
```
https://api.alteg.io/api/v1
```

## Security

### BearerPartner

Partner API token for accessing developer endpoints

Type: http
Scheme: bearer
Bearer Format: Bearer {PartnerToken}

### BearerPartnerUser

Combined partner and user tokens for authenticated user operations

Type: http
Scheme: bearer
Bearer Format: Bearer {PartnerToken}, User {UserToken}

## Download OpenAPI description

 - [Developer Tools](https://developer.alteg.io/_bundle/en/developers/openapi.yaml)

## Marketplace

 - [POST /company/{company_id}/marketplace/applications/{application_id}/grant_access](https://developer.alteg.io/en/developers/openapi/marketplace/marketplace_location_grant_access.md): **Step 1 of the two-step installation handshake** — the location owner grants the application access to their location. Call this on behalf of the location owner (combined partner + user token). On su
 - [GET /company/{company_id}/marketplace/applications/{application_id}/permissions](https://developer.alteg.io/en/developers/openapi/marketplace/marketplace_location_application_permissions.md): Returns the permission groups declared by the application. These are the rights requested for its system user when installed on a Location. The result does not report the system user's current effecti
 - [GET /marketplace/application/{application_id}/salons](https://developer.alteg.io/en/developers/openapi/marketplace/list_marketplace_app_locations.md): This endpoint retrieves a list of locations that have connected a specific application, along with detailed information about each.
 - [GET /marketplace/application/{application_id}/tariffs](https://developer.alteg.io/en/developers/openapi/marketplace/marketplace_partner_applications_tariffs_list.md): Retrieves list of tariffs for the application. **Note:** For marketplace partners only.
 - [POST /marketplace/application/add_discount](https://developer.alteg.io/en/developers/openapi/marketplace/marketplace_partner_application_add_discount.md): Sets a payment discount for specific locations when they pay through Altegio platform. **Note:** This endpoint is intended for marketplace partners only. Requires marketplace partner authorization.
 - [GET /marketplace/application/payment_link](https://developer.alteg.io/en/developers/openapi/marketplace/marketplace_partner_application_payment_link.md): Generates a payment link for application payment through Altegio platform. A link with a non-zero `discount` is valid for 7 days. After that, the payment page rejects it and a new link must be generat
 - [POST /marketplace/application/update_channel](https://developer.alteg.io/en/developers/openapi/marketplace/marketplace_partner_applications_update_channel.md): Updates available notification channels for the application. **Note:** Only for Chat Bots and SMS Aggregators category applications. For marketplace partners only.
 - [POST /marketplace/application/new_message](https://developer.alteg.io/en/developers/openapi/marketplace/marketplace_partner_application_new_chat_message.md): Marks the installed Chat frame as having unread messages. Altegio updates the timetable UI and may create a notification-center item according to the location's Chat settings. If lead saving is enable
 - [GET /marketplace/salon/{location_id}/application/{application_id}](https://developer.alteg.io/en/developers/openapi/marketplace/get_marketplace_integration_status.md): Retrieves the application's installation status in a specific location. Use it after the installation callback to confirm that the status is `active`. For the complete owner grant → partner confirmati
 - [POST /marketplace/salon/{location_id}/application/{application_id}/uninstall](https://developer.alteg.io/en/developers/openapi/marketplace/uninstall_marketplace_app.md): This endpoint is used by the partner service to uninstall the application from a specific location.
 - [POST /marketplace/partner/callback](https://developer.alteg.io/en/developers/openapi/marketplace/marketplace_notification_settings_callback.md): **Step 2 of the two-step installation handshake** — the partner confirms the installation and delivers integration settings. > **Host:** this partner callback is served from the `https://app.alteg.io`
 - [POST /marketplace/partner/callback/redirect](https://developer.alteg.io/en/developers/openapi/marketplace/marketplace_notification_settings_redirect_callback.md): After completing registration, the user must be redirected to this URL in the browser, along with any required data needed by the partner service.
 - [POST /marketplace/partner/payment](https://developer.alteg.io/en/developers/openapi/marketplace/marketplace_notification_payment_callback.md): A webhook notification must be sent to this address to inform Altegio of a successful payment made on the partner service’s side. Not available for applications whose payments go through Altegio: Alte
 - [POST /marketplace/partner/payment/refund/{payment_id}](https://developer.alteg.io/en/developers/openapi/marketplace/marketplace_payment_refund_callback.md): Chargeback Notice Not available for payments made through Altegio checkout or for applications whose payments go through Altegio: this endpoint returns 403.
 - [POST /marketplace/partner/short_names](https://developer.alteg.io/en/developers/openapi/marketplace/set_marketplace_notification_short_names.md): This endpoint is used to send the list of SMS sender names available to the user. The user will be able to choose from any of the provided sender names.
 - [POST /marketplace_webhook](https://developer.alteg.io/en/developers/openapi/marketplace/marketplace_webhook.md): This is an example receiver path on your application backend, not an Altegio API endpoint. Altegio POSTs to the application's configured `callback_url`. It is separate from location entity `webhook_ur
## Webhooks

 - [GET /hooks_settings/{location_id}](https://developer.alteg.io/en/developers/openapi/webhooks/get_event_notification_settings.md): Read location-wide webhook settings. Requires webhook settings read access. `url_settings` contains the actual flags for each destination; the legacy top-level flags reflect only the first URL. This p
 - [POST /hooks_settings/{location_id}](https://developer.alteg.io/en/developers/openapi/webhooks/update_event_notification_settings.md): Replace the complete location-wide URL set and apply one event-flag set to every supplied destination. Omitted flags default to 0. Requires webhook settings read access and permission to edit the loca
 - [POST SalonEvent](https://developer.alteg.io/en/developers/openapi/webhooks/webhook_salon.md): Location settings changes are sent with `resource: company`. Legacy `salon` events remain compatible. The `/locations` API URL alias does not change the webhook resource name. `delete` is sent once, w
 - [POST StaffEvent](https://developer.alteg.io/en/developers/openapi/webhooks/webhook_staff.md): Sent when a team member is created, updated, or deleted. The `data` field matches the response from `GET /company/{company_id}/staff/{staff_id}`.
 - [POST ServiceEvent](https://developer.alteg.io/en/developers/openapi/webhooks/webhook_service.md): Sent when a service is created, updated, or deleted. The `data` field matches the response from `GET /company/{company_id}/services/{service_id}`.
 - [POST ServiceCategoryEvent](https://developer.alteg.io/en/developers/openapi/webhooks/webhook_service_category.md): Sent when a service category is created, updated, or deleted. The `data` field matches the response from `GET /company/{company_id}/service/categories`.
 - [POST ClientEvent](https://developer.alteg.io/en/developers/openapi/webhooks/webhook_client.md): Sent when a client is created, updated, or deleted. The `data` field contains the full client profile with all default includes.
 - [POST RecordEvent](https://developer.alteg.io/en/developers/openapi/webhooks/webhook_record.md): Sent when an appointment is created, updated, or deleted. The `data` field matches the response from `GET /record/{company_id}/{record_id}`.
 - [POST LoyaltyCardEvent](https://developer.alteg.io/en/developers/openapi/webhooks/webhook_loyalty_card.md): Sent when a loyalty card is created, updated, or deleted. Uses a simplified payload with essential fields only.
 - [POST ScheduleEvent](https://developer.alteg.io/en/developers/openapi/webhooks/webhook_schedule.md): Sent when a team member's schedule changes, including when the team member loses timetable access and their future schedules are removed. Only `update` is emitted. The existing `staff` update notifica
 - [POST GoodEvent](https://developer.alteg.io/en/developers/openapi/webhooks/webhook_good.md): Sent when a product is created, updated, or deleted. The `data` field matches the response from `GET /goods/{company_id}/{good_id}`.
 - [POST GoodsOperationEvent](https://developer.alteg.io/en/developers/openapi/webhooks/webhook_goods_operation.md): Sent when a product operation occurs: sale, receipt, consumable write-off, product write-off, or product movement. The `resource` field indicates the specific operation type: `goods_operations_sale`,
 - [POST FinancesOperationEvent](https://developer.alteg.io/en/developers/openapi/webhooks/webhook_finances_operation.md): Sent when a financial transaction is created, updated, or deleted. May optionally include `payment_system_transaction_ids` if the feature is enabled for the location.
## VoIP Integration

 - [POST /voip/integration](https://developer.alteg.io/en/developers/openapi/voip-integration/handle_voip_integration_event.md): #### Enable integration To use the api and activate access to the settings in the user interface, you need to activate the integration by sending the "Enable integration" request. After a successful c
 - [GET /voip/integration/calls](https://developer.alteg.io/en/developers/openapi/voip-integration/list_voip_calls.md): This endpoint is designed to get a list of calls in a location, taking into account filters and pagination
## Dictionaries

 - [GET /countries](https://developer.alteg.io/en/developers/openapi/dictionaries/get_country_list.md)
 - [GET /cities](https://developer.alteg.io/en/developers/openapi/dictionaries/get_city_list.md)
 - [GET /references/business_groups_with_types](https://developer.alteg.io/en/developers/openapi/dictionaries/get_business_types_by_group.md)