# Business Management

Next-generation B2B API with improved design and consistency.

**Base URL:** `https://api.alteg.io/api/v2`

## Status

This API is in active development. New features and improvements are released here first.
We recommend using this API for all new integrations.

## Authentication

Requires both partner and user authorization:
```
Authorization: Bearer <partner_token>, User <user_token>
```

## URL Patterns

The API uses two URL patterns:
- `/companies/{company_id}/...` - company-level resources (positions, tags)
- `/locations/{location_id}/...` - location-specific resources (services, team members, appointments, products)


Version: 2.0.0
License: Altegio API Agreement

## Servers

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

## Security

### bearer

Type: apiKey
In: header
Name: Authorization

### user

Type: apiKey
In: header
Name: Authorization

### BearerPartner

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

### BearerPartnerUser

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

## Download OpenAPI description

[Business Management](https://developer.alteg.io/_bundle/en/b2b-v2/openapi.yaml)

## Services

Service catalog management.

Retrieve services and service categories for a location.


### List Services

 - [GET /locations/{location_id}/services](https://developer.alteg.io/en/b2b-v2/openapi/services/list_services.md): Retrieve all services for a location, optionally filtered by service IDs.

Supports pagination and includes for related data.

Available includes:
- category - Service category details
- staff - Staff members who provide this service

### Get Service

 - [GET /locations/{location_id}/services/{service_id}](https://developer.alteg.io/en/b2b-v2/openapi/services/get_service.md): Retrieve details of a specific service.

Available includes:
- category - Service category details
- staff - Staff members who provide this service

### List Service Categories

 - [GET /locations/{location_id}/service_categories](https://developer.alteg.io/en/b2b-v2/openapi/services/list_service_categories.md): Retrieve all service categories for a location.

Optionally filter by staff member to get categories for services they provide.

Available includes:
- services - Services in this category

## Products

Product (goods) inventory management.

Retrieve products, categories, stock levels, and attendance product items.


### List Products

 - [GET /locations/{location_id}/products](https://developer.alteg.io/en/b2b-v2/openapi/products/list_products.md): Retrieve products for a location with optional filters.

Filters:
- ids - filter by specific product IDs
- related_loyalty_entity_slug - filter by loyalty program type:
  - common - regular products (default)
  - loyalty_abonement - subscription/membership products
  - loyalty_certificate - gift certificate products

Available includes:
- category - Product category details
- storage_amounts - Stock levels across storages

### Autocomplete Products

 - [GET /locations/{location_id}/products/autocomplete](https://developer.alteg.io/en/b2b-v2/openapi/products/autocomplete_products.md): Search products by name, article number, or barcode.
Useful for quick product lookup in forms.

Note: Emoji characters are not supported in search terms.

### Get Product

 - [GET /locations/{location_id}/products/{product_id}](https://developer.alteg.io/en/b2b-v2/openapi/products/get_product.md): Retrieve details of a specific product by ID.

Available includes:
- category - Product category details
- storage_amounts - Stock levels across storages

### Get Product Storage Amounts

 - [GET /locations/{location_id}/products/{product_id}/storage_amounts](https://developer.alteg.io/en/b2b-v2/openapi/products/list_product_storage_amounts.md): Retrieve stock levels for a product across all storages.
Shows how much of the product is available in each storage location.

Available includes:
- storage - Storage details

### List Product Categories

 - [GET /locations/{location_id}/product_categories](https://developer.alteg.io/en/b2b-v2/openapi/products/list_product_categories.md): Retrieve product categories for a location.
Supports hierarchical categories via parent_category_id filter.

Available includes:
- children - Child categories
- products - Products in this category

### Get Product Category

 - [GET /locations/{location_id}/product_categories/{product_category_id}](https://developer.alteg.io/en/b2b-v2/openapi/products/get_product_category.md): Retrieve details of a specific product category.

Available includes:
- children - Child categories
- products - Products in this category
- parent - Parent category

### Get Attendance Product Item

 - [GET /locations/{location_id}/attendance_product_items/{attendance_product_item_id}](https://developer.alteg.io/en/b2b-v2/openapi/products/get_attendance_product_item.md): Retrieve a product item from an attendance (visit session).
This represents a product sold/used during a client visit.

Available includes:
- product - Product details
- storage - Source storage details

## Team Members

Team member (staff) and position management.

Manage staff positions and retrieve team member information.


### List Team Members

 - [GET /locations/{location_id}/team_members](https://developer.alteg.io/en/b2b-v2/openapi/team-members/list_team_members.md): Retrieve all team members (staff) for a location with optional filters.

Filter Values (tri-state):
- 0 = exclude matching
- 1 = only matching
- 2 = all (default for most filters)

| Filter | Default | Description |
|--------|---------|-------------|
| deleted | 0 | 0=active only, 1=deleted only, 2=all |
| fired | 2 | 0=employed, 1=fired only, 2=all |
| user_linked | 2 | 0=no account, 1=has account, 2=all |
| is_paid | 2 | 0=unpaid, 1=paid, 2=all |
| has_schedule | 2 | 0=no schedule, 1=has schedule, 2=all |
| is_assistant | 2 | 0=exclude assistants, 1=only assistants, 2=all |

Available includes:
- position - Position details
- services - Services provided by this team member
- schedule - Work schedule

### List Positions

 - [GET /companies/{company_id}/positions](https://developer.alteg.io/en/b2b-v2/openapi/team-members/list_positions.md): Returns all staff positions for the specified company.

Response uses JSON:API format where type: "position" is the resource type.

Positions define organizational roles and can be assigned to staff members.
Positions are stored at the salon group level but accessed via company.

### Create Position

 - [POST /companies/{company_id}/positions](https://developer.alteg.io/en/b2b-v2/openapi/team-members/create_position.md): Creates a new staff position for the specified company.
At least one salon ID must be provided.

### Get Position

 - [GET /companies/{company_id}/positions/{position_id}](https://developer.alteg.io/en/b2b-v2/openapi/team-members/get_position.md): Retrieve details of a specific position by ID.

Response uses JSON:API format where type: "position" is the resource type.

### Update Position

 - [PUT /companies/{company_id}/positions/{position_id}](https://developer.alteg.io/en/b2b-v2/openapi/team-members/update_position.md): Update an existing staff position.
Title and salon_ids are required in the request body.

### Delete Position

 - [DELETE /companies/{company_id}/positions/{position_id}](https://developer.alteg.io/en/b2b-v2/openapi/team-members/delete_position.md): Delete a staff position.

## Appointments

Appointment (booking/record) management.

List and manage appointments for a location.


### List Appointments

 - [GET /locations/{location_id}/appointments](https://developer.alteg.io/en/b2b-v2/openapi/appointments/list_appointments.md): Retrieve appointments for a location with optional filters.

Date Format: ISO 8601 without timezone (YYYY-MM-DDTHH:MM:SS)

Available includes:
- client - Client information
- staff - Staff member details
- services - Service details
- custom_field_values - Custom field values (requires permission)
- client.custom_field_values - Client custom fields (requires permission)

### Delete Appointment

 - [DELETE /locations/{location_id}/appointments/{appointment_id}](https://developer.alteg.io/en/b2b-v2/openapi/appointments/delete_appointment.md): Delete (cancel) an appointment.

Requires hasSalonDeleteRecordsAccess permission and
record-level delete access for the specific appointment.

### Bulk Delete Appointments

 - [POST /locations/{location_id}/timetable/appointments/delete](https://developer.alteg.io/en/b2b-v2/openapi/appointments/bulk_delete_appointments.md): Delete multiple appointments from the timetable view.

Alternative endpoint for batch deletion operations.
Returns partial success - both deleted IDs and failed deletions with error messages.

## Events

Group events (activities) management.

### List Activities

 - [GET /companies/{location_id}/activities](https://developer.alteg.io/en/b2b-v2/openapi/events/list_activities.md): Retrieve activities for a company within a date range, optionally filtered by search, staff, or services.

Required Parameters:
- filter[from] - start date/time (format: YYYY-MM-DD HH:MM:SS)
- filter[to] - end date/time (format: YYYY-MM-DD HH:MM:SS)

Optional Filters:
- filtermaster_ids - filter by staff IDs (array)
- filterservice_ids - filter by service IDs (array)
- filter[capacity] - filter by capacity (number)
- search - search by activity name or description (string)
- limit - results per page (default: 100)
- offset - pagination offset (default: 0)

### Create Event

 - [POST /companies/{location_id}/activities](https://developer.alteg.io/en/b2b-v2/openapi/events/create_event.md): Creates an Event (group activity) for a location.

### Get Event

 - [GET /companies/{location_id}/activities/{event_id}](https://developer.alteg.io/en/b2b-v2/openapi/events/get_event.md): Returns detailed information about a specific Event.

### Update Event

 - [PUT /companies/{location_id}/activities/{event_id}](https://developer.alteg.io/en/b2b-v2/openapi/events/update_event.md): Updates an existing Event.

### Delete Event

 - [DELETE /companies/{location_id}/activities/{event_id}](https://developer.alteg.io/en/b2b-v2/openapi/events/delete_event.md): Deletes an Event.

### Create Event Appointment

 - [POST /companies/{location_id}/activities/{event_id}/records](https://developer.alteg.io/en/b2b-v2/openapi/events/create_event_appointment.md): Creates an Appointment for a Client in an Event.

Note: All client fields are required even when using existing client ID.

### Update Event Appointment

 - [PATCH /companies/{location_id}/activities/{event_id}/records/{record_id}](https://developer.alteg.io/en/b2b-v2/openapi/events/update_event_appointment.md): Updates an existing Appointment in an Event.

Note: This endpoint uses PATCH (not POST as in some documentation).

## Tags

Client tagging system.

### List Tags

 - [GET /companies/{company_id}/tags](https://developer.alteg.io/en/b2b-v2/openapi/tags/list_tags.md): Returns all tags for the specified company, optionally filtered by entity type.

Response uses JSON:API format where type: "tag" is the resource type name (not to be confused with entity_type attribute).

Entity types:
- common (0) - General tags
- client (1) - Client tags
- record (2) - Appointment/record tags
- activity (3) - Activity/event tags

Use the entity query parameter to filter by type. Accepts both string aliases and numeric values.

### Create Tag

 - [POST /companies/{company_id}/tags](https://developer.alteg.io/en/b2b-v2/openapi/tags/create_tag.md): Creates a new tag for the specified company.

### Get Tag

 - [GET /companies/{company_id}/tags/{tag_id}](https://developer.alteg.io/en/b2b-v2/openapi/tags/get_tag.md): Returns detailed information about a specific tag.

Response uses JSON:API format where type: "tag" is the resource type name.

### Update Tag

 - [PUT /companies/{company_id}/tags/{tag_id}](https://developer.alteg.io/en/b2b-v2/openapi/tags/update_tag.md): Updates an existing tag.

### Delete Tag

 - [DELETE /companies/{company_id}/tags/{tag_id}](https://developer.alteg.io/en/b2b-v2/openapi/tags/delete_tag.md): Deletes a tag (soft delete - marks as deleted).