Appointments

HuskyVoice AI includes a built-in appointment booking engine. External systems — CRMs, EMRs, websites, and automation scripts — can create, update, and query appointments and availability through the same REST API used by the AI voice agents and the dashboard.

Key Concepts

Services (Appointment Types)

A service defines the type of appointment — for example, "General Checkup" or "Follow-up Visit". Each service has a unique service_id (UUID). When creating appointments you can pass either the UUID or the human-readable name; the API resolves names case-insensitively.

Use GET /v1/services to list all configured services for your organization.

Branches

A branch is a physical location. Every appointment is tied to a branch. If your organization has a single branch, branch_id is resolved automatically. If you have multiple branches, branch_id must be passed explicitly in every create request.

To find your branch_id, call GET /v1/appointment-slots/availability with any future date — each slot in the response includes the branch_id it belongs to. If no slots are configured yet, find your branch IDs in Dashboard → Settings → Branches.

Calendar Windows

A calendar window is a recurring availability rule — for example, "Monday Mornings 09:00–11:00, max 20 slots". Windows repeat weekly on the same day and session. Each window belongs to a branch and can optionally be restricted to a specific service type.

Manage calendar windows using the Appointment Slots API.

Schedule Tracking

Schedule tracking records are per-date projections of calendar windows. The system auto-generates one record per calendar window per calendar date and keeps fill counts current as appointments are booked or cancelled.

Query tracking using the Availability & Schedule Tracking API.

Scopes

Each API key must include the relevant scope. Go to Dashboard → Integrations → API Keys → Generate New Key to create a key with the scopes your integration requires.

Scope	Allows
`appointments:read`	Fetch appointments, configuration, services, and availability
`appointments:write`	Create and update appointments
`slots:read`	Read slot availability and schedule tracking records
`slots:write`	Create, update, and disable calendar windows; update and regenerate tracking

Reading Your Configuration

GET /v1/appointment-config returns the general booking settings for your organization. Use this to read the configured timezone, advance booking limits, and policy flags.

Endpoint: GET https://api.huskyvoice.ai/v1/appointment-config
Required scope: appointments:read

cURL
Python
JavaScript
n8n

curl -s https://api.huskyvoice.ai/v1/appointment-config \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

response = requests.get(
    "https://api.huskyvoice.ai/v1/appointment-config",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
print(response.json())

const response = await fetch("https://api.huskyvoice.ai/v1/appointment-config", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await response.json();
console.log(data);

Credential setup

Create an HTTP Header Auth credential in n8n: set Name to Authorization and Value to Bearer YOUR_API_KEY. Select it in the HTTP Request node's Authentication field.

{
  "name": "HuskyVoice – Get Appointment Config",
  "nodes": [
    {
      "parameters": {
        "method": "GET",
        "url": "https://api.huskyvoice.ai/v1/appointment-config",
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth"
      },
      "id": "1",
      "name": "Get Appointment Config",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [250, 300]
    }
  ],
  "connections": {},
  "settings": {},
  "meta": { "instanceId": "huskyvoice-docs" }
}

Response — 200 OK

{
  "success": true,
  "data": {
    "general": {
      "enabled": true,
      "timezone": "Asia/Kolkata",
      "buffer_time_minutes": 15,
      "max_advance_booking_days": 30,
      "min_notice_hours": 2,
      "allow_reschedule": true,
      "allow_cancellation": true,
      "cancellation_notice_hours": 24
    }
  }
}

Field	Description
`timezone`	IANA timezone identifier used for all date/time validation (e.g. `"Asia/Kolkata"`)
`max_advance_booking_days`	How many days ahead bookings are accepted
`min_notice_hours`	Minimum hours of advance notice required
`buffer_time_minutes`	Gap enforced between consecutive appointments
`allow_reschedule`	Whether rescheduling is permitted
`allow_cancellation`	Whether cancellation is permitted
`cancellation_notice_hours`	Minimum notice required before cancelling

tip

Always read timezone from this endpoint before constructing appointment_date values. The booking engine validates times in the org's local timezone — a UTC datetime that looks valid may fall outside any configured window once converted.

Listing Appointment Types

GET /v1/services returns all configured appointment types for your organization. Use this to resolve human-readable names to UUIDs, or to populate a type selector.

Endpoint: GET https://api.huskyvoice.ai/v1/services
Required scope: appointments:read

cURL
Python
JavaScript
n8n

curl -s https://api.huskyvoice.ai/v1/services \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

response = requests.get(
    "https://api.huskyvoice.ai/v1/services",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
print(response.json())

const response = await fetch("https://api.huskyvoice.ai/v1/services", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await response.json();
console.log(data);

Credential setup

Create an HTTP Header Auth credential in n8n: set Name to Authorization and Value to Bearer YOUR_API_KEY. Select it in the HTTP Request node's Authentication field.

{
  "name": "HuskyVoice – List Appointment Types",
  "nodes": [
    {
      "parameters": {
        "method": "GET",
        "url": "https://api.huskyvoice.ai/v1/services",
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth"
      },
      "id": "1",
      "name": "List Appointment Types",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [250, 300]
    }
  ],
  "connections": {},
  "settings": {},
  "meta": { "instanceId": "huskyvoice-docs" }
}

Response — 200 OK

{
  "success": true,
  "data": [
    { "service_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "name": "General Checkup" },
    { "service_id": "3b8b1c2a-9e4f-4d3a-8c1b-2e5f7a9b0c1d", "name": "Follow-up Visit" }
  ]
}

Key Concepts​

Services (Appointment Types)​

Branches​

Calendar Windows​

Schedule Tracking​

Scopes​

Reading Your Configuration​

Listing Appointment Types​