# CallSnare Actions This page defines stable product actions. Not every action is publicly callable today. ## list_bookings Status: Live today via protected access Returns bookings for a date range. Current surface: GET /api/private/v1/bookings Use when: Use this when an approved external system needs calendar visibility for upcoming or recent work. Required data: - Bearer token - READ_BOOKINGS scope - Optional from/to date range Output: A booking collection with status, timing, customer details, and source labeling. Side effects: - Touches credential usage history for audit and observability. Permissions: Protected private API with org-scoped token and READ_BOOKINGS. Idempotency: Read-only request. No idempotency key required. ## get_booking_status Status: Live today via protected access Returns one booking and its current state. Current surface: GET /api/private/v1/bookings/:bookingId Use when: Use this when an approved external system needs the latest status for one booked job. Required data: - Bearer token - READ_BOOKINGS scope - bookingId path parameter Output: One booking record including timing, status, source, and scheduling state. Side effects: - Touches credential usage history for audit and observability. Permissions: Protected private API with org-scoped token and READ_BOOKINGS. Idempotency: Read-only request. No idempotency key required. ## book_job Status: Live today via protected access Creates a booking in CallSnare's calendar layer. Current surface: POST /api/private/v1/bookings Use when: Use this when an approved integration has enough customer and schedule detail to place the job. Required data: - Bearer token - WRITE_BOOKINGS scope - customerPhone - scheduledStartAt - scheduledEndAt - Optional customerName, serviceLabel, notes, address, postalCode, leadId Output: A created booking record and source attribution for the external actor. Side effects: - Creates the booking record. - May connect to an existing lead. - Schedules confirmation and reminder work when booking settings allow it. Permissions: Protected private API with org-scoped token and WRITE_BOOKINGS. Idempotency: Supports Idempotency-Key. Replays with the same request return the same booking. Conflicting retries return a 409 response. ## reschedule_booking Status: Live today via protected access Moves an existing booking to a new time window. Current surface: PATCH /api/private/v1/bookings/:bookingId Use when: Use this when an approved integration needs to change the scheduled visit time. Required data: - Bearer token - WRITE_BOOKINGS scope - bookingId path parameter - One or more mutable fields such as scheduledStartAt or scheduledEndAt Output: The updated booking record. Side effects: - Updates the booking record. - Replaces unsent confirmation and reminder jobs so communication stays aligned to the new schedule. Permissions: Protected private API with org-scoped token and WRITE_BOOKINGS. Idempotency: Supports Idempotency-Key. Replays with the same request stay safe. Conflicting retries return a 409 response. ## cancel_booking Status: Live today via protected access Cancels a booking without deleting its history. Current surface: PATCH /api/private/v1/bookings/:bookingId Use when: Use this when an approved integration needs the calendar and reminder state to reflect a canceled visit. Required data: - Bearer token - WRITE_BOOKINGS scope - bookingId path parameter - status=CANCELED Output: The updated booking record in canceled state. Side effects: - Preserves booking history for audit. - Prevents future booking communication from sending as if the visit were still active. Permissions: Protected private API with org-scoped token and WRITE_BOOKINGS. Idempotency: Supports Idempotency-Key. Replays with the same request stay safe. Conflicting retries return a 409 response. ## get_private_api_health Status: Live today via protected access Verifies that a protected credential is valid and scoped to the expected organization. Current surface: GET /api/private/v1/health Use when: Use this during credential handoff or integration smoke tests. Required data: - Bearer token Output: Credential identity, actor type, scopes, and orgId. Side effects: - Touches credential usage history for audit and observability. Permissions: Protected private API with any valid org-scoped credential. Idempotency: Read-only request. No idempotency key required. ## create_lead Status: Live inside CallSnare only Creates or reuses a lead when a missed call or inbound text starts a conversation. Current surface: Internal webhook and web-app workflow Use when: Use this as the product concept for new customer conversations. There is no public protected lead-create endpoint today. Required data: - Tracked phone number context - Customer phone number - Inbound event payload Output: A tenant-scoped lead and timeline evidence. Side effects: - May trigger missed-call follow-up automation when rules allow it. Permissions: Internal product flow only today. Idempotency: Webhook ingestion uses provider message and call identifiers to avoid duplicate side effects. ## update_lead_status Status: Live inside CallSnare only Moves a lead through the lifecycle such as Active, Booked, Won, or Lost. Current surface: Web app only today Use when: Use this when the team or the product needs the lead lifecycle to reflect real progress. Required data: - leadId - New lifecycle status Output: Updated lead state with lifecycle timestamps and timeline evidence. Side effects: - Writes lead events and may stop automation when terminal states are reached. Permissions: Available to team members inside the product. Not exposed as a protected external write today. Idempotency: Lifecycle timestamps are written idempotently. ## send_confirmation Status: Live inside CallSnare only Sends or schedules a booking confirmation message from the booking workflow. Current surface: Internal booking automation Use when: Use this when a booking is placed and confirmation messaging is enabled for the organization. Required data: - Booking record - Outbound messaging entitlement - Configured templates and phone settings Output: Updated booking confirmation state and outbound job evidence. Side effects: - Creates or processes outbound jobs. - Writes auditable booking communication history. Permissions: Internal product flow only today. Idempotency: Outbound job processing is designed to stay safe under concurrent cron execution. ## send_reminder Status: Live inside CallSnare only Sends or schedules reminder messages for upcoming bookings. Current surface: Internal booking automation Use when: Use this when reminder timing is enabled and the appointment is still active. Required data: - Booking record - Reminder schedule - Outbound messaging entitlement Output: Updated reminder state and outbound job evidence. Side effects: - Creates or processes outbound jobs. - Stops when the booking is canceled or otherwise no longer eligible. Permissions: Internal product flow only today. Idempotency: Outbound job processing is designed to stay safe under concurrent cron execution. ## list_open_slots Status: Planned future action Returns available appointment windows. Current surface: Planned future protected action Use when: Planned future protected action for tighter scheduling integrations. Required data: - Date window - Organization calendar settings Output: Open slots and blackout guidance. Side effects: - None expected for the read path. Permissions: Not exposed publicly today. Idempotency: Would be read-only. ## get_conversation_summary Status: Planned future action Returns a concise summary of the customer conversation and current next step. Current surface: Planned future protected action Use when: Planned future protected action for systems that need context without scraping the inbox UI. Required data: - leadId or conversation identifier Output: Lead summary, status, and next action guidance. Side effects: - None expected for the read path. Permissions: Not exposed publicly today. Idempotency: Would be read-only.