Run a sub-account from your own software or an AI assistant: leads, deal value and won jobs, pipeline stages, bookings and calendars, texts and emails, the inbox, calls, forms, automations and settings. 173 endpoints, one MCP server.
Every path below starts with /v1 after the API address, and every answer has the same shape: { "success": true, "data": { ... }, "error": null }, or success: false with an error message and a matching HTTP status.
A key works inside its own sub-account only. Leave out workspace_id wherever you see it: the key fills it in, a different one is ignored, and records of any other sub-account answer 404.
An admin of the sub-account creates keys in the CRM under Settings → API. Each key is shown once; revoke it there the moment you stop using it. Send it with every request:
Header
Authorization: Bearer zu-...
Access level
What the key can do
Read only
Look things up. Nothing is created, changed or sent.
Read and write
Create and update leads, bookings and settings, send messages and enroll leads in automations. Cannot delete things or manage the team.
Full access
Everything, including deleting, team members, and sending lead data to other tools (webhooks, alert recipients).
Each endpoint below shows the level it needs. Calls also follow the role of the person who made the key: a key keeps working only while they are an admin of the sub-account.
Quick start
Pick your language once; every example on the page follows it.
Mark a job won and record what it was worth
Set the lead's status and deal value (in cents). Moving it to a pipeline stage works the same with stage_key.
Pick a calendar (GET /v1/calendars), find an open time (GET /v1/calendars/{calendar_id}/availability), then book it. The customer gets the usual confirmation and reminders unless you send notify_lead: false.
import os
import uuid
import requests
res = requests.post(
"https://api.ottopros.com/v1/leads",
headers={
"Authorization": f"Bearer {os.environ['API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"full_name": "Jane Smith",
"phone": "+15125550123",
"email": "jane@example.com",
"inquiry": "Roof leak over the garage",
},
)
print(res.json())
Text a customer
Sent from the sub-account's number, exactly like a text from the inbox. Add send_at to schedule it.
cURL
curl -X POST "https://api.ottopros.com/v1/messages" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"lead_id": "LEAD_ID",
"channel": "sms",
"body": "Hi Jane, we can come out Tuesday at 10."
}'
JavaScript
const res = await fetch("https://api.ottopros.com/v1/messages", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
lead_id: "LEAD_ID",
channel: "sms",
body: "Hi Jane, we can come out Tuesday at 10.",
}),
});
const { success, data, error } = await res.json();
Python
import os
import uuid
import requests
res = requests.post(
"https://api.ottopros.com/v1/messages",
headers={
"Authorization": f"Bearer {os.environ['API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"lead_id": "LEAD_ID",
"channel": "sms",
"body": "Hi Jane, we can come out Tuesday at 10.",
},
)
print(res.json())
AI assistants (MCP)
Claude, ChatGPT, Cursor and other assistants can run the sub-account through the MCP server at https://api.ottopros.com/mcp (Streamable HTTP, JSON-RPC 2.0). Use the same API key; the assistant can do exactly what the key allows, so a Read only key is a safe way to start.
Claude (web, desktop, mobile): custom connector
Settings → Connectors → Add custom connector. Name it, paste this URL, leave OAuth blank. Treat the URL like a password.
get_api_key_info — Access level, sub-account lock, rate limit, credit budget and 30-day usage of the connected key.
Sub-account setup
get_setup_checklist — Start here: what is configured, what is missing, and the tool that fixes each finding.
manage_offers — Offers: first text, follow-ups, AI notes, triggers. list / create / update / delete.
manage_calendars — Booking calendars, their hosts and their booking page: prices with options and add-ons, deposit, design, full days, shared schedule, booking questions. create / update / copy_design / generate_design.
manage_booking_menus — Service menus: one booking link listing several calendars in sections. list / create / update / delete / share_schedule / generate_design.
manage_calendar_routes — Calendar routing: which calendar each lead books on, from their answers or tags. list / create / update / delete / reorder / match.
business_hours — Time zone, weekly hours, days off, slot length. get / set.
manage_pipeline_stages — Add, rename, hide, reorder or delete pipeline stages.
manage_custom_fields — Custom lead fields. list / create / update / archive.
lead_routing — Round-robin assignment of new leads, in even turns or by percentage. get / set.
manage_alert_recipients — Who is texted or emailed about new leads and AI receptionist calls (admin scope to change).
manage_lead_sources — Private URLs that accept leads from any form or tool.
manage_outbound_webhooks — Push lead, appointment, message and AI receptionist call events to Zapier, Make or a CRM (admin scope).
knowledge_base — The FAQ the AI answers from. get / add / replace.
ai_receptionist — The AI that answers the phone. get / configure.
manage_smart_forms — Create a smart form, change its basics, questions (photos, prices on answers), instant estimate, service area and calendar routing, publish it.
configure_workspace_outreach — Auto-greet, AI replies, follow-ups, reminders, sending identity.
ai_texting — The AI texting agent and automatic texts: replies on/off, name, reply mode, first text, send window, reminders, missed-call text, prompt rules. get / set.
nurture_sequence — The automatic follow-up texts and emails. get / set / edit / enable / disable / clear.
business_profile — Name, industry, time zone, address, country, business phone and email. get / set.
list_phone_numbers — The sub-account's numbers and whether texting is ready.
Dashboard & inbox
get_overview — Dashboard numbers: leads, booked, speed to lead, AI replies, calls, and how many leads reached each pipeline stage.
get_usage — Credits used by tool and by day.
list_conversations — The Inbox: conversations with unread counts, last message and AI state.
update_conversation — Mark read / unread, archive / unarchive.
pause_lead_ai — Pause or resume the AI on one lead.
list_reply_suggestions — AI suggested replies waiting for approval.
decide_reply_suggestion — Approve (sends, charged like an AI reply) or dismiss a suggested reply.
list_calls — Phone calls with outcome and AI summary.
get_call — One call: summary, transcript, 15-minute recording link.
call_campaigns — AI calling campaigns: list with progress, or pause one.
busy_blocks — Team members' busy time from other software: list, set (add or replace by your id), remove, sync a window.
ai_lessons — The AI Brain: list lessons, add rules, switch off, reword or delete.
rate_ai_message — Thumbs up / down on an AI message to teach the AI.
invoices — Invoices, read only (deposit and balance invoices say so). list / get.
estimates — Estimates: list / get / the price book, and create (a draft with Good / Better / Best options), update, send to the lead, convert to an invoice, delete.
get_ad_insights — The sub-account's Ad Insights: spend, leads and cost per lead across its Meta ad accounts, per campaign and ad.
google_ads — Its Google Ads: the connection and conversions sent back, and live reports (campaigns, keywords, search terms...).
google_business — Google Business Profiles: profiles, reviews and replies, posts, Profile Optimizer runs.
map_rankings — Map Rankings: keywords, scans, one scan's grid and next steps.
business_listings — Business Listings: each directory's status and what's needed.
support_tickets — Support tickets and their messages.
ai_brain_photos — AI Brain photos the AI may send: list, add from a link, change, remove.
ai_brain_waiting — Questions waiting on you: list, answer (trains the AI, resumes it), dismiss.
get_sales_report — The Sales page: won jobs, parts, tips and profit by technician, lead source and tag.
list_activity — The Activity log: every change and who made it, access, messages, calls, automations and errors.
reviews — Review pages, who rated what, and a lead's review link.
CRM leads
list_recent_leads — Leads, newest first. Filter by tags (any or all), status, stage, assignee (a user id, me or unassigned), a name/email/phone search and since.
list_lead_tags — A sub-account's lead tags and how many leads carry each.
get_lead — One lead with its inquiry, address, custom fields, tags and timeline.
create_lead — Create a lead with inquiry, address, custom fields, stage and tags (de-duplicated by phone and email).
update_lead — Update any lead field, custom fields and stage; add, remove or replace tags.
delete_lead — Delete a lead, and its appointments too if asked (admin scope).
get_lead_timeline — Everything that happened with a lead.
add_lead_note — Add a note to a lead, tagging teammates (@mentions) if you like.
set_lead_stage — Move a lead to a pipeline stage.
manage_lead_note — Edit a note you wrote, or delete a note.
mark_do_not_contact — Stop all texts and emails to a lead (no undo).
list_pipeline_stages — The sub-account's pipeline stages.
Messaging
send_lead_message — Send a text or email to a lead, now or at a later time (send_at).
get_lead_conversation — The text and email thread with a lead.
list_messages — Message history across the sub-account.
get_message — One message with its delivery status.
get_message_limits — Today's sending limits and what is left.
manage_imessage — iMessage through the sub-account's own Macs: list_lines (health, Advanced mode, usage), update_line, send (a text or voice message as iMessage from one of them), react (a tapback on an iMessage).
Bookings
list_calendars — Booking calendars with their pricing, design and booking form.
get_calendar_availability — Open appointment slots, for the option and add-ons picked.
list_bookings — Appointments.
create_booking — Book an appointment, with the option and add-ons picked.
reschedule_booking — Move an appointment.
cancel_booking — Cancel an appointment.
update_booking — Record an appointment's outcome, change its title, notes, location, host or lead notifications, or link a hand-typed appointment to its lead.
Sub-accounts & team
list_workspaces — Your sub-accounts.
get_workspace — One sub-account.
update_workspace — Rename, re-time-zone or archive a sub-account; turn optional features on (Settings > Features) or hide features from its people.
list_workspace_members — Members and pending invites.
invite_workspace_member — Invite someone to a sub-account (admin scope).
update_workspace_member_role — Change a member's role (admin scope).
remove_workspace_member — Remove a member (admin scope).
Forms & automations
list_smart_forms — Smart forms with views and submissions.
list_form_submissions — Submissions of a form.
list_workspace_automations — A sub-account's automations.
enroll_leads_in_automation — Enroll leads in an automation (can send real messages). Leads already queued for it are skipped; ignore_filters defaults to false, so leads failing its only_if rules are skipped.
toggle_workspace_automation — Turn a sub-account automation on or off.
manage_workspace_automation — Build automations: reference / get / create / update / duplicate / delete (changes need admin scope). Triggers can name Smart Forms, calendars and Facebook forms; email steps can pick a sender; inbound webhooks return their URL.
workflow_enrollments — Who is in an automation, a lead's automations, and taking leads out.
Errors
Status
Meaning
What to do
400
Invalid request body or unknown action.
Fix the payload; retrying unchanged returns the same error.
401
Missing, malformed or revoked API key.
Re-copy the key from Settings → API.
402
The account is out of credits for this message or call, or the key's monthly credit budget is used up.
Add credits to the account, or raise the key's budget in Settings → API.
403
The key lacks the scope, or it is restricted to one sub-account and this endpoint is account-level.
Create a key with that scope in Settings → API. The response names the scope it needs.
404
Unknown route or record.
Check the path and the id.
409
Conflict, e.g. a lead with that phone or email already exists, or the lead is already booked at that time. Also idempotency_in_progress: the first request with this Idempotency-Key is still running.
Use the id returned in details. For idempotency_in_progress, send the request again with the same key a moment later.
429
Per-key rate limit exceeded.
Wait for Retry-After seconds; read X-RateLimit-Remaining.
503
Pricing or a limit check is temporarily unavailable. Nothing was charged.
Retry with exponential backoff.
5xx
Transient server or upstream failure.
Retry with exponential backoff.
Limits and conventions
Authentication
Send your key as Authorization: Bearer zu-.... Admins of a sub-account create keys in the CRM under Settings → API. A key works inside its own sub-account only: you can leave out workspace_id everywhere, a different one is ignored, and records of any other sub-account answer 404. Access levels: Read only, Read and write, or Full access (deleting things, team members and anything that sends lead data outside the account). Every call also follows the role of the person who made the key: a key keeps working only while they are an admin of the sub-account.
Idempotency
Every write (POST, PUT, PATCH, DELETE) accepts Idempotency-Key: <your-unique-string>. Replaying the same key with the same body within 24 hours returns the original response instead of doing the work twice (no second message, no second booking); the same key with a different body answers 409. Use a fresh key per logical operation, not per retry.
Rate limits
Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. On 429 a Retry-After header (and retry_after_seconds in the body) tells you how long to wait. The limit is per key, per minute: 120 by default, adjustable from 1 to 600 in Settings → API.
Pagination
List endpoints accept limit (default 50, max 200) and return the newest rows first. GET /v1/messages is the one endpoint with a cursor: pass cursor (or since) and follow next_cursor to walk forward without duplicates.
Messaging safety limits
To protect number reputation, each sub-account can message at most 300 unique contacts per UTC day (plus per-minute burst and daily segment caps). Replying to a contact you already messaged that day does not consume another contact slot. Messaging endpoints return X-Contacts-Limit, X-Contacts-Used, X-Contacts-Remaining and X-Contacts-Reset; over the cap sends answer 429 with code: "sms_limit" and a limit object. Check the current state any time with GET /v1/messages/limits. Need a higher ceiling? Request a limit increase from Settings → Messaging and we'll review it.
Responses and errors
Success is { success: true, data, error: null }. Errors are { success: false, data: null, error: string, details?: object } with a matching HTTP status; scope, rate-limit and budget errors put a machine-readable code in error (scope_denied, rate_limit_exceeded, credit_limit_exceeded) and the explanation in message. Branch on the status and the code, not on message text.
Webhooks
Get events pushed to your own URL: set a webhook up in Settings → Leads → Outbound webhooks, or with POST /v1/outbound-webhooks below.
Event
When it fires
lead.created
A lead was captured for this sub-account. Payload is a full lead snapshot including custom form fields.
lead.updated
The lead's status or pipeline stage changed (other field edits do not fire it). Payload carries previous_status, status, previous_stage_key and stage_key.
lead.qualified
The lead was marked qualified.
appointment.booked
An appointment was booked for the lead.
appointment.rescheduled
An appointment moved to a new time, in the CRM calendar, through the API or by an inbound webhook. Payload carries booking_id, lead_id, the new starts_at / ends_at, timezone, host, calendar, meeting and moved_via (app, api or inbound_webhook).
appointment.cancelled
A booked appointment was cancelled.
message.received
An inbound SMS or email arrived on this sub-account's number or inbox. Payload carries message_id, lead_id, channel, direction, body, from/to and media_urls, and transport (imessage or mac_sms) when it came in on one of the sub-account's iMessage Macs.
message.sent
An outbound SMS or email was handed to the carrier or mail provider — manual, automated or API-sent. Texts carry transport: sms from the business number, imessage or mac_sms when one of the sub-account's Macs sent it.
message.failed
An outbound message could not be sent. Payload includes the error and, when the contact-safety cap was hit, a limit object.
call.completed
An AI receptionist call ended (once per call, after its recap is written; practice calls from Settings excluded). Payload carries call_id, lead_id (null for a caller with no lead), from/to, status, duration_sec, outcome, summary, booking_id and started_at / ended_at. The transcript and recording: GET /v1/calls/{call_id}.
deal.updated
A lead was marked won, or a won lead's amount or plan changed later (an amount added from Ad Insights, a plan edited). Payload carries deal_type (one_time or plan), deal_value_cents (the first payment), deal_plan_cents, deal_plan_interval, deal_monthly_cents and deal_expected_total_cents, plus the lead snapshot. Every lead event's snapshot carries the same deal fields.
Verify each delivery: X-Webhook-Signature: sha256=<hex hmac>. Each delivery is signed with HMAC-SHA256 over the exact raw request body using the webhook's secret (shown once when it is created). Compute the HMAC over the raw bytes, before JSON parsing, and compare in constant time. X-Webhook-Event carries the event name and X-Webhook-Delivery a unique delivery id you can use to de-duplicate retries.
Start here. Returns the sub-account's real configuration (numbers, AI texting, receptionist, calendars, forms, automations, offers, team, lead sources, integrations) and a severity-ranked list of findings. Each finding names the API call and MCP tool that fixes it, or says when it can only be done in the app (buying a number, SMS registration, connecting Google or Outlook).
Send only what changes. A new time zone also moves the booking hours' time zone, as in the app.
Parameter
Description
name
body · string
Max 120.
industry
body · string
Max 80.
timezone
body · string
IANA zone, e.g. America/Chicago.
address_line1
body · string
Street.
address_line2
body · string
Suite, unit.
city
body · string
City.
state
body · string
State or region.
postal_code
body · string
ZIP or postal code.
country
body · string
Two-letter country code (US, CA, GB, AU; "United States" works too), or null. It picks the State list on leads, forms and booking pages, and the list a lead's state is matched against when the lead has no phone.
Number, name, default, capabilities, texting registration and caller-name status, and who may use it: assigned_user_id (a number that belongs to one team member: it rings only them and other technicians can't text from it), tech_can_answer and tech_can_use (whether it rings technicians and whether they may call and text from it). Buying and releasing numbers is done in the app. iMessage Macs: GET /v1/imessage/lines.
Offers (offer playbooks) tell the AI what this business sells to a lead: the first text, the follow-up sequence, notes for the AI and the booking link.
First text to a new lead. Supports {{first_name}} (max 1600).
nurture_enabled
body · boolean
null follows the sub-account's own follow-up setting.
nurture_steps
body · array
Up to 12 follow-ups: { offset_minutes, body_template }. offset_minutes counts from the previous message.
ai_context_note
body · string
What the AI should know about this offer (max 2000).
booking_link
body · string
Public http(s) URL.
is_active
body · boolean
Default true.
smart_first_text_enabled
body · boolean
true: the AI writes the first text for these leads (first_message_template is the backup); false: first_message_template goes out as written; null (default) follows the sub-account's smart first text switch.
smart_first_text_instructions
body · string
What the smart first text should do for these leads (max 1000). Empty uses the sub-account's instructions.
triggers
body · array
Which leads get this offer: { type, value, label? }. type is meta_form, smart_form, webhook (a lead source id) or source (the lead's source text). Form and lead-source ids must belong to the sub-account.
Request
cURL
curl -X POST "https://api.ottopros.com/v1/offers" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Free roof inspection",
"offer_label": "a free 20-point roof inspection",
"first_message_template": "Hi {{first_name}}, thanks for asking about a free roof inspection. What day works best?",
"nurture_steps": [
{
"offset_minutes": 60,
"body_template": "Still want that inspection?"
}
],
"triggers": [
{
"type": "source",
"value": "Website form"
}
]
}'
JavaScript
const res = await fetch("https://api.ottopros.com/v1/offers", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
name: "Free roof inspection",
offer_label: "a free 20-point roof inspection",
first_message_template: "Hi {{first_name}}, thanks for asking about a free roof inspection. What day works best?",
nurture_steps: [
{
offset_minutes: 60,
body_template: "Still want that inspection?",
},
],
triggers: [
{
type: "source",
value: "Website form",
},
],
}),
});
const { success, data, error } = await res.json();
Python
import os
import uuid
import requests
res = requests.post(
"https://api.ottopros.com/v1/offers",
headers={
"Authorization": f"Bearer {os.environ['API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"name": "Free roof inspection",
"offer_label": "a free 20-point roof inspection",
"first_message_template": "Hi {{first_name}}, thanks for asking about a free roof inspection. What day works best?",
"nurture_steps": [
{
"offset_minutes": 60,
"body_template": "Still want that inspection?",
},
],
"triggers": [
{
"type": "source",
"value": "Website form",
},
],
},
)
print(res.json())
A new calendar has no host unless host_user_id or hosts is sent. Hosts must be members of the sub-account (GET /v1/members). The response is the calendar as GET /v1/calendars shows it, with its public booking path (/c/<slug>). Calendars are switched off with is_active=false rather than deleted. The booking page can show prices with options and add-ons and take a deposit (pricing), have its own look (design), book whole working days (duration_days), share one schedule with other calendars (schedule_group) and ask its own questions (questions). Taking money at booking needs Stripe, Authorize.net or Whop connected to the sub-account in the app first.
Parameter
Description
name
body · string · required
Calendar name (max 80).
title
body · string
Shown to the person booking.
duration_minutes
body · number
5-1440, default 30.
buffer_minutes
body · number
0-1440, default 0. Always saved as 0 on an arrival_window calendar (a window books the whole window and pads nothing), as in the app.
min_notice_minutes
body · number
Default 60.
max_days_ahead
body · number
1-365, default 14.
timezone
body · string
IANA zone, e.g. America/Chicago. Defaults to the sub-account's.
weekly_hours
body · object
Per day, 24h HH:MM windows: {"mon":[["09:00","17:00"]],"sat":[]}. Default Mon-Fri 9-5.
date_overrides
body · array
Days off or special hours: [{"date":"2026-12-25","pairs":[]}].
assignment_mode
body · string
Who takes the booking. Default unassigned (no host), or single when host_user_id is sent.
One of: single, round_robin, collective, unassigned
host_user_id
body · string
Host of a single-host calendar (required for single).
hosts
body · array
User ids sharing a round_robin / collective calendar.
meeting_type
body · string
Default phone. in_person: the customer comes to meeting_location (studio, shop, office). customer_address: the team goes to the customer's home, and the booking page asks for their address.
One of: zoom, google_meet, phone, phone_attendee, in_person, customer_address, custom
scheduling_mode
body · string
exact times, or an arrival window for trades.
One of: exact, arrival_window
arrival_window_minutes
body · number
15-720.
appointment_texts
body · object
Confirmation and reminder texts for appointments on this calendar, keyed by confirmation, reminder_24h, reminder_1h, reminder_5m. Each takes {"mode":"custom","template":"..."} (this wording, sent even when the sub-account has that text off), {"mode":"off"} (never sent for this calendar), or null / {"mode":"inherit"} (the sub-account's text, the default). Only the texts you name change.
slots_per_window
body · number
1-50: how many jobs can run at the same moment (crews).
duration_days
body · number
Full-day jobs, 1-14 working days: each booking runs from opening time on its first day to closing time on its last, skipping closed days. null = timed by duration_minutes.
schedule_group
body · string
Shared schedule name (max 60): calendars with the same group count each other's bookings, so one crew's time is never sold twice across services. null = its own schedule.
pricing
body · object
Prices on the booking page. Merged into what the calendar has, except options and addons, which replace their lists (send each row's id to keep it; ids come back in GET /v1/calendars). Money in cents. { enabled, show_prices, price_cents (no options), price_note (max 160), options_label ("Vehicle size"), options: [{ id?, name (max 80), description?, price_cents, duration_minutes (5-1440, its own job length), duration_days (full-day calendars), image_url? }] (max 24; the customer picks one), addons_label, addons: [{ id?, name, description?, price_cents, extra_minutes (0-720), image_url? }] (max 24), deposit: { mode: none | fixed | percent | full, amount_cents, percent (1-100) } }. A calendar that never had pricing switches it on unless enabled is false; null clears it. A deposit needs a connected gateway.
design
body · object
The booking page look, merged into the current design. { enabled, preset (clean, showroom, midnight, fresh, warm, bold, ocean, spa, mono, graphite: applied first), mode: light | dark | auto, colors: { background, surface, text, button } (#rrggbb, merged), font, heading_font ("match" or a font), radius: sharp | soft | rounded | pill, button_style: solid | soft | outline, backdrop: solid | glow | photo, logo_url, cover_url (https), hide_avatar, custom_css (max 12000) }. Fonts: inter, poppins, dm-sans, space-grotesk, manrope, outfit, figtree, plus-jakarta, work-sans, rubik, nunito-sans, montserrat, raleway, urbanist, sora, lexend, archivo, barlow, karla, public-sans, bricolage, bebas, anton, archivo-black, syne, clash, oswald, playfair, dm-serif, lora, libre-baskerville, cormorant, instrument-serif, fraunces, source-serif, merriweather, jetbrains-mono, space-mono, ibm-plex-mono, system. A page that never had a design switches it on unless enabled is false; null = the classic page. It carries into embeds and custom domains.
questions
body · array
The calendar's own booking questions, up to 30, replacing the list: [{ key?, label (max 160), field_type: text | textarea | number | money | phone | email | url | select | multiselect | boolean | date | datetime | rating | file (photos or PDFs, up to 6), options (select / multiselect: 2-40), option_style?, required?, enabled?, save_to_crm? (never for file), placeholder?, helper_text? }]. Answers show on the appointment and the lead.
fields
body · object
Contact fields on the booking form, merged: {"address":{"enabled":true,"required":true,"autocomplete":true},"email":{"required":false}}. Keys: full_name, first_name, last_name, email, phone, address, state, notes. Phone or email stays on; full_name or first_name + last_name.
image_url
body · string
The service's photo (https): on its booking page and its service menu card.
currency
body · string
Prices and payments in this currency.
One of: usd, cad, gbp, eur, aud
payment_gateway
body · string
Charge through this connected gateway; null = whichever is connected (Stripe first).
One of: stripe, authorize_net, whop
payment_hold_minutes
body · number
15-120: how long the time is held while they pay.
payment_label
body · string
What the checkout calls the payment, e.g. "Deposit" (max 60).
Takes the same fields as create; send only what changes. hosts, when sent, replaces the pool; people who stay keep their place in the rotation. An arrival_window calendar always keeps buffer_minutes at 0 (a full-day one keeps its buffer). appointment_texts changes only the texts it names. pricing, design and fields merge; pricing.options, pricing.addons and questions replace their lists. Turning pricing off also stops taking payment at booking.
The Design tab's "Use on other calendars": this calendar's design goes onto the calendars named (or every other calendar of the sub-account with all: true), switched on. A calendar that has its own cover photo keeps it. The calendar must have a design switched on.
The Design tab's AI designer: describe the look in one line and/or give the business's website (its colours, fonts and logo are read from it). Returns the design and a one-line summary, and saves it on the calendar unless save is false. readable says whether the text reads well on the card. No credits used.
Parameter
Description
calendar_id
path · string · required
Calendar id.
instruction
body · string
What it should look like, e.g. "black and gold, like a luxury showroom" (max 1200).
website_url
body · string
The business's website.
save
body · boolean
Default true. false only returns the design (send it later with PATCH design).
Request
cURL
curl -X POST "https://api.ottopros.com/v1/calendars/CALENDAR_ID/design/generate" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"instruction": "black and gold, like a luxury showroom",
"website_url": "https://example.com"
}'
Service menus (Calendars → Booking tools → Service menu): one booking link (/c/<slug>, public_path) that lists several calendars in sections, with search, category chips and sorting; the customer picks a service and books it there. Each section lists its services with their price and length as the page shows them. warnings says when its services are on separate schedules (two customers could book the same time on different services) or switched off.
Without sections it starts like the app's: one "Services" section with every calendar that is switched on, and a link named after the business. The link shares /c/ with calendars, so a slug a calendar or another menu uses answers 409.
Parameter
Description
title
body · string
Heading customers see (max 120). Default "Book a service".
name
body · string
Internal name (max 80). Default "All services".
description
body · string
Under the heading (max 600).
slug
body · string
Link name: /c/<slug> (letters, numbers, dashes; max 40).
sections
body · array
In order, replacing the list: [{ id?, title (max 80), description?, calendar_ids: [calendar ids, in the order shown] }]. Up to 30 sections; every calendar must belong to the sub-account.
options
body · object
Merged: { show_prices, show_durations, search, filters (category chips), sorting, default_sort: featured | price_low | price_high | shortest | name }. All on by default.
design
body · object
The page look, the same shape as a calendar's design. It carries into each service's booking flow opened from the menu.
The menu editor's "Share one schedule": every calendar on the menu gets the same schedule_group, so a booking on any of them takes that time on all of them (one crew doing every service). group names it; by default the group one of them already has, else the menu's title.
Calendar routing (Calendars -> Calendar routing in the app) sends each lead to the calendar that fits their answers: "Player group is Girls 13-14 -> Girls 13-14 calendar". Rules are checked in order (position 1 first); the first rule whose conditions ALL match the lead's custom fields or tags picks the calendar. Smart Forms with calendar_routing on, the AI texter and the AI caller follow them. Each rule comes with its calendar's name and a readable summary. Rules that are switched off, or whose calendar is off, are skipped.
Added last unless you send position. Conditions: a field condition reads a custom field by key (GET /v1/custom-fields) with op is, is_not or contains and values (any one matches), or op between with min and/or max for numbers ("11 years old" counts as 11); a tag condition (kind tag, op is or is_not) reads the lead's tags. Answers compare ignoring case, accents and punctuation. The calendar must belong to the sub-account. warnings explains a rule that may never fire (a key that is not a custom field, a calendar that is switched off). Owners and admins only; at most 200 rules.
Parameter
Description
calendar_id
body · string · required
The calendar this rule books on (GET /v1/calendars).
conditions
body · array · required
All must match, 1-20: [{"kind":"field","key":"player_group","op":"is","values":["Girls 13-14"]}], [{"kind":"field","key":"age","op":"between","min":9,"max":12}], [{"kind":"tag","op":"is","values":["VIP"]}].
Send any of calendar_id, name, conditions (replaces the list) and is_active. To move a rule use POST /v1/calendar-routes/reorder. Owners and admins only.
The first rule that matches wins, so put narrower rules first. order lists every rule id of the sub-account exactly once, first to last. Answers the rules in their new order. Owners and admins only.
Runs the rules the way the booking paths do (active rules on calendars that are on) against a lead's custom fields and tags, and/or answers you pass. status: matched (calendar and the route that won), pending (no rule matched yet but one still can: missing_fields are the answers to ask for before offering times), unmatched (no rule fits: the form's or the AI's own calendar applies), or no_rules. Viewers limited to their own leads only reach those leads.
Parameter
Description
lead_id
query · string
The lead to route. Send lead_id, answers or both.
answers
query · string
JSON object of field key to answer to try, laid over the lead's own, e.g. {"player_group":"Girls 13-14"}.
For a schedule kept in other software (a field-service app, a dispatch board): the person is treated as booked for that time, so the AI (text, chat and phone), Smart Forms, booking pages and round robin only offer times when they are free. external_id is YOUR id for the block (a job or visit id, URL-encoded in the path); sending the same id again replaces the block, so it is safe to resend. A block can make several people busy (a two-tech job). Team members are named by user id or email (GET /v1/members); technicians must be invited as members first. Times need a time zone (Z or an offset). At most 31 days per block. 201 when created, 200 when replaced (changed: false when nothing differed). Owners and admins of the sub-account only.
Parameter
Description
external_id
path · string · required
Your own id for the block: 1-200 letters, digits or . _ : ~ @ # | + = -
team_member
body · string
The busy person: a team member's user id or email. Or team_members for several.
team_members
body · array
Several busy people (user ids or emails), up to 50.
starts_at
body · string · required
ISO 8601 with a zone, e.g. 2026-10-14T08:00:00-05:00.
ends_at
body · string · required
ISO 8601 with a zone; after starts_at.
title
body · string
Optional note shown to the team in the CRM calendar (never to leads or the AI), max 200.
Send your full list of busy blocks for a window: blocks in the list are added or replaced, and blocks you sent earlier that START inside [from, to) but are no longer in the list are removed (cancelled or moved jobs). With team_member, only that person's blocks are replaced and each block defaults to them; a removed block that also names other people keeps them. Up to 500 blocks per call. Good for a nightly or hourly full sync next to the per-block calls. Owners and admins only.
Assigns NEW LEADS to team members in turn. (A round-robin calendar is separate: it rotates appointment hosts.) An empty eligible_member_ids list means everyone takes turns. member_weights splits leads by percentage (80/20 gives one person 8 of every 10 leads, spread out); {} goes back to even turns.
Parameter
Description
round_robin_enabled
body · boolean
Turn the rotation on or off.
eligible_member_ids
body · array
User ids from GET /v1/members. Empty = everyone.
member_weights
body · object
Percentage split by user id (GET /v1/members): {"<user_id>": 80, "<other_user_id>": 20}. Whole percents 0-100; the shares above 0 must add up to exactly 100. Sets eligible_member_ids to the people with a share and restarts the rotation. {} = even turns (keeps who is in the rotation).
Returns a URL any website form, landing page tool or CRM can POST leads (or appointments) to.
Parameter
Description
name
body · string · required
e.g. Website contact form.
field_mapping
body · object
Their field name to ours: {"Full Name":"full_name","Roof size":"custom:roof_size"}. Targets: full_name, email, phone, address, city, state, zip, inquiry, notes, appointment_* or custom:<field_key>. A state is saved as its code ("Texas" becomes TX).
default_source
body · string
Source label stamped on these leads.
default_status
body · string
Default new.
payload_kind
body · string
Default auto. update = a form your own team fills in (e.g. during a call): its answers go onto the matching contact (lead_id, phone, then email; added quietly when nobody matches) and nothing is sent: no first text, team alert, Instant Lead Connect call or new-lead automation.
Pushes lead and appointment events to another system (Zapier, Make, a CRM). Lead data leaves the account, so every write needs an admin-scoped key and target_url must be https on a public host. The signing secret is returned once.
Parameter
Description
name
body · string · required
e.g. Zapier: new leads.
target_url
body · string · required
https:// URL that receives the POST.
events
body · array
Default lead.created and appointment.booked. See the sub-account webhook events list.
enabled
body · boolean
Default true.
preset
body · string
Payload flavour.
One of: zapier, make, salesforce_flow, service_titan, custom
auth_type
body · string
Default none. Send auth_token (and auth_header_name or auth_username) with it. Write-only.
Photos of the business's work the AI may text a customer who asks to see some (up to 100): link, caption, the service it shows, on / off, how often it was sent. Owners and admins.
From a public link to a JPEG, PNG or WebP (10 MB at most), stored like an upload on the page. The AI writes the caption and service you leave out, which is how it picks the right photo. 409 at 100 photos.
AI Brain > Waiting on you: questions customers asked (texts, chat, DMs, calls) that the AI couldn't answer and handed to the team, newest first, one row per question (times = how many customers asked, variants = how they wrote it). Answered and dismissed ones are left out. Owners and admins.
As Answer it on the page: the answer becomes a saved answer (replacing one to the same question) that the AI texter and receptionist use from now on, the question leaves the list, and the AI turns back on for the leads it was paused on for that question. Nothing is sent to the customer.
Parameter
Description
question
body · string · required
The question as listed.
answer
body · string · required
What the AI should say (max 2000).
event_id
body · string
The row's event_id.
Request
cURL
curl -X POST "https://api.ottopros.com/v1/ai-brain/waiting/answer" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"event_id": "uuid",
"question": "Do you work on Sundays?",
"answer": "No, we'\''re open Monday to Saturday, 8 to 6."
}'
JavaScript
const res = await fetch("https://api.ottopros.com/v1/ai-brain/waiting/answer", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
event_id: "uuid",
question: "Do you work on Sundays?",
answer: "No, we're open Monday to Saturday, 8 to 6.",
}),
});
const { success, data, error } = await res.json();
Python
import os
import uuid
import requests
res = requests.post(
"https://api.ottopros.com/v1/ai-brain/waiting/answer",
headers={
"Authorization": f"Bearer {os.environ['API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"event_id": "uuid",
"question": "Do you work on Sundays?",
"answer": "No, we're open Monday to Saturday, 8 to 6.",
},
)
print(res.json())
The AI that answers the sub-account's phone. Answered calls bill 1.5 credits per minute of AI conversation (15-second steps; time after a transfer to a person bills as phone minutes), and it needs a phone number on the sub-account to do anything (the response carries a warning when there is none).
Parameter
Description
enabled
body · boolean
Turn it on or off.
mode
body · string
Every call, or only outside business hours.
One of: always, after_hours
goal
body · string
What it tries to do.
One of: book, support, book_and_support
agent_name
body · string
Max 40.
voice
body · string
One of the voices returned by GET.
greeting
body · string
Max 400.
after_hours_greeting
body · string
Max 400.
extra_instructions
body · string
Max 1200.
transfer_enabled
body · boolean
Allow transfers to a person.
transfer_numbers
body · array
Up to 8 phone numbers.
take_messages
body · boolean
Take a message when nobody is available.
max_call_seconds
body · number
60-1800.
record_calls
body · boolean
Record answered calls (billed per recorded minute).
update_contact_details
body · boolean
Let it save the caller's name, email and address to the lead.
collect_fields
body · array
Details it asks for before booking: "address", "email" or custom field keys (GET /v1/custom-fields). Max 12.
Read the AI texting agent and automatic text settings
GET/v1/ai-texting
Read only
AI replies, agent name, reply mode, goal, what it knows, booking link, first text, send window, hand-off, confirmation and reminder texts, missed-call text-back, email greeting, and a preview of its prompt. Says whether the sub-account has a phone number.
Send only the settings to change, by these names: ai_replies, agent_name, reply_mode (auto | suggest), goal (book_appointment | collect_details | customer_support), business_context, booking_link, max_replies (1-15), reply_delay_minutes (1-120), ai_can_cancel, handoff_when_unsure, pause_ai_on_handoff, handoff_resume_days (0, 1, 2, 3, 7), greet_new_leads, first_message, smart_first_text (the AI writes each new lead's first text from their answers and the right calendar's open times; first_message becomes the backup), smart_first_text_goal (what that text should get them to do; empty = book an appointment), greet_delay_minutes, form_greet_delay_minutes, missed_call_text, missed_call_message, confirmation_text, confirmation_message, confirmation_email (the confirmation email with a calendar invite, plus the move and cancel emails), confirmation_email_language (en | es), reminder_24h, reminder_24h_message, reminder_1h, reminder_1h_message, reminder_5m (the 5-minute reminder, off by default), reminder_5m_message, email_greeting, email_greeting_subject, email_greeting_body, send_window (anytime | daily | booking_hours), send_window_start, send_window_end ("HH:MM"), ai_answers_email, prompt_addition (one more rule) or prompt (a full rewrite). Owners, agency admins and client admins can change these. Turning AI replies on lets it answer conversations still waiting for a reply.
Parameter
Description
ai_replies
body · boolean
The AI answers leads by text.
agent_name
body · string
First name the AI texts as (max 40).
reply_mode
body · string
suggest = drafts each reply for a teammate to approve (GET /v1/reply-suggestions).
One of: auto, suggest
first_message
body · string
First text to a new lead. Variables {first_name}, {agent}, {business}, {service}.
send_window
body · string
When automated texts may go out.
One of: anytime, daily, booking_hours
prompt_addition
body · string
A rule added to the end of the AI's prompt (max 2000).
Replaces one channel's steps and turns it on. Timing is the app's: the first 3 hours after the first text, then front-loaded days over span_days (about 5 days per message, at most 60), or the explicit days you send. At most 40 texts or 60 emails; email needs a verified sending domain. Pending sends that would change channel are cancelled.
Parameter
Description
channel
body · string
Default sms.
One of: sms, email
messages
body · array · required
One message per step, in order.
subjects
body · array
Email only: one subject per message.
span_days
body · number
Days from the first message to the last (1-365).
days
body · array
Instead of span_days: the day each message goes out, going up. 0 = 3 hours in.
enabled
body · boolean
Default true.
Request
cURL
curl -X PUT "https://api.ottopros.com/v1/nurture-sequence" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"channel": "sms",
"messages": [
"Hi {first_name}, still looking for a quote?",
"Quick check-in from {business}: want me to hold a time for you?"
],
"span_days": 7
}'
JavaScript
const res = await fetch("https://api.ottopros.com/v1/nurture-sequence", {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
channel: "sms",
messages: [
"Hi {first_name}, still looking for a quote?",
"Quick check-in from {business}: want me to hold a time for you?",
],
span_days: 7,
}),
});
const { success, data, error } = await res.json();
Python
import os
import uuid
import requests
res = requests.put(
"https://api.ottopros.com/v1/nurture-sequence",
headers={
"Authorization": f"Bearer {os.environ['API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"channel": "sms",
"messages": [
"Hi {first_name}, still looking for a quote?",
"Quick check-in from {business}: want me to hold a time for you?",
],
"span_days": 7,
},
)
print(res.json())
New leads, booked leads and appointments (each with the previous window of the same length for comparison), upcoming appointments, contacted, won and closed, speed to lead (median minutes to the first reply: anyone, AI or automation, a person), AI replies sent, calls (answered, missed, voicemails, AI calls, talk time), and stage_reach: of the leads created in the window, how many reached each pipeline stage (total, and reached keyed by stage key from GET /v1/stages; a lead counts for every stage it has been in, so a lead that sat and then won counts for both; the Overview's "<Stage> rate" cards divide reached by total). Moves made before 2026-10-16 are not known. stage_reach is null if it could not be read. Viewers limited to their own leads see only those.
Parameter
Description
days
query · number
1-365, default 30.
from
query · string
ISO start, instead of days (window at most 366 days).
What the sub-account spent in a window, by tool (the Usage tab's names: texts, lead alert texts, email, AI text replies, website chat widget, AI agents, phone calls, AI receptionist, AI calling, phone numbers, ad tools) and by day. unpaid counts events that ran while the account was out of credits.
Settings > Features > Sales (off until an owner or admin turns it on: 403 feature_off until then). Won jobs in the window by the date they were won, as the Sales page adds them up: what customers paid, parts, tips and profit in total, per technician (deal_sold_by, else whoever the lead is assigned to), per lead source and per tag, plus the jobs themselves. Every group also has plans, monthly_cents (the monthly revenue its new plans add) and expected_cents (what its jobs are expected to bring in, one-time jobs at their amount), and each job its deal_type and plan (Plans & memberships). Record a sale with PATCH /v1/leads/{lead_id}: status won, deal_value_cents, deal_parts_cents, deal_tip_cents, deal_sold_by. Owners and admins only.
Everything that happened in the sub-account, newest first, as Settings > Activity log shows it: every change (the fields that changed, before and after, secrets hidden) with who made it (a person, an API key, the AI or an automation), their IP and browser, who opened what (contacts, conversations, recordings, exports), and messages, calls, bookings, automation runs, notifications and errors. Keyset paged by next_cursor. summary=true adds the page's counts by type and by day and who did the most. Owners and admins only.
Every lead with a message either way (or an unread one), like the Inbox: unread count, archive state, whether the AI is paused on it (and the question it handed to the team), and the last message or call. The first page also returns the Inbox counts. Read the thread with GET /v1/leads/{lead_id}/conversation.
Parameter
Description
archived
query · boolean
true = the Archived tab. Default false.
unread
query · boolean
Only unread conversations.
assigned_to
query · string
A user id, "me" or "unassigned".
search
query · string
Name, email or phone contains (2-80 characters).
imessage_line_id
query · string
Only the conversations this iMessage Mac has had (GET /v1/imessage/lines), like the Inbox's number filter.
paused: true stops AI replies to this lead (and its automatic follow-ups at send time) until someone turns it back on, or until until. paused: false turns it back on and clears any hand-off. The sub-account-wide switch is ai_replies on PATCH /v1/ai-texting.
Parameter
Description
lead_id
path · string · required
Lead id.
paused
body · boolean · required
Pause (true) or resume (false).
until
body · string
ISO time the AI turns itself back on (paused: true only, at most a year away).
When AI texting's reply_mode is suggest, the AI drafts its reply to each text or email here instead of sending it. Each one shows the lead, the draft, and the appointment it would book or cancel. reply_mode in the response says whether the sub-account is in suggest mode.
Parameter
Description
status
query · string
Default pending.
One of: pending, sending, sent, dismissed, superseded, failed, all
Sends it to the lead as the AI (edited, if you send body), makes the booking or cancellation it decided on, and is charged exactly like an automatic AI reply plus the text, through the same code as the Inbox's Send button. Owners and admins only. 409 = someone already answered or the lead wrote again (nothing sent), 422 = not sent for a reason in error (e.g. AI paused, out of credits, that time is no longer open), 503 = a sending hiccup, try again.
Parameter
Description
suggestion_id
path · string · required
Suggestion id.
body
body · string
The edited reply to send instead (texts up to 1600 characters, emails 5000).
Request
cURL
curl -X POST "https://api.ottopros.com/v1/reply-suggestions/SUGGESTION_ID/approve" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"body": "Thursday at 2pm works! See you then."
}'
JavaScript
const res = await fetch("https://api.ottopros.com/v1/reply-suggestions/SUGGESTION_ID/approve", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
body: "Thursday at 2pm works! See you then.",
}),
});
const { success, data, error } = await res.json();
Python
import os
import uuid
import requests
res = requests.post(
"https://api.ottopros.com/v1/reply-suggestions/SUGGESTION_ID/approve",
headers={
"Authorization": f"Bearer {os.environ['API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"body": "Thursday at 2pm works! See you then.",
},
)
print(res.json())
Every call on the sub-account's numbers: direction, type (softphone, bridge, inbound, forward, ai, ai_receptionist), status, duration, voicemail, the AI's outcome and summary, and the lead. Get one for its transcript and recording.
Parameter
Description
direction
query · string
Inbound or outbound.
One of: inbound, outbound
type
query · string
Call type.
One of: softphone, bridge, inbound, forward, ai, ai_receptionist
Settings → AI Brain: rules (instructions every AI reply follows), good examples (thumbs up) and lessons (thumbs down: what was wrong, a better reply, never send anything like it again). The AI texter and the voice agent read the active ones on every reply. Owners and admins only.
Like Add rule in Settings → AI Brain. channel limits it to texts (sms), email or calls (voice); leave it out for everywhere. To teach from a specific reply, rate it (POST /v1/messages/{message_id}/rating). Owners and admins only; at most 200 rules.
What can change depends on the kind, as in the app: a rule's note, channel and active; a thumbs-down lesson's note, better_reply, never_again and active; a good example's active only.
Exactly the Inbox's rating. up keeps the reply as a good example; down records what was wrong (reasons), what it should have said (better_reply), a note, and by default never to send anything close again; clear removes the rating. Rating the same message again replaces its lesson. Works on messages and calls sent to the lead (message ids from GET /v1/leads/{lead_id}/conversation). Owners and admins only.
Parameter
Description
message_id
path · string · required
The message (lead event) id.
rating
body · string · required
up, down or clear.
One of: up, down, clear
reasons
body · array
down only: wrong_info, too_pushy, too_long, missed_question, wrong_tone, should_not_reply.
better_reply
body · string
down only: what it should have said (max 2000).
note
body · string
down only: a note (max 600).
never_again
body · boolean
down only. Default true.
Request
cURL
curl -X POST "https://api.ottopros.com/v1/messages/MESSAGE_ID/rating" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"rating": "down",
"reasons": [
"too_pushy"
],
"better_reply": "No rush at all, happy to answer any questions first."
}'
JavaScript
const res = await fetch("https://api.ottopros.com/v1/messages/MESSAGE_ID/rating", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
rating: "down",
reasons: ["too_pushy"],
better_reply: "No rush at all, happy to answer any questions first.",
}),
});
const { success, data, error } = await res.json();
Python
import os
import uuid
import requests
res = requests.post(
"https://api.ottopros.com/v1/messages/MESSAGE_ID/rating",
headers={
"Authorization": f"Bearer {os.environ['API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"rating": "down",
"reasons": ["too_pushy"],
"better_reply": "No rush at all, happy to answer any questions first.",
},
)
print(res.json())
Response 200
JSON
{
"success": true,
"data": {
"message_id": "uuid",
"rating": "down",
"lesson_id": "uuid",
"lesson": {
"id": "uuid",
"kind": "avoid",
"channel": "sms",
"ai_message": "Book now before slots fill up!",
"better_reply": "No rush at all, happy to answer any questions first.",
"reasons": [
"too_pushy"
],
"never_again": true,
"active": true
}
},
"error": null
}
Newest first. Filter by tags (tag_match=any returns leads with at least one of the tags, all leads with every one), status, pipeline stage, assignee, a name / email / phone search and a created-since time. Each lead carries inquiry (the CRM's Inquiry column), address, city, state, zip, custom_fields, tags and stage (the pipeline stage it shows in). Page with limit and offset: next_offset is set while there are more.
Parameter
Description
tags
query · string
Tag names, comma-separated (tags=VIP,Roof), or a JSON array (tags=["Roof, metal","VIP"]) when a name has a comma. Max 10.
tag_match
query · string
any (default): at least one of the tags. all: every tag.
One of: any, all. Default: any
status
query · string
One or more statuses, comma-separated: new, contacted, qualified, booked, won, lost, spam, partial.
stage_key
query · string
Pipeline stage key from GET /v1/stages.
assigned_to
query · string
A user id (GET /v1/members): leads assigned to them. "me": the key's own user. "unassigned": nobody's.
search
query · string
Matches name, email or phone (any format).
since
query · string
ISO timestamp: only leads created at or after it.
limit
query · number
Default 50, max 200.
offset
query · number
Skip this many leads; pass next_offset from the previous page.
The lead with every column, its raw_payload, the flattened inquiry, address, city, state, zip, custom_fields, tags and stage, plus its 50 most recent timeline events.
Needs workspace_id plus at least one of full_name, email or phone. Besides the lead's columns you can set inquiry, address, city, state, zip, custom_fields and tags. The lead and its tags are saved together, so automations that filter on tags see them; each tag fires the lead.tag_added automation trigger. A lead with the same phone (last 10 digits) or email already in the sub-account answers 409 with its lead_id and matched_on in details: update that lead instead. A field the API does not know answers 400 (it is never silently dropped). By default the intake doesn't run (no first text or AI opener, follow-ups, team alert or Instant Lead Connect); run_intake: true works it like any new lead from a form and intake in the response says what ran. Either way it is a new lead to the rest of the CRM, as one added by hand is: automations that start on a new lead or a tag run, AI calling campaigns that take new leads pick it up, and the lead.created webhook fires. Returns the lead as GET /v1/leads/{lead_id} shows it.
Parameter
Description
full_name
body · string
Lead name.
email
body · string
Email address.
phone
body · string
10-digit US number or + and a country code; stored as E.164.
Base lead status. To move a lead in the pipeline, send stage_key instead.
One of: new, contacted, qualified, booked, won, lost, spam, partial
stage_key
body · string
Pipeline stage key from GET /v1/stages. A stage also sets the status it stands for.
score
body · number
A number 0-100 that is yours to set, e.g. a counter your automations keep. Nothing writes it for you (AI lead scoring is off).
notes
body · string
Internal notes.
assigned_to
body · string
User id of someone in the sub-account (GET /v1/members). The agency owner only with the owner's own key (the app never offers them to the sub-account's people; a lead already on them may stay). null unassigns. A change is logged on the lead's timeline (Lead assigned / Lead unassigned), as in the app.
ad_name
body · string
Ad the lead came from.
campaign_name
body · string
Campaign the lead came from.
utm_source
body · string
UTM source.
utm_medium
body · string
UTM medium.
utm_campaign
body · string
UTM campaign.
utm_term
body · string
UTM term.
utm_content
body · string
UTM content.
landing_url
body · string
Page the lead converted on.
referrer_url
body · string
Referring page.
attribution_channel
body · string
e.g. meta, google, organic, direct.
gclid
body · string
Google Ads click id. A lead with one is sent back to the sub-account's Google Ads by its click when it books or is won (CRM conversions).
gbraid
body · string
Google Ads app-to-web click id.
wbraid
body · string
Google Ads web-to-app click id.
fbclid
body · string
Facebook click id.
msclkid
body · string
Microsoft Ads click id.
deal_value_cents
body · number
Deal value in cents: on a won job, what the customer paid (the Sales report's Sold, and the revenue sent to Meta).
deal_currency
body · string
3-letter currency code. Default USD.
deal_parts_cents
body · number
Won job: what the parts cost, in cents (Sales report).
deal_tip_cents
body · number
Won job: the tip the technician got, in cents.
deal_sold_by
body · string
Won job: the user id of the technician credited with the sale (GET /v1/members). null = whoever the lead is assigned to.
deal_won_at
body · string
When the job was won (ISO 8601). Set for you when status becomes won; send it to date a sale yourself.
deal_type
body · string
Plans & memberships: what the customer bought, one_time (a job) or plan (a plan or membership that pays again). null = one-time. A deal_plan_cents sent alone makes it a plan; one_time clears the plan.
One of: one_time, plan
deal_plan_cents
body · number
Plan: its price in cents, charged every deal_plan_interval. deal_value_cents is the first payment (the plan price when you leave it out).
deal_plan_interval
body · string
Plan: how often it's charged. Default month.
One of: month, quarter, year
deal_plan_start_date
body · string
Plan: when it starts (YYYY-MM-DD). Default today.
deal_plan_months
body · number
Plan: how many months it runs (1-600). null = no end date: the business's default length counts (12 months unless changed in Settings > Features). Leads return deal_monthly_cents and deal_expected_total_cents (first payment + the plan price for the rest of its length).
inquiry
body · string
What the lead asked about: the Inquiry column in the CRM (max 500). Without it the CRM shows the form or ad offer, then General inquiry.
address
body · string
Street address.
city
body · string
City.
state
body · string
State or region. A US state, Canadian province or Australian state is stored as its code ("Texas" -> "TX"), a Mexican state by name, like every other intake; the list follows the lead's country (its phone number, else the sub-account's country). Anything else is kept as sent.
zip
body · string
ZIP or postal code.
custom_fields
body · object
Custom field values keyed by field_key (GET /v1/custom-fields); a field's label also works. Values are checked against the field type: number/money/rating numbers, boolean true/false, date YYYY-MM-DD, datetime ISO 8601, select one of its options, multiselect a list of options. null or "" clears a value; fields you leave out keep their value.
tags
body · array
Tag names. New names are created in the sub-account (matched ignoring case). Max 50.
run_intake
body · boolean
Default false. true = work the lead like a new lead from a form: first text or AI opener, follow-ups, team alert, Instant Lead Connect.
Send only what changes; null or "" clears a value. custom_fields merges: values you leave out are kept. tags REPLACES all of the lead's tags; add_tags and remove_tags change only those (applied in that order: tags, add_tags, remove_tags). A body with only tag changes is fine. stage_key moves the lead in the pipeline and sets the status that stage stands for. A field the API does not know answers 400. Returns the updated lead.
Parameter
Description
lead_id
path · string · required
Lead id.
full_name
body · string
Lead name.
email
body · string
Email address.
phone
body · string
10-digit US number or + and a country code; stored as E.164.
Base lead status. To move a lead in the pipeline, send stage_key instead.
One of: new, contacted, qualified, booked, won, lost, spam, partial
stage_key
body · string
Pipeline stage key from GET /v1/stages. A stage also sets the status it stands for.
score
body · number
A number 0-100 that is yours to set, e.g. a counter your automations keep. Nothing writes it for you (AI lead scoring is off).
notes
body · string
Internal notes.
assigned_to
body · string
User id of someone in the sub-account (GET /v1/members). The agency owner only with the owner's own key (the app never offers them to the sub-account's people; a lead already on them may stay). null unassigns. A change is logged on the lead's timeline (Lead assigned / Lead unassigned), as in the app.
ad_name
body · string
Ad the lead came from.
campaign_name
body · string
Campaign the lead came from.
utm_source
body · string
UTM source.
utm_medium
body · string
UTM medium.
utm_campaign
body · string
UTM campaign.
utm_term
body · string
UTM term.
utm_content
body · string
UTM content.
landing_url
body · string
Page the lead converted on.
referrer_url
body · string
Referring page.
attribution_channel
body · string
e.g. meta, google, organic, direct.
gclid
body · string
Google Ads click id. A lead with one is sent back to the sub-account's Google Ads by its click when it books or is won (CRM conversions).
gbraid
body · string
Google Ads app-to-web click id.
wbraid
body · string
Google Ads web-to-app click id.
fbclid
body · string
Facebook click id.
msclkid
body · string
Microsoft Ads click id.
deal_value_cents
body · number
Deal value in cents: on a won job, what the customer paid (the Sales report's Sold, and the revenue sent to Meta).
deal_currency
body · string
3-letter currency code. Default USD.
deal_parts_cents
body · number
Won job: what the parts cost, in cents (Sales report).
deal_tip_cents
body · number
Won job: the tip the technician got, in cents.
deal_sold_by
body · string
Won job: the user id of the technician credited with the sale (GET /v1/members). null = whoever the lead is assigned to.
deal_won_at
body · string
When the job was won (ISO 8601). Set for you when status becomes won; send it to date a sale yourself.
deal_type
body · string
Plans & memberships: what the customer bought, one_time (a job) or plan (a plan or membership that pays again). null = one-time. A deal_plan_cents sent alone makes it a plan; one_time clears the plan.
One of: one_time, plan
deal_plan_cents
body · number
Plan: its price in cents, charged every deal_plan_interval. deal_value_cents is the first payment (the plan price when you leave it out).
deal_plan_interval
body · string
Plan: how often it's charged. Default month.
One of: month, quarter, year
deal_plan_start_date
body · string
Plan: when it starts (YYYY-MM-DD). Default today.
deal_plan_months
body · number
Plan: how many months it runs (1-600). null = no end date: the business's default length counts (12 months unless changed in Settings > Features). Leads return deal_monthly_cents and deal_expected_total_cents (first payment + the plan price for the rest of its length).
inquiry
body · string
What the lead asked about: the Inquiry column in the CRM (max 500). Without it the CRM shows the form or ad offer, then General inquiry.
address
body · string
Street address.
city
body · string
City.
state
body · string
State or region. A US state, Canadian province or Australian state is stored as its code ("Texas" -> "TX"), a Mexican state by name, like every other intake; the list follows the lead's country (its phone number, else the sub-account's country). Anything else is kept as sent.
zip
body · string
ZIP or postal code.
custom_fields
body · object
Custom field values keyed by field_key (GET /v1/custom-fields); a field's label also works. Values are checked against the field type: number/money/rating numbers, boolean true/false, date YYYY-MM-DD, datetime ISO 8601, select one of its options, multiselect a list of options. null or "" clears a value; fields you leave out keep their value.
tags
body · array
REPLACES all of the lead's tags ([] removes them all). To change only some, use add_tags / remove_tags.
add_tags
body · array
Tag names to add; the lead's other tags stay. New names are created.
With delete_appointments=true its appointments go first, each the way the calendar deletes one: the synced Google / Outlook event, the customer's invite (cancelled if it was still on), its reminder texts, then the appointment; if one can't be deleted the lead is kept and the answer says how many went. Without it the appointments stay on the calendar with no lead, as before.
Parameter
Description
lead_id
path · string · required
Lead id.
delete_appointments
query · boolean
Also delete the lead's appointments (the app's "Also delete their appointments").
mentions tags teammates like @Name in the app's note box: each one on the sub-account's team who can see the lead gets an email and a push with the note and a link to the conversation (replies go to you); the answer lists who was told and who was skipped and why (not_on_team, cant_see_lead).
Parameter
Description
lead_id
path · string · required
Lead id.
body
body · string · required
Note text.
actor_label
body · string
Who the note is from.
mentions
body · array
Up to 20 user ids to tag (GET /v1/members).
Request
cURL
curl -X POST "https://api.ottopros.com/v1/leads/LEAD_ID/notes" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"body": "@Sam can you call her back after 5?",
"mentions": [
"uuid"
]
}'
JavaScript
const res = await fetch("https://api.ottopros.com/v1/leads/LEAD_ID/notes", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
body: "@Sam can you call her back after 5?",
mentions: ["uuid"],
}),
});
const { success, data, error } = await res.json();
Python
import os
import uuid
import requests
res = requests.post(
"https://api.ottopros.com/v1/leads/LEAD_ID/notes",
headers={
"Authorization": f"Bearer {os.environ['API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"body": "@Sam can you call her back after 5?",
"mentions": ["uuid"],
},
)
print(res.json())
Response 201
JSON
{
"success": true,
"data": {
"event": {
"id": "uuid",
"event_type": "note",
"body": "@Sam can you call her back after 5?"
},
"mentions": {
"tagged": [
{
"user_id": "uuid",
"name": "Sam Tech"
}
],
"skipped": []
}
},
"error": null
}
Every tag in the sub-account and how many leads carry it. A tag is created automatically the first time you send its name in a lead's tags or add_tags.
Sends from the sub-account's own number / verified sending domain and logs the message on the lead timeline. Email requires a subject. Address the message with lead_id, or with a raw to (E.164 phone for SMS, email address for email) plus workspace_id — CRM matches an existing contact or creates one. Every send counts against the daily unique-contact safety limit (300 contacts per UTC day by default); replies to contacts already messaged today are free of the cap. Over the cap the call answers 429. Each message is billed at the platform rate and counts against the key's monthly credit budget, if it has one (402 when the budget is used up); a text through one of the sub-account's iMessage Macs is free. The message is sent as the key's user, as from the Inbox: the conversation names them, the Activity Log records them, the numbers and Macs they may text from apply, and an archived conversation comes back to the Inbox.
With send_at the message is scheduled instead, exactly like the Inbox's "Schedule message": the call answers 201 with the scheduled message, and at that time it is sent from the lead's usual number or sender as the key's user, with the same opt-out, credit and limit checks as a send now (a refusal then marks it failed with the reason). A contact who opted out, or has no phone or email for the channel, is refused up front (400). A scheduled message counts against the key's credit budget when it is scheduled. See, change, cancel or send it early with /v1/scheduled-messages.
Parameter
Description
lead_id
body · string
Lead to message. Omit when using to.
to
body · string
Raw destination: E.164 phone for sms, email address for email. Requires workspace_id.
channel
body · string · required
sms or email.
One of: sms, email
body
body · string · required
Message text.
subject
body · string
Required for email.
name
body · string
Contact name used when to creates a new lead.
media_urls
body · array
Up to 10 MMS/attachment URLs.
actor_label
body · string
Sender label shown in the timeline.
send_at
body · string
Schedule instead of sending now: ISO 8601 with a time zone (Z or an offset), e.g. 2026-10-20T09:00:00-05:00. In the future and at most 365 days ahead. Answers 201 with scheduled_message.
send_as
body · string
Texts, with an iMessage Mac connected (Beta): imessage sends a blue iMessage from one of the sub-account's iPhone numbers, sms from its business number, auto (default) lets the routing choose. The answer's transport says how it went (imessage, or mac_sms for the iPhone's own SMS).
One of: auto, imessage, sms
imessage_line_id
body · string
Texts: which Mac (iPhone number) sends it (GET /v1/imessage/lines).
audio_message
body · boolean
Texts: the one media_urls file is a voice message. Through a Mac running Advanced mode it arrives as a real iMessage audio message; anywhere else as an audio attachment. Not with send_at.
Request
cURL
curl -X POST "https://api.ottopros.com/v1/messages" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"lead_id": "uuid",
"channel": "sms",
"body": "Hi Jane, are you still looking for a quote?"
}'
JavaScript
const res = await fetch("https://api.ottopros.com/v1/messages", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
lead_id: "uuid",
channel: "sms",
body: "Hi Jane, are you still looking for a quote?",
}),
});
const { success, data, error } = await res.json();
Python
import os
import uuid
import requests
res = requests.post(
"https://api.ottopros.com/v1/messages",
headers={
"Authorization": f"Bearer {os.environ['API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"lead_id": "uuid",
"channel": "sms",
"body": "Hi Jane, are you still looking for a quote?",
},
)
print(res.json())
Messages waiting to be sent later, scheduled in the Inbox or with POST /v1/messages and send_at. By default the upcoming ones (pending, sending, failed), soonest first, like the dashed bubbles at the end of a conversation; status = sent, cancelled or all lists history, newest first. A failed message carries last_error. Viewers limited to their own leads only see those leads' messages.
Parameter
Description
lead_id
query · string
Only this lead's messages.
status
query · string
Default upcoming (pending, sending, failed).
One of: upcoming, pending, sending, failed, sent, cancelled, all
Like the Inbox's Edit, Cancel and Undo. Send any of body, subject (emails), scheduled_at and media_urls (texts) to change a pending or failed message: it goes back in the queue (status pending). status: "cancelled" (on its own) stops it; status: "pending" brings a cancelled one back (send a new scheduled_at when its time has passed). 409 when it is sending or already sent. Owners and admins only.
Parameter
Description
scheduled_message_id
path · string · required
Scheduled message id.
body
body · string
The new text.
subject
body · string
The new subject (emails only).
scheduled_at
body · string
ISO 8601 with a time zone, in the future and at most 365 days ahead.
media_urls
body · array
Picture URLs for a text, max 10 (replaces the list).
status
body · string
cancelled to cancel, pending to restore.
One of: pending, cancelled
Request
cURL
curl -X PATCH "https://api.ottopros.com/v1/scheduled-messages/SCHEDULED_MESSAGE_ID" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"scheduled_at": "2026-10-21T09:00:00-05:00",
"body": "Hi Jane, following up on your quote. Any questions?"
}'
JavaScript
const res = await fetch("https://api.ottopros.com/v1/scheduled-messages/SCHEDULED_MESSAGE_ID", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
scheduled_at: "2026-10-21T09:00:00-05:00",
body: "Hi Jane, following up on your quote. Any questions?",
}),
});
const { success, data, error } = await res.json();
Python
import os
import uuid
import requests
res = requests.patch(
"https://api.ottopros.com/v1/scheduled-messages/SCHEDULED_MESSAGE_ID",
headers={
"Authorization": f"Bearer {os.environ['API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"scheduled_at": "2026-10-21T09:00:00-05:00",
"body": "Hi Jane, following up on your quote. Any questions?",
},
)
print(res.json())
Response 200
JSON
{
"success": true,
"data": {
"scheduled_message": {
"id": "uuid",
"channel": "sms",
"body": "Hi Jane, following up on your quote. Any questions?",
"scheduled_at": "2026-10-21T14:00:00+00:00",
"status": "pending"
},
"changed": true
},
"error": null
}
The Inbox's "Send now": a pending or failed message goes out at once, as the teammate who scheduled it, with the usual opt-out, credit and limit checks, and is billed like any text or email. 200 = sent; 202 = a sending hiccup, it tries again by itself in a couple of minutes; 400 = refused, with the reason (the message is marked failed); 409 = cancelled, already sending or sent. Refused when the key's credit budget is used up. Owners and admins only.
Every SMS and email on the sub-account's CRM numbers and inboxes, newest first. For polling, pass cursor (or since) — results then come oldest-first and next_cursor walks forward with no duplicates and no missed messages. Poll no more than once every 10 seconds, or subscribe to the message.received webhook instead. A text that went through one of the sub-account's iMessage Macs carries transport (imessage, or mac_sms for the iPhone's own green text) and imessage { line_id, from, service: imessage | sms | rcs, delivered_at, read_at }; a tapback carries reaction { by: them | you, type, emoji, reacts_to: the message it hangs on, removed }.
Parameter
Description
lead_id
query · string
Only messages with this contact.
channel
query · string
sms or email.
One of: sms, email
direction
query · string
inbound or outbound.
One of: inbound, outbound
since
query · string
ISO-8601 timestamp; returns messages created after it, oldest-first.
Returns the daily unique-contact cap (default 300 per UTC day), how many contacts have been used, what's left, segment usage and the reset time. The same values ride on every messaging call as X-Contacts-Limit / -Used / -Remaining / -Reset headers.
Every Mac connected to the sub-account for iMessage, the default first: its iPhone number, whose Mac it is, whether it's online, what the Mac reports about itself (health: Messages signed in, Full Disk Access, awake, lid closed allowed, iCloud still syncing, the number missing from or switched off in Messages), whether Advanced mode runs on it (advanced_mode: real audio messages and reactions), its settings (scope, create_leads, new_conversations, fallback, offline_minutes, ai_replies), who can text from it (access, allowed_user_ids, and can_use for you), its limits (new conversations a day and an hour, tries and length before someone first replies) and today's usage (new conversations today and this hour, messages waiting, every text it sent today, and how many other accounts share that iPhone's limit). has_number says whether the sub-account has a business number to fall back on; without one every text goes through a Mac. Any member. Connecting and disconnecting a Mac happen in the app.
Send only what changes. The sub-account's owners and admins change any Mac; everyone else only their own; only owners and admins choose the default (is_default: true moves it from the old one). access: everyone, owner (only the person whose Mac it is) or selected (allowed_user_ids); owners, admins and the Mac's owner can always text from it, and AI replies and automations aren't limited.
Parameter
Description
line_id
path · string · required
The Mac (GET /v1/imessage/lines).
label
body · string
A name for it (max 80), or null.
is_default
body · boolean
true makes it the default Mac.
access
body · string
Who can text from it by hand.
One of: everyone, owner, selected
allowed_user_ids
body · array
With access selected: the team members who can.
scope
body · string
crm: only conversations with people already in the CRM sync; all: every one-to-one conversation.
One of: crm, all
create_leads
body · boolean
With scope all: someone new who texts in becomes a lead.
new_conversations
body · string
How a first text to someone goes.
One of: sms, imessage
fallback
body · string
When they aren't on iMessage or the Mac is offline: the business number, RCS or SMS from the iPhone through the Mac, the iPhone and then the business number (mac_then_number, the default), or nothing.
One of: number, mac, mac_then_number, none
offline_minutes
body · number
How long a message waits for an offline Mac before the fallback, 2-240.
Puts a tapback (❤️ 👍 👎 😂 ‼️ ❓) on a text that went through one of the sub-account's Macs, like the Inbox's reaction picker; remove: true takes yours back. Only a Mac running Advanced mode can (advanced_mode on GET /v1/imessage/lines): otherwise 409 advanced_off. The reaction is queued (202) and shows on the message (its reaction, by you) once the Mac has sent it; if it can't, a note says why on the conversation. Anyone who can see the lead and text from that number. Free, like every text through a Mac.
Parameter
Description
message_id
path · string · required
The text to react to (an id from GET /v1/messages or the lead's conversation).
reaction
body · string · required
love, like, dislike, laugh, emphasize or question (or the emoji).
One of: love, like, dislike, laugh, emphasize, question
Every setting POST / PATCH /v1/calendars takes, read the way the booking page reads it: hours, length, buffers, hosts' mode, texts, pricing (with each option's and add-on's id, used by availability and bookings), design, duration_days (full-day jobs), schedule_group (shared schedule), fields and questions (the booking form), image_url, the payment settings, a summary (price_from_cents, price_to_cents, length_label such as "4-6 hr", has_options, takes_payment) and booking_path (/c/<slug>).
The times the calendar's booking page offers, worked out the same way: weekly hours and days off, the job length, buffers, capacity (slots_per_window jobs at one moment), calendars sharing its schedule, max per day, minimum notice, the booking window (max_days_ahead, up to a year) and the hosts' own calendars. A calendar with options times each one differently, so send option_id (400 lists the options otherwise) and any addon_ids; the answer carries a quote (option, add-ons, length, total, deposit, balance). Full-day calendars also return slot_ends (when each start's job is done). Always call this before creating a booking.
Parameter
Description
calendar_id
path · string · required
Calendar id.
from
query · string
A date (2026-11-03) or an ISO time; defaults to today.
days
query · number
1-42, default 7.
option_id
query · string
The option picked (its id in GET /v1/calendars pricing.options). Required on a calendar with options.
addon_ids
query · string
Add-on ids, comma-separated: they add their time to the job.
Soonest first. Each appointment has the same fields as everywhere else in the API: id, lead_id, calendar_id, appointment_number (the sub-account's #1001 and up, as the calendar shows it), title, starts_at, ends_at, timezone, lead_timezone, location, notes, meeting_type, meeting_location, meeting_url, host_user_id, status, source, notify_lead, is_arrival_window (booked as an arrival window: starts_at to ends_at is the window), service_details (on a priced calendar: the service, option, add-ons, length, total_cents, deposit_cents, balance_cents and currency; null otherwise), created_at and updated_at.
Books like the app: rejects a second overlapping appointment for the same lead; calendar_id must be one of the sub-account's calendars (404 otherwise); ends_at must be after starts_at and at most 24 hours later. With a calendar, the slot's capacity is checked, calendars sharing its schedule included (409 with code slot_full; pick a time from GET /v1/calendars/{calendar_id}/availability, or send force: true) and the host is picked by the calendar's round robin. On a priced calendar, option_id and addon_ids set the job's length and price: the booking's notes start with the pick and its service_details carry the option, add-ons, total, deposit and balance; the lead's deal value is filled when it has none (the response adds a quote; a warning says when a calendar with options was booked without one). Bookings made through the API never take the deposit: to collect it, send the customer the booking link. A full-day calendar's job starts at opening time and ends at closing time on its last working day (400 not_a_start_time otherwise, unless ends_at is sent). By default the lead gets the confirmation and reminder texts and the calendar invite (notify_lead: false to skip them). Fires the appointment.booked outbound webhooks.
Parameter
Description
starts_at
body · string · required
ISO 8601 start time.
ends_at
body · string
ISO 8601 end time (instead of duration_minutes; at most 24 h after starts_at, 31 days on a full-day calendar).
lead_id
body · string
Lead to book.
calendar_id
body · string
One of the sub-account's calendars.
option_id
body · string
The option booked (GET /v1/calendars pricing.options id), e.g. the vehicle size.
addon_ids
body · array
Add-ons booked (pricing.addons ids).
duration_minutes
body · number
5-1440. Default: the option's length with its add-ons, else the calendar's, else 30.
timezone
body · string
IANA timezone.
location
body · string
Meeting location.
notes
body · string
Internal notes.
notify_lead
body · boolean
Default true: the lead gets the confirmation email with its calendar invite plus the confirmation and reminder texts. false books quietly, and later updates or cancels stay quiet too; the host still gets the booking alert.
force
body · boolean
Skip the calendar's capacity check (the database still never double-books a person or a full calendar).
Re-times the reminder texts, updates the calendar mirror and the lead's invite, and fires the appointment.rescheduled outbound webhooks when the time changed. The appointment keeps its length; a full-day job runs to closing time on its new last working day. 409 slot_full when the new time is taken.
Change an appointment's outcome, title, notes, location, host, lead notifications or lead
PATCH/v1/bookings/{booking_id}
Read and writeIdempotent
Everything but the time (use reschedule for that). status records the outcome: completed, no_show or cancelled release the lead from Booked and stop its reminder texts; confirmed puts it back on. host_user_id must be someone on the sub-account's team (GET /v1/members). notify_lead: false silences the lead's remaining reminder texts and invite updates; true turns them back on (an upcoming appointment's reminders are queued again). lead_id links an appointment that has no lead yet (typed in by hand) to a lead of the same sub-account; one that already has a lead answers 409. Linking an upcoming scheduled appointment books it for the lead like a new booking: the lead is marked booked, its follow-ups and AI calls stop, and the confirmation and reminder texts and the invite go out (unless notify_lead is false). A past or finished appointment is only linked.
Parameter
Description
booking_id
path · string · required
Booking id.
status
body · string
The appointment's outcome.
One of: confirmed, completed, no_show, cancelled
title
body · string
Max 200.
notes
body · string
Max 2000. null clears them.
location
body · string
Address or place, max 300. null clears it.
host_user_id
body · string
Team member who takes it. null for nobody.
notify_lead
body · boolean
false: the lead gets no more reminder texts or invite updates for this appointment. true: they do again.
lead_id
body · string
Link an appointment with no lead to this lead (same sub-account). Cannot move an appointment from one lead to another.
Each member has user_id, role, email and full_name. Use user_id (or the email) to name a team member in busy blocks. Staff and Technicians, who have no Team page in the app, get names and roles only (no emails, no invitations).
Starts unpublished with the same defaults as a form created in the app. The response includes its public path (/f/<slug>), qualifier_questions, custom_fields, qualification, calendar_routing, service_area and estimate. Questions can ask for photos (field_type file) and put a price on answers (option_prices) for the instant estimate: switched on with estimate, the answers' prices add up to a live total in the form's footer, saved on the lead with its total as the deal value. Qualification routes each lead to Qualified, Nurture or Not eligible: yes/no qualifier_questions (asked first when qualifier_enabled is on) and choice questions with disqualify_options or nurture_options. A service area (fields.address.service_area) only accepts addresses in chosen US states or within a radius: address suggestions stay inside it and an out-of-area visitor sees your message and cannot send the form; switching it on shows and requires the address, like the builder. Design and tracking pixels are edited in the app.
Parameter
Description
name
body · string · required
Form name (max 80).
headline
body · string
Max 160.
subheadline
body · string
Max 300.
primary_color
body · string
#rrggbb.
bullet_points
body · array
Up to 8 short lines.
layout_mode
body · string
The builder's Layout: single_step (one page, the default), multi_step (a step-by-step wizard), conversational (one question at a time, like a chat) or funnel (one big question per screen).
One of: single_step, multi_step, conversational, funnel
calendar_id
body · string
Calendar used by the booking step.
calendar_routing
body · boolean
Pick the calendar from the answers: the sub-account's calendar routing rules (/v1/calendar-routes) choose which calendar's times the form shows once the deciding question is answered; calendar_id is used when no rule fits.
booking_enabled
body · boolean
Show the booking step.
fields
body · object
Contact fields: {"email":{"required":false},"address":{"enabled":false}}. Keys: first_name, last_name, phone, email, address, state (a State / Province pick list), notes. Phone or email must stay on. address also takes service_area (merged): {"enabled":true,"mode":"states","states":["TX","OK"],"message":"Sorry, we only serve Texas and Oklahoma."}, or mode "radius" with "center":{"lat":32.7767,"lng":-96.797,"label":"Dallas, TX"} and "radius_miles" (1-500, default 25). A blank message shows "Sorry, we don't service this area yet."; null or enabled:false switches it off.
is_published
body · boolean
Default false.
qualifier_enabled
body · boolean
Ask the qualifier_questions first.
qualifier_questions
body · array
Up to 10, replaces the list: [{ text (max 200), disqualify_on: "yes" | "no" (default "no"), outcome: "not_eligible" | "nurture" (default "not_eligible") }].
questions
body · array
Custom questions, up to 30, replaces the list: [{ key?, label (max 160), field_type: text | textarea | number | money | phone | email | url | select | multiselect | boolean | date | datetime | rating | file (photos or PDFs, up to 6, shown on the lead), options (select / multiselect: 2-40), option_prices? (select / multiselect: cents per answer for the instant estimate, e.g. {"SUV": 8000}; left out keeps the saved prices, null removes them), disqualify_options? or nurture_options? (choice types; boolean answers "yes" / "no"; never both), placement?: "qualify" | "details" (qualify = choice types only), option_style?: dropdown | buttons | cards | auto, no_first? (boolean: show No before Yes), required?, enabled?, save_to_crm? (never for file), placeholder?, helper_text? }].
The instant price estimate, merged: { enabled, label (default "Your estimate"), base_cents (added before any answer), note (e.g. "Final price after we see the job"), range_percent (0-50: shown as a range that far either side) }. null switches it off.
Request
cURL
curl -X POST "https://api.ottopros.com/v1/smart-forms" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Roof quote",
"qualifier_enabled": true,
"qualifier_questions": [
{
"text": "Do you own the home?",
"disqualify_on": "no",
"outcome": "not_eligible"
}
],
"questions": [
{
"label": "When do you want to start?",
"field_type": "select",
"options": [
"This month",
"In 1-3 months",
"Just researching"
],
"nurture_options": [
"Just researching"
],
"placement": "qualify"
},
{
"label": "Vehicle size",
"field_type": "select",
"options": [
"Car",
"SUV",
"Truck"
],
"option_prices": {
"Car": 31500,
"SUV": 38500,
"Truck": 45000
}
},
{
"label": "Photos of the damage",
"field_type": "file"
}
],
"qualification": {
"save_not_eligible": true
},
"estimate": {
"enabled": true,
"note": "Final price after we see the job",
"range_percent": 10
}
}'
JavaScript
const res = await fetch("https://api.ottopros.com/v1/smart-forms", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
name: "Roof quote",
qualifier_enabled: true,
qualifier_questions: [
{
text: "Do you own the home?",
disqualify_on: "no",
outcome: "not_eligible",
},
],
questions: [
{
label: "When do you want to start?",
field_type: "select",
options: ["This month", "In 1-3 months", "Just researching"],
nurture_options: ["Just researching"],
placement: "qualify",
},
{
label: "Vehicle size",
field_type: "select",
options: ["Car", "SUV", "Truck"],
option_prices: {
Car: 31500,
SUV: 38500,
Truck: 45000,
},
},
{
label: "Photos of the damage",
field_type: "file",
},
],
qualification: {
save_not_eligible: true,
},
estimate: {
enabled: true,
note: "Final price after we see the job",
range_percent: 10,
},
}),
});
const { success, data, error } = await res.json();
Python
import os
import uuid
import requests
res = requests.post(
"https://api.ottopros.com/v1/smart-forms",
headers={
"Authorization": f"Bearer {os.environ['API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"name": "Roof quote",
"qualifier_enabled": True,
"qualifier_questions": [
{
"text": "Do you own the home?",
"disqualify_on": "no",
"outcome": "not_eligible",
},
],
"questions": [
{
"label": "When do you want to start?",
"field_type": "select",
"options": ["This month", "In 1-3 months", "Just researching"],
"nurture_options": ["Just researching"],
"placement": "qualify",
},
{
"label": "Vehicle size",
"field_type": "select",
"options": ["Car", "SUV", "Truck"],
"option_prices": {
"Car": 31500,
"SUV": 38500,
"Truck": 45000,
},
},
{
"label": "Photos of the damage",
"field_type": "file",
},
],
"qualification": {
"save_not_eligible": True,
},
"estimate": {
"enabled": True,
"note": "Final price after we see the job",
"range_percent": 10,
},
},
)
print(res.json())
Takes the same fields as create; send only what changes. questions and qualifier_questions replace their lists; qualification, estimate, fields and fields.address.service_area are merged.
Parameter
Description
form_id
path · string · required
Form id.
is_published
body · boolean
Publish or unpublish.
layout_mode
body · string
single_step, multi_step, conversational or funnel (see create).
One of: single_step, multi_step, conversational, funnel
qualifier_enabled
body · boolean
Ask the qualifier_questions first.
qualifier_questions
body · array
Replaces the list (see create).
questions
body · array
Replaces the list (see create).
qualification
body · object
Merged (see create).
estimate
body · object
Merged (see create).
calendar_routing
body · boolean
Pick the calendar from the answers (see create).
fields
body · object
Merged, including address.service_area (see create).
Can send real texts and emails. Confirm the lead list before calling. Leads are queued and start within the sub-account's daily contact limit. A lead already waiting in this automation's queue is not queued again (already_queued). ignore_filters defaults to false: a lead that fails the automation's only_if rules is skipped when the queue reaches it (the app's Enroll dialog defaults to true).
Parameter
Description
automation_id
path · string · required
Automation id.
lead_ids
body · array · required
Lead ids (max 5000).
ignore_filters
body · boolean
Default false: leads that fail the automation's only_if rules are skipped. true = enroll them anyway.
Every trigger, step, filter and setting the builder accepts
GET/v1/workspace-automations/reference
Read only
Read this before building: trigger types and their filters, step actions and their fields, entry-rule fields and operators (with every lead source), settings, message variables, and what this sub-account has for a definition to point at: stages, team, custom fields, phone numbers, review funnel, Facebook pages, Smart Forms, form names (for form_name rules), calendars and email senders.
Saved exactly as the Automations page saves it, so it opens and edits in the app. Saved OFF unless enabled is true; once on, its texts and emails go to real leads through the normal quiet hours, opt-out and daily limits. Steps can send lead data out (webhooks, alerts), so this needs an admin-scoped key. Everything it points at (stages, team members, phone numbers, review pages, Facebook pages, Smart Forms, calendars, email senders) must be in the same sub-account; GET /v1/workspace-automations/reference lists them. Any step can take a label (its name on the step card). An inbound_webhook automation comes back with its private inbound_url: POST JSON with a phone or email to start it (it must be on), and every field sent can be used in its messages as {field}.
Parameter
Description
name
body · string · required
Up to 80 characters.
description
body · string
Optional note.
trigger
body · object · required
When it starts: {"type":"new_lead"}, {"type":"stage_changed","to_stages":["booked"]}, {"type":"tag_added","tags":["hot"]}, {"type":"smart_form_submitted","form_ids":["Free quote"]}, {"type":"appointment_booked","calendar_ids":["Estimate visit"]}, {"type":"inbound_webhook"}... Ids or names. See GET /v1/workspace-automations/reference.
only_if
body · array
Entry rules, all must hold: [{"field":"tags","op":"has_none","value":["customer"]}].
steps
body · array · required
In order: [{"action":"send_text","message":"Hi {first_name}"},{"action":"wait","days":1},{"action":"send_email","subject":"Your quote","message":"..","from_sender_id":"<email sender id, address or name>"},{"action":"if","conditions":[..],"then":[..],"else":[..]}]. A send_text step takes send_as (auto, imessage or sms) when the sub-account has an iMessage Mac.
One automation as {trigger, only_if, steps, settings}
GET/v1/workspace-automations/{automation_id}
Read only
The same shape create and update take (step names included), with a ref on every step so an update can keep steps unchanged ({"keep":"<ref>"}). Webhook header values are hidden. An inbound_webhook automation includes its inbound_url; viewers see only its host, like webhook step links.
Send only what changes. steps replaces all steps: keep unchanged ones with {"keep":"<ref>"} from GET. settings changes only the keys sent. enabled turns it on or off.
The sub-account's invoices, newest first. effective_status adds overdue (sent and past due), as the app shows it. kind is invoice, deposit (it lists the whole job but asks only for deposit_cents now; deposit_percent when it was a percent) or balance (made by Bill the balance: deposit_invoice_id is the deposit it follows and deposit_applied_cents comes off the job total). total_cents is always what this invoice asks for. Owners and admins only. Payment processor details are never returned.
Adds the customer's address, notes, terms, subtotal, discount and tax, the PDF link, line items, the event history (created, sent, viewed, paid) and public_path, the customer's view-and-pay page on the sub-account's domain (none for drafts).
The sub-account's estimates, newest first, as the Estimates tab lists them: number, title, the customer, status and effective_status (expired: sent and past its last day), when it was sent, viewed, approved (and by whom) or declined (and why), the invoice it became, its Good / Better / Best options with their totals, and total_cents (the option the customer picked, else the recommended one). Technicians and Staff limited to their own leads see the estimates for leads they can see and ones they made without a lead, as in the app.
Parameter
Description
status
query · string
Filter.
One of: draft, sent, approved, declined, expired, converted
Adds the customer's address, intro, terms, tax rate and the customer's approval note, every option (name, description, photo, recommended, subtotal, tax and total) with its lines (name, details, photo, quantity, unit price, taxable), the history (created, sent, viewed, approved, declined) and public_path, the customer's page on the sub-account's domain (none for drafts).
The saved items estimates and invoices pick their lines from: name, details, category, unit price, taxable, photo, and how often it's used (most used first).
Saved as a draft exactly as the estimate editor saves one: the sub-account's next number, its default terms, days valid and tax rate, the lead's name, email, phone and address filled in. Send items for one option, or options (2-4, e.g. Good / Better / Best) each with its items; every option's subtotal, tax and total are worked out as the editor does (each line rounded, tax on taxable lines). Answers with the estimate as GET /v1/estimates/{estimate_id} shows it. Send it with POST /v1/estimates/{estimate_id}/send. Technicians only while the sub-account lets them make estimates, and only for their own leads.
Parameter
Description
lead_id
body · string
Who it is for (fills in the customer; needed to send it). Or customer_name.
title
body · string
Max 200, e.g. Whole-house duct cleaning.
intro
body · string
A note to the customer at the top (max 2000).
items
body · array
One option's lines: [{ description (the line's name, max 300), details? (max 2000), image_url? (https), quantity? (default 1), unit_price_cents, taxable? (default true) }].
options
body · array
Instead of items, up to 4 choices: [{ name, description?, image_url?, recommended?, items: [...] }]. One is recommended (the first marked, else the first).
tax_rate
body · number
Percent, 0-30. Default: the sub-account's.
valid_days
body · number
Days it is valid (1-365). Default: the sub-account's. Or expires_at.
expires_at
body · string
Last day, YYYY-MM-DD, or null for no end.
terms
body · string
Max 4000. Default: the sub-account's estimate terms.
currency
body · string
3 letters, default usd.
customer_name
body · string
Without a lead, or to change what the lead fills in.
Send only what changes. options (or items) replace every option and line, as the editor saves; a new tax_rate re-totals the options. An approved estimate or one already made into an invoice answers 409: make a new one.
Like the editor's Send: a text and/or an email to the estimate's lead with the link to review and approve it (on the sub-account's own domain when it has one), in the editor's own words unless you send message (it must include {link}). Sent as the key's person, with the usual opt-out, credit and limit checks; each is billed like any text or email. A draft (or a declined or expired one) becomes sent. sent lists each channel and why one didn't go.
Convert to invoice: a draft invoice from the option the customer picked (else the recommended one, or option_id), with its lines, the estimate's tax rate and the sub-account's due days, terms and notes; the estimate becomes converted. Owners and admins (invoices are theirs). Send the invoice from the app.
Tools → Review funnel: each review page, which one is the default, its rating threshold, where happy customers are sent, and its public_path (/r/<code> on the sub-account's domain).
Makes (or returns) the lead's link on a review page, like Copy review link on the lead. Sends nothing; share it however you like. Owners and admins only.
Send only what changes: name, timezone, industry, logo_url, brand_id, archived, notify_on_appointments, enabled_features, hidden_features. logo_url is the sub-account's Client logo, the same image as Settings → Client logo & app icon: changing either changes both (null removes it). enabled_features is Settings > Features: tools only some businesses use, off until turned on (today: sales, the Sales page and the parts / tip / technician on won jobs; plans, Plans & memberships on won jobs); owners and admins. hidden_features is what the agency hides from the sub-account's own people (client admins, Staff and Technicians lose those pages, and their API keys get 403 feature_off on those routes): leads, messages, appointments, calendars, smart_forms, media, campaigns, calls, ai_voice, automations, landing_pages, invoices, sales, activity, team, ad_insights, tools, support, agent. archived, brand_id and hidden_features are the agency's: the owner or an agency admin. Both take { key: true | false } and change only the keys sent.
Parameter
Description
logo_url
body · string
Client logo URL, or null to remove it.
enabled_features
body · object
Settings > Features, e.g. { "sales": true }.
hidden_features
body · object
Hidden from the client's people, e.g. { "invoices": true, "team": false }. Owner or agency admin.
Configure outreach (auto-greet, AI replies, sending identity)
POST/v1/workspaces/{workspace_id}/outreach
Read and writeIdempotent
Raw column names, for anyone who can manage the sub-account; PATCH on the same path does the same. Prefer PATCH /v1/ai-texting and /v1/nurture-sequence, which take friendly names and check every value. Accepted fields: auto_greet_new_leads, first_message_template, sms_template, greet_delay_minutes_smart_form, greet_delay_minutes_default, greet_window_mode / _start / _end, followup_window_mode / _start / _end, ai_enabled, ai_system_prompt, ai_business_context, ai_agent_name, ai_booking_link, ai_max_auto_replies, reply_delay_minutes, respect_business_hours, quiet_hours_enabled / _start / _end, handoff_on_unknown, handoff_pause_ai, handoff_resume_days, ai_can_cancel_appointments, ai_cancel_retention_enabled, ai_cancel_retention_note, ai_auto_resume_minutes, nurture_enabled, nurture_steps, email_enabled, email_from_address, email_from_name, email_subject, email_template, sms_enabled, missed_call_text_enabled, missed_call_text_body, reminder_24h_enabled / _template, reminder_1h_enabled / _template, reminder_5m_enabled / _template (the 5-minute reminder, off by default), customer_confirmation_enabled / _template, appointment_email_enabled, appointment_email_language (en | es). Unknown fields are ignored; text is capped at 20,000 characters.
Exactly what its Ad Insights page shows: spend, leads, cost per lead, impressions and clicks for the Meta ad accounts attached to it (one, or all of them added up with each account's share in accounts, and an error for one that couldn't be read), each read with whichever connected Facebook profile can; per campaign and per ad, only the campaigns and ads the agency picked for this sub-account; ads left out (ads_hidden) when the agency hides them from the client. Amounts are added up in each account's own currency (accounts_meta). 403 ad_insights_off when Ad Insights is off for it.
Parameter
Description
ad_account_id
query · string
"all" (default) or one attached account, act_123.
date_preset
query · string
Default last_30d.
One of: today, yesterday, last_7d, last_14d, last_30d, last_90d, this_month, last_month, maximum
The sub-account's own Google Ads connection (Ad Insights > Google Ads): its ad accounts (customers), the one in use, whether booked / won leads are sent back as conversions and to which conversion actions, and the newest conversions with their status (pending, sent, failed, skipped) and how each lead was matched (gclid, gbraid, wbraid or email / phone). Owners and admins.
One of the Google Ads screens, read live from Google for one of the sub-account's ad accounts: overview (campaigns with spend, clicks, conversions, totals and by day), ad_groups, keywords, ads, search_terms, negatives, campaign_settings (campaign_id), conversion_actions, bidding, recommendations. Nothing is changed. Owners and admins.
Every Business Profile connected to the sub-account (it can have several): the location, rating, review count, whether Google's API answers for it, and its auto-reply, auto-post and photo settings; plus the Google logins connected (email only). Owners and admins.
Each Profile Optimizer check, newest first: the score, what it found, the keywords, its suggestions and the changes made from it (and undone). Owners and admins.
Where the business ranks on Google Maps across a grid around it: the keywords tracked (grid, schedule, next and last scan) and the scans, newest first, each with its summary (points, found, top 3, average rank). Owners and admins.
Every grid point with its rank (null: not in the top 20), the competitors found, and the next steps to rank #1 once they've been written (they are written when the scan is first opened in the app). Owners and admins.
The directories the business is being listed on: each one's status (queued, scanning, listed, mismatch, not_listed, working, needs_you, submitted, live, owner, skipped, failed) with counts, what differs or what's needed from the owner, the listing link, and the latest activity. Passwords and verification codes are never returned. Owners and admins.
The sub-account's Support tickets, newest activity first: subject, category, status (open, answered, resolved), who is answering (the assistant or the team), unread state and rating. The agency team sees every ticket; a client admin every ticket of the sub-account; anyone else their own. 403 feature_off while Support is off for the sub-account.
What this key may do and how much of it is used: access_level (read / write / admin / custom) and scopes, the workspace it is locked to (if any), rate_limit_per_min, credit_budget (limit, used, remaining and reset date; null when the key has no budget) and usage_30d (requests, errors, rate_limited). type is account (made in Settings → API) or sub_account (made in a sub-account's own Settings → API in the client CRM), and endpoints gives the API and MCP addresses for the host you called. A sub-account key can call this.