AI Churn Manager

• API Endpoint: {api_url}/v1/guests/retention_scores

• Scenario: This API bulk updates retention scores for guests, called by the ML model after scoring. It accepts a list of guest IDs with corresponding scores and updates all records in a single batch operation using a table-valued parameter (TVP) for optimal performance.

• API method: POST

• Earlier behavior: New API. No earlier behavior.

• New behavior: The POST endpoint accepts a list of guest IDs and scores (0.0 to 1.0), validates that the scores list is non-empty, and updates all matching guest records in a single batch. Returns the count of updated records on success. Returns error code GE005 for empty, null, or missing request bodies. Non-existent guest IDs return a 200 with an updated count of 0 and no error. Server or database failures return a 500 with error code GE100.

Treatment Hub

• API Endpoint: {api_url}/v1/treatments/procedures/{procedure_id}/snapshots/{snapshot_id}/rectifications

• Scenario: This API creates a rectification of a specific treatment snapshot. It produces a new snapshot version by merging changed clinical data sections from the database on top of the specified snapshot blob. Used when a manager or elevated employee unlocks a locked procedure, makes corrections, and submits with a rectification reason.

• API method: POST

• Earlier behavior: New API. No earlier behavior.

• New behavior: Creates a new rectified snapshot version by merging specified changed sections (clinical_data, treatment_charts, treatment_files, contraindications) onto the existing snapshot blob, retaining the original in history. Restricted to employees with Therapist role or Appointments (Add/Edit) permission.

Memberships

• API Endpoint: {api_url}/v1/reports/billing_collections_deposits_summary/flat_file

• Scenario: This API generates a comprehensive financial report analyzing billing, collections, and deposits data over a defined time period across one or more centers.

• API method: POST

• Earlier behavior: New API. No earlier behavior.

• New behavior: Returns billing, collections, and deposits data for the specified date range (max 365 days) and centers, with response sections controlled by the expand_grid parameter.

Treatment Hub

• API Endpoint: v1/component_locks/{lock_id}

• Scenario: This API retrieves lock details for a Treatment Hub card given a lock key, returning the lock ID, the employee who holds the lock, and the expiry time.

• API method: GET

• Earlier behavior: New API. No earlier behavior.

• New behavior: Returns lock details for the specified lock_id, including who holds the lock and when it expires. Restricted to employee tokens with Therapist role or Appointments (Add/Edit) permission.

Treatment Hub

• API Endpoint: v1/component_locks/{lock_id}/renew

• Scenario: This API renews an existing lock on a Treatment Hub card, extending the lock expiry for the specified lock key.

• API method: PUT

• Earlier behavior: New API. No earlier behavior.

• New behavior: Renews the lock for the specified lock_id and returns a success response with no body. Restricted to employee tokens with Therapist role or Appointments (Add/Edit) permission.

Treatment Hub

• API Endpoint: v1/component_locks/{lock_id}

• Scenario: This API releases an existing lock on a Treatment Hub card, making it editable for other concurrent users.

• API method: DELETE

• Earlier behavior: New API. No earlier behavior.

• New behavior: Releases the lock for the specified lock_id and returns the released lock ID on success. Restricted to employee tokens with Therapist role or Appointments (Add/Edit) permission.

Treatment Hub

• API Endpoint: v1/component_locks

• Scenario: This API acquires a lock on a Treatment Hub card, making it uneditable for other concurrent users.

• API method: POST

• Earlier behavior: New API. No earlier behavior.

• New behavior: Acquires a lock for the specified entity type and ID, returning the lock status (LockAcquired, LockRefreshed, or ComponentLocked), lock details, and expiry time. If the card is already locked by another user, returns status ComponentLocked with the existing lock details. Restricted to employee tokens with Therapist role or Appointments (Add/Edit) permission.

Treatment Hub

• API Endpoint: {api_url} /v1/procedures/{procedure_id}/draft

• Scenario: This API saves or updates in-progress treatment chart data for a procedure in Treatment Hub, ensuring work is not lost during a treatment session.

• API method: PUT

• Earlier behavior: New API. No earlier behavior.

• New behavior: Saves or updates draft chart component data for the specified procedure, creating new records when IDs are null and updating existing ones when IDs are provided. Returns the saved data with generated identifiers on success. Restricted to employee tokens via Web and Mobile POS sources only.

Loyalty

• API Endpoint: {api_url}/v1/organizations/lp_payment_setting

• Scenario: This API enables or disables the loyalty points payment setting for an organization, used during Aveda LP integration setup to ensure the payment setting is active before proceeding with the Aveda flow.

• API method: PATCH

• Earlier behavior: New API. No earlier behavior.

• New behavior: Accepts a single boolean is_enabled field and updates the org-level loyalty points payment setting accordingly. Restricted to employee tokens with Appointments (Add or Edit) permission.

Loyalty

• API Endpoint: {api_url}/v1/services/aveda/service_associations

• Scenario: This API voids all Aveda service records for the organization, used when toggling the "Enable Aveda Services" setting to clear existing records so services can be re-marked.

• API method: DELETE

• Earlier behavior: New API. No earlier behavior.

• New behavior: Voids all Aveda service associations for the organization with no request body required. Returns 400 if Aveda integration is not enabled. Restricted to employee tokens with Services (Add or Edit) permission.

Loyalty

• API Endpoint: {api_url}/v1/products/aveda/check_duplicate_upc

• Scenario: This API checks whether a given Aveda UPC code already exists for another product within the organization.

• API method: PUT

• Earlier behavior: New API. No earlier behavior.

• New behavior: Accepts a UPC code and an optional product ID (excluded from the duplicate check) and returns is_duplicate as true or false. Restricted to employee tokens with Products (Add or Edit) permission.

Loyalty

• API Endpoint: {api_url}/v1/integrations/aveda/ping

• Scenario: This API tests connectivity to the Aveda LP service using a location ID, used to validate user input before saving LP configuration settings.

• API method: GET

• Earlier behavior: New API. No earlier behavior.

• New behavior: Accepts a location_id query parameter and pings the Aveda service to confirm connectivity. Returns 400 if the location ID is missing or the service is unreachable. Restricted to employee tokens with Centers (Add or Edit) permission.

Loyalty

• API Endpoint: {api_url}/v1/integrations/aveda/lp_configuration_settings

• Scenario: This API saves location-level Aveda LP integration settings for a center, creating or configuring the AvedaLP custom payment agent, AvedaEnrollment package, and AvedaSSC service certificate payment agent.

• API method: PUT

• Earlier behavior: New API. No earlier behavior.

• New behavior: Accepts subscriber_id, location_id, and is_active to configure and persist Aveda LP integration settings for a center. Returns 400 if required fields are missing or if any step in the setup chain (payment agent, enrollment package, or settings save) fails. Restricted to employee tokens with Centers (Add or Edit) permission.

Loyalty

• API Endpoint: {api_url}/v1/guests/{guest_id}/aveda/history

• Scenario: This API returns paginated transaction history for an Aveda-linked guest by resolving their Aveda membership ID internally and fetching history from the Aveda LP service.

• API method: GET

• Earlier behavior: New API. No earlier behavior.

• New behavior: Accepts guest_id as a path parameter and optional center_id, page_size (default 10), and page_index (default 1) query parameters. Returns paginated transaction records including amount spent, points earned or redeemed, and transaction type. Returns 400 if the guest, center, or Aveda linkage is invalid or Aveda is not enabled. Restricted to employee tokens with Guest History (View) and Guests (Edit) permissions.

Loyalty

• API Endpoint: {api_url}/v1/guests/{guest_id}/aveda/enroll

• Scenario: This API enrolls a guest in the Aveda loyalty program by sending their details to the Aveda LP service, returning the newly created membership ID and enrollment attributes on success.

• API method: POST

• Earlier behavior: New API. No earlier behavior.

• New behavior: Accepts guest details including name, email, date of birth, address, communication preferences, and terms acceptance, and creates an Aveda loyalty membership. Returns 400 if the guest is not found, Aveda is not enabled, or the Aveda service returns validation errors (including duplicate email). Restricted to employee tokens with Guest History (View) and Guests (Edit) permissions.

Loyalty

• API Endpoint: {api_url}/v1/guests/{guest_id}/aveda/certificates

• Scenario: This API returns the list of Aveda SSC/certificates for a guest by resolving their Aveda membership ID internally and fetching certificates from the Aveda LP service.

• API method: GET

• Earlier behavior: New API. No earlier behavior.

• New behavior: Accepts guest_id as a path parameter and an optional center_id query parameter, and returns a list of certificates including offer code, offer type, and expiry date. Returns 400 if the guest, center, or Aveda linkage is invalid or Aveda is not enabled. Restricted to employee tokens with Guest History (View) and Guests (Edit) permissions.

Loyalty

• API Endpoint: {api_url}/v1/guests/{guest_id}/aveda/enrollment_form_details

• Scenario: This API returns guest profile fields pre-filled for the Aveda enrollment form, including formatted phone number with country code, address with ISO state/country codes, and date of birth.

• API method: GET

• Earlier behavior: New API. No earlier behavior.

• New behavior: Accepts guest_id as a path parameter and returns pre-filled enrollment details resolved from the authenticated user's session center. Returns 400 if the guest is not found or Aveda is not enabled at the org or center level. Restricted to employee tokens with Guest History (View) and Guests (Edit) permissions.

Loyalty

• API Endpoint: {api_url}/v1/guests/{guest_id}/aveda/details

• Scenario: This API returns Aveda membership details for a guest, including membership ID, enrollment status, point balance, and suspended flag.

• API method: GET

• Earlier behavior: New API. No earlier behavior.

• New behavior: Accepts guest_id as a path parameter and an optional center_id query parameter, and returns the guest's Aveda membership attributes. Returns 400 if the guest or center is invalid or Aveda is not enabled. Restricted to employee tokens with Guest History (View) and Guests (Edit) permissions.

Treatment Hub

• API Endpoint: {api_url}/v1/treatments/procedures/{procedure_id}/snapshots/{snapshot_id}

• Scenario: This API retrieves a specific treatment snapshot by its unique identifier, used for accessing historical snapshots or when the snapshot ID is already known. Validates that the snapshot belongs to the specified procedure.

• API method: GET

• Earlier behavior: New API. No earlier behavior.

• New behavior: Accepts procedure_id and snapshot_id as path parameters and returns the snapshot with a pre-signed download URL, metadata, and completeness details. Returns 404 if the snapshot is not found or the procedure ID doesn't match. Restricted to employee tokens with TreatmentSnapshot permission via Web and Mobile POS sources.