> ## Documentation Index > Fetch the complete documentation index at: https://developers.huechat.ai/llms.txt > Use this file to discover all available pages before exploring further. # Sync one appointment from a scheduling system > Requires a REST API key with appointments:sync on an account HueChat approved for a scheduling system connection. The booking is stored exactly as the system has it - past, same-day, off-grid and outside-hours times, overlapping bookings for one resource, archived services or resources and any lifecycle status (native names, HL7 FHIR R4 Appointment.status or HL7 v2 SIU filler status) - with source sync. Send source_updated_at (the system's last-modified time) so updates that arrive out of order are ignored. Resources and services match by HueChat id, then the system's own code (resource_code, service_code), then name; a code HueChat has not seen is added to the catalog. The booking links to an existing contact by contact_id, patient_identifier (the contact's identifier) or phone. Rejected bookings stay listed in GET /appointments/sync/status until a later version succeeds. ## OpenAPI ````yaml /api-reference/openapi.json put /api/v2/accounts/{accountId}/appointments/external/{externalId} openapi: 3.0.3 info: contact: name: HueChat support email: support@huechat.ai url: https://huechat.ai/contact description: >- Account-scoped REST API for HueChat: conversations, messages, contacts, Customer CDP, Sales CRM, forms, appointments, inboxes, teams, agents, AI agents and knowledge, WhatsApp templates and broadcasts, workflows and chat menus. Authenticate with account-scoped API keys; every route is scoped to your own account. license: name: Proprietary url: https://huechat.ai/terms termsOfService: https://huechat.ai/terms title: HueChat API version: 2.0.0 servers: - url: https://app.huechat.ai description: Production security: - bearerAuth: [] tags: - name: Agents description: The human agents on your account and their availability. - name: AI Agents description: >- Assistants you build to answer customers on their own: persona, language, guardrails, tools and a knowledge base, published to inboxes, replying in Arabic or English until they hand off to a human. Create, publish, test, monitor quality and roll back versions. - name: Broadcasts description: >- Send a WhatsApp template to a list of contacts from a CSV or saved audience, with scheduling, pause and resume, and delivery reports. - name: Chat Menus description: >- Numbered or button-driven menus a customer sees at the start of a conversation. - name: Contacts description: >- The people your team talks to: phone, email, name, custom attributes, labels and notes. One contact can have conversations on several channels. - name: Conversations description: >- A conversation is one thread between a contact and your team on one channel, with status, assignee, team, labels, priority and custom attributes. List, filter, search, assign, resolve and annotate them. - name: Forms description: >- Form management, assets, delivery, respondent sessions, submissions, scheduling, reports and AI-assisted authoring in one group. - name: Inboxes description: >- Connected channels: a WhatsApp Business number, an Instagram or Messenger page, an email address or a website live-chat widget. Inboxes decide where a conversation comes from and who can see it. - name: Knowledge description: >- Documents, web pages and text that ground an AI agent's answers. Upload, point at a URL or paste text; HueChat indexes it and the agent cites it. - name: Messages description: >- Everything said inside a conversation: text, attachments, WhatsApp templates and interactive replies. Sending through the API delivers on the conversation's channel and shows in the inbox like any agent reply. - name: Sales CRM description: >- The full tenant-scoped Sales workspace: Leads, Companies, Deals, tasks, products, price books, quotes, payments, forecasts, reports and settings. - name: Teams description: Groups of agents used for assignment and reporting. - name: Templates description: >- Pre-approved WhatsApp message formats required by Meta for business-initiated messages. Create, sync from Meta, AI-generate, test-send and read analytics. - name: Workflows description: >- Automation flows built from triggers and steps: route, tag, reply, wait, hand off. Create, publish, version and toggle. paths: /api/v2/accounts/{accountId}/appointments/external/{externalId}: put: tags: - Appointments summary: Sync one appointment from a scheduling system description: >- Requires a REST API key with appointments:sync on an account HueChat approved for a scheduling system connection. The booking is stored exactly as the system has it - past, same-day, off-grid and outside-hours times, overlapping bookings for one resource, archived services or resources and any lifecycle status (native names, HL7 FHIR R4 Appointment.status or HL7 v2 SIU filler status) - with source sync. Send source_updated_at (the system's last-modified time) so updates that arrive out of order are ignored. Resources and services match by HueChat id, then the system's own code (resource_code, service_code), then name; a code HueChat has not seen is added to the catalog. The booking links to an existing contact by contact_id, patient_identifier (the contact's identifier) or phone. Rejected bookings stay listed in GET /appointments/sync/status until a later version succeeds. operationId: put_api_v2_accounts_accountId_appointments_external_externalId parameters: - name: accountId in: path required: true description: HueChat account ID schema: type: integer description: HueChat account ID - name: externalId in: path required: true description: The scheduling system's booking identifier schema: type: string description: The scheduling system's booking identifier requestBody: description: Booking as the scheduling system has it required: true content: application/json: schema: $ref: '#/components/schemas/huechat.AppointmentSyncRequest' responses: '200': description: Updated, unchanged or stale (see X-HueChat-Sync-Result) content: application/json: schema: $ref: '#/components/schemas/huechat.AppointmentResponse' headers: X-HueChat-Sync-Result: description: created, updated, unchanged or stale schema: type: string '201': description: Created content: application/json: schema: $ref: '#/components/schemas/huechat.AppointmentResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/huechat.AppointmentAPIError' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/huechat.AppointmentAPIError' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/huechat.AppointmentAPIError' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/huechat.AppointmentAPIError' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/huechat.AppointmentAPIError' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/huechat.AppointmentAPIError' '503': description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/huechat.AppointmentAPIError' security: - bearerAuth: [] components: schemas: huechat.AppointmentSyncRequest: type: object properties: cancellation_reason: type: string contact_id: type: integer example: 42 customer_email: type: string example: patient@example.com customer_name: type: string maxLength: 200 example: Example Patient customer_phone: type: string example: '+966500000000' date: type: string example: '2026-09-22' duration_minutes: type: integer maximum: 43200 minimum: 1 ends_at: type: string format: date-time example: '2026-09-22T13:20:00+03:00' external_id: type: string maxLength: 128 example: oracle-main:A-10492 notes: type: string patient_identifier: type: string maxLength: 255 example: MRN-000205 resource_code: type: string maxLength: 128 example: Practitioner/482 resource_id: type: string format: uuid resource_name: type: string maxLength: 160 example: Dr. Sara Ali resource_type: type: string maxLength: 80 example: Doctor service_code: type: string maxLength: 128 example: DENT-CONSULT service_id: type: string format: uuid service_name: type: string maxLength: 160 example: Dental consultation source_updated_at: type: string format: date-time example: '2026-09-22T09:58:00Z' starts_at: type: string format: date-time example: '2026-09-22T13:00:00+03:00' status: type: string example: booked time: type: string example: '13:00' huechat.AppointmentResponse: type: object properties: account_id: type: integer buffer_after_minutes: type: integer buffer_before_minutes: type: integer busy_ends_at: type: string format: date-time busy_starts_at: type: string format: date-time cancellation_reason: type: string cancelled_at: type: string format: date-time completed_at: type: string format: date-time confirmed_at: type: string format: date-time contact_id: type: integer conversation_id: type: integer created_at: type: string format: date-time created_by_ai_agent_id: type: string format: uuid created_by_user_id: type: integer customer_email: type: string customer_name: type: string customer_phone: type: string duration_minutes: type: integer ends_at: type: string format: date-time external_id: type: string id: type: string format: uuid notes: type: string public_id: type: string resource_color: type: string resource_id: type: string format: uuid resource_name: type: string resource_type: type: string service_color: type: string service_currency: type: string service_description: type: string service_id: type: string format: uuid service_name: type: string service_price: type: number source: type: string starts_at: type: string format: date-time status: type: string updated_at: type: string format: date-time version: type: integer huechat.AppointmentAPIError: type: object properties: error: type: string limit: type: string securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your personal access token where supported, or a scoped API key (`hc_…`) created inside HueChat at Account → Developer API. Send it as `Authorization: Bearer `. ````