01
Protected writes stay narrow
Current external access focuses on booking operations and health checks through org-scoped Bearer credentials.
Residential HVAC missed-call recovery
Keep working. We’ll handle the callback.
Docs / Actions
Stable action vocabulary first, broader external surface later
This page names the action model clearly before exposing it broadly. Public discovery does not mean broad public write access; the current protected surface stays intentionally narrow and org-scoped.
Reading about an action here does not make it public. The public docs explain the model; protected access still depends on explicit credentials, scopes, and tenant boundaries.
Action model
Protected today, internal where needed, explicit about what is next
02
Internal workflows remain real
Lead creation, status movement, confirmations, and reminders exist now without becoming a broad public write surface.
03
Planned expansion is named early
Future action vocabulary is public so integrations can align to the model before the surface expands.
Discoverability is broad. Callable surface area is still deliberately small.
Live protected
6
Currently callable through the private API with explicit scopes.
Live internal
4
Product workflows that remain inside the main operating surface.
Planned
2
Future actions documented publicly but not exposed today.
Live protected
Actions available today through org-scoped credentials
These are the narrow actions currently exposed through the protected private API used by approved integrations.
6 actions
list_bookings
Returns bookings for a date range.
Use when
Use this when an approved external system needs calendar visibility for upcoming or recent work.
Current surface
GET /api/private/v1/bookings
Output and permissions
A booking collection with status, timing, customer details, and source labeling.
Permissions
Protected private API with org-scoped token and READ_BOOKINGS.
Required data
- Bearer token
- READ_BOOKINGS scope
- Optional from/to date range
Side effects and safety
- Touches credential usage history for audit and observability.
Idempotency
Read-only request. No idempotency key required.
get_booking_status
Returns one booking and its current state.
Use when
Use this when an approved external system needs the latest status for one booked job.
Current surface
GET /api/private/v1/bookings/:bookingId
Output and permissions
One booking record including timing, status, source, and scheduling state.
Permissions
Protected private API with org-scoped token and READ_BOOKINGS.
Required data
- Bearer token
- READ_BOOKINGS scope
- bookingId path parameter
Side effects and safety
- Touches credential usage history for audit and observability.
Idempotency
Read-only request. No idempotency key required.
book_job
Creates a booking in CallSnare's calendar layer.
Use when
Use this when an approved integration has enough customer and schedule detail to place the job.
Current surface
POST /api/private/v1/bookings
Output and permissions
A created booking record and source attribution for the external actor.
Permissions
Protected private API with org-scoped token and WRITE_BOOKINGS.
Required data
- Bearer token
- WRITE_BOOKINGS scope
- customerPhone
- scheduledStartAt
- scheduledEndAt
- Optional customerName, serviceLabel, notes, address, postalCode, leadId
Side effects and safety
- Creates the booking record.
- May connect to an existing lead.
- Schedules confirmation and reminder work when booking settings allow it.
Idempotency
Supports Idempotency-Key. Replays with the same request return the same booking. Conflicting retries return a 409 response.
reschedule_booking
Moves an existing booking to a new time window.
Use when
Use this when an approved integration needs to change the scheduled visit time.
Current surface
PATCH /api/private/v1/bookings/:bookingId
Output and permissions
The updated booking record.
Permissions
Protected private API with org-scoped token and WRITE_BOOKINGS.
Required data
- Bearer token
- WRITE_BOOKINGS scope
- bookingId path parameter
- One or more mutable fields such as scheduledStartAt or scheduledEndAt
Side effects and safety
- Updates the booking record.
- Replaces unsent confirmation and reminder jobs so communication stays aligned to the new schedule.
Idempotency
Supports Idempotency-Key. Replays with the same request stay safe. Conflicting retries return a 409 response.
cancel_booking
Cancels a booking without deleting its history.
Use when
Use this when an approved integration needs the calendar and reminder state to reflect a canceled visit.
Current surface
PATCH /api/private/v1/bookings/:bookingId
Output and permissions
The updated booking record in canceled state.
Permissions
Protected private API with org-scoped token and WRITE_BOOKINGS.
Required data
- Bearer token
- WRITE_BOOKINGS scope
- bookingId path parameter
- status=CANCELED
Side effects and safety
- Preserves booking history for audit.
- Prevents future booking communication from sending as if the visit were still active.
Idempotency
Supports Idempotency-Key. Replays with the same request stay safe. Conflicting retries return a 409 response.
get_private_api_health
Verifies that a protected credential is valid and scoped to the expected organization.
Use when
Use this during credential handoff or integration smoke tests.
Current surface
GET /api/private/v1/health
Output and permissions
Credential identity, actor type, scopes, and orgId.
Permissions
Protected private API with any valid org-scoped credential.
Required data
- Bearer token
Side effects and safety
- Touches credential usage history for audit and observability.
Idempotency
Read-only request. No idempotency key required.
Live internal
Actions the product performs today without exposing them as public writes
These workflows are real, but they remain inside the CallSnare product surface so the team, audit trails, and guardrails stay in control.
4 actions
create_lead
Creates or reuses a lead when a missed call or inbound text starts a conversation.
Use when
Use this as the product concept for new customer conversations. There is no public protected lead-create endpoint today.
Current surface
Internal webhook and web-app workflow
Output and permissions
A tenant-scoped lead and timeline evidence.
Permissions
Internal product flow only today.
Required data
- Tracked phone number context
- Customer phone number
- Inbound event payload
Side effects and safety
- May trigger missed-call follow-up automation when rules allow it.
Idempotency
Webhook ingestion uses provider message and call identifiers to avoid duplicate side effects.
update_lead_status
Moves a lead through the lifecycle such as Active, Booked, Won, or Lost.
Use when
Use this when the team or the product needs the lead lifecycle to reflect real progress.
Current surface
Web app only today
Output and permissions
Updated lead state with lifecycle timestamps and timeline evidence.
Permissions
Available to team members inside the product. Not exposed as a protected external write today.
Required data
- leadId
- New lifecycle status
Side effects and safety
- Writes lead events and may stop automation when terminal states are reached.
Idempotency
Lifecycle timestamps are written idempotently.
send_confirmation
Sends or schedules a booking confirmation message from the booking workflow.
Use when
Use this when a booking is placed and confirmation messaging is enabled for the organization.
Current surface
Internal booking automation
Output and permissions
Updated booking confirmation state and outbound job evidence.
Permissions
Internal product flow only today.
Required data
- Booking record
- Outbound messaging entitlement
- Configured templates and phone settings
Side effects and safety
- Creates or processes outbound jobs.
- Writes auditable booking communication history.
Idempotency
Outbound job processing is designed to stay safe under concurrent cron execution.
send_reminder
Sends or schedules reminder messages for upcoming bookings.
Use when
Use this when reminder timing is enabled and the appointment is still active.
Current surface
Internal booking automation
Output and permissions
Updated reminder state and outbound job evidence.
Permissions
Internal product flow only today.
Required data
- Booking record
- Reminder schedule
- Outbound messaging entitlement
Side effects and safety
- Creates or processes outbound jobs.
- Stops when the booking is canceled or otherwise no longer eligible.
Idempotency
Outbound job processing is designed to stay safe under concurrent cron execution.
Planned surface
Future actions that are documented early but not publicly exposed
Planned actions are listed so the vocabulary is clear before the external surface expands. They are not callable today.
2 actions
list_open_slots
Returns available appointment windows.
Use when
Planned future protected action for tighter scheduling integrations.
Current surface
Planned future protected action
Output and permissions
Open slots and blackout guidance.
Permissions
Not exposed publicly today.
Required data
- Date window
- Organization calendar settings
Side effects and safety
- None expected for the read path.
Idempotency
Would be read-only.
get_conversation_summary
Returns a concise summary of the customer conversation and current next step.
Use when
Planned future protected action for systems that need context without scraping the inbox UI.
Current surface
Planned future protected action
Output and permissions
Lead summary, status, and next action guidance.
Permissions
Not exposed publicly today.
Required data
- leadId or conversation identifier
Side effects and safety
- None expected for the read path.
Idempotency
Would be read-only.
Continue reading
After the action model, the important questions are who can use it and how it stays safe
Use the next docs to understand the role and scope system, the public-versus-protected machine access split, and the webhook model that feeds the product.
Permissions
See how roles, scopes, and tenant boundaries shape who can do what.
Agent access
Review the current boundary between public discovery and protected machine work.
Security
Understand how authentication, authorization, validation, and auditability fit together.
Webhooks
Check the provider callback model that drives missed-call, messaging, and billing synchronization.