The Crush It Engine REST API

Verify your key

GET/me

Confirms the API key works and identifies the business it belongs to — including its plan and the products it owns, so you know which actions apply.

→ { "ok": true, "business_id": "…", "business_name": "Tampa Test Plumbing", "plan": "scale", "products": ["ai_voice", "mctb"], "marketing_included": true }

Send a text message

POST/send-text

Texts a customer from your business number. Every send passes the same compliance gate as the platform's own messages — opt-outs and quiet hours are re-checked at the instant of send, and unregistered numbers never send into carrier filtering.

→ { "ok": true, "status": "sent", "to": "+18135551234", "thread_id": "…" }

A blocked send is NOT an error — you get 200 with `status: "suppressed"` and a `reason`: `contact_opted_out`, `quiet_hours`, or `carrier_registration_pending`. Branch on `status`, don't retry.

Sent messages appear in your dashboard inbox thread like any other outbound text.

Open or close a job's team chat

POST/job-chat

Automatic job chats from any field software: open a team chat for a dispatched job with the assigned techs (matched to team logins by email) plus the owner and managers, and a first message with the customer, address and job summary. Calling open again refreshes it; close marks it done and keeps the history. Team messaging comes with AI Voice or Cloud PBX; without either, this returns 403.

→ { "ok": true, "conversation_id": "…", "created": true }

Add a note to a customer

POST/customer-note

Adds a note to a customer's timeline — what was promised, a gate code, anything the team should see. Shows in the dashboard with who wrote it.

→ { "ok": true, "phone": "+18135551234" }

Create or update a contact/lead

POST/contacts

Phone-keyed upsert into your leads. If a lead with that phone number exists, only the fields you send are overwritten; otherwise a new lead is created.

→ { "ok": true, "created": true, "lead": { … } }

Teach the agent a fact

POST/knowledge

Adds a fact to your live agent's knowledge as a coaching note and republishes the agent — the change is live on the very next call, usually within seconds.

→ { "ok": true, "status": "applied_live", "note_id": "…" }

If the live republish can't complete, you get `status: "saved_pending"` — the note is saved and applies on the next Save & publish from the dashboard.

Pause or resume the AI

POST/pause

One-tap pause as an API: while paused, calls ring your real phone — and with Missed-Call Text Back, the ones you miss still get a text.

→ { "ok": true, "paused": true }

Pausing requires a transfer phone (Phone line → Transfer) — paused calls have to ring somewhere. With the Team Phone on, paused calls go to your menu and team instead, so no transfer phone is needed.

Set the answering mode

POST/answering-mode

Switches how your number answers, exactly like the dashboard switch.

→ { "ok": true, "mode": "ai_after_hours" }

Every mode except ai_always uses text-back, so it needs Missed-Call Text Back on the account (403 otherwise). The two scheduled modes also need AI Voice Pro or Scale.

With the Team Phone (Cloud PBX) on, the phone system owns the number and a separate front-desk setting in the dashboard decides who answers — this returns 409 and changes nothing.

Add a trusted number

POST/trusted-numbers

Trusted callers skip the AI and ring you directly, and are never sent text-back messages. 25 numbers max.

→ { "ok": true, "entry": { … } }

Remove a trusted number

DELETE/trusted-numbers

Removes a number from the trusted list (send the phone in the JSON body).

→ { "ok": true, "removed": "+18135551234" }

Suppress a contact (do not text)

POST/suppress

Marks a number as opted out here — use it to sync unsubscribes from your CRM or email platform so no channel texts someone who said stop anywhere.

→ { "ok": true, "suppressed": "+18135551234" }

One-way by design: under FCC revocation rules only the customer texting START restores consent, so there is no unsuppress endpoint.

Turn text-back on or off

POST/text-back

Flips the missed-call rescue engine — for example, off while a vacation auto-responder runs.

→ { "ok": true, "active": false }

Turning it on needs Missed-Call Text Back on the account (403 otherwise). Turning it off always works.

Change appointment reminders

POST/reminder-settings

The reminder text every booked customer gets before their appointment — on by default, no text-back needed. GET the same path to read the current settings.

→ { "ok": true, "updated": ["reminder_hours_before"] }

Create an appointment

POST/appointments

Writes a confirmed appointment in from your booking tool. Callers with an upcoming appointment are automatically spared sales-y rescue texts.

→ { "ok": true, "appointment": { … } }

Appointments created here never emit the appointment_booked webhook — no event loops.

Rate a call

POST/calls/{id}/rate

Rate a call as the owner. Down-ratings flag the call for quality review.

→ { "ok": true, "call_id": "…", "rating": "down" }

Answer or dismiss a question

POST/questions/{id}

Close an open unanswered question. Answering turns your answer into agent knowledge and republishes the live agent — the teach-it loop as an API.

→ { "ok": true, "question_id": "…", "status": "applied_live" }

Take over / hand back a conversation

POST/thread

Toggle who handles one text thread. Taking over (ai_active=false) stops AI replies and cancels queued follow-ups for that customer.

→ { "ok": true, "thread_id": "…", "ai_handling": false }

Set business hours

POST/business-hours

Local hours that drive after-hours answering modes and what the agent tells callers. Republishes the live agent.

→ { "ok": true, "hours": { … }, "agent_republished": true }

Set the transfer number

POST/transfer-number

Where hot calls and pass-through modes ring. Republishes the live agent (the number is baked into its transfer tool).

→ { "ok": true, "transfer_number": "+1813…", "agent_republished": true }

Update text-back settings

POST/textback-settings

Partial update — only fields you send change. Quiet hours are a fixed compliance floor and not settable.

→ { "ok": true, "updated": ["rescue_delay_seconds"] }

Cancel queued follow-ups

DELETE/followups

Cancel one queued follow-up by id, or everything queued for a phone number.

→ { "ok": true, "cancelled": 2 }

Cancel an appointment

DELETE/appointments/{id}

Marks the appointment cancelled (kept in history), calls off its reminder text, offers the slot to the next person on your waitlist, and fires the appointment_cancelled webhook.

→ { "ok": true, "appointment_id": "…", "status": "cancelled" }

Send a review request

POST/review-request

Schedule the compliant post-job Google-review text to a customer (same link to everyone; opt-out, quiet-hours and A2P gated). Optional follow-up rides the queue.

→ { "ok": true, "status": "scheduled" }

If it can't be sent you get `status: "skipped"` with a `reason` (for example disabled, opted_out, already_sent) — not an error.

Send a referral ask

POST/referral-request

Text a customer you just served a friendly "know someone who could use us?" message (opt-out, quiet-hours and A2P gated like every send). Part of Marketing — AI Voice Pro & Scale — with referral asks switched on in Marketing → Referrals. One ask per customer every 90 days.

→ { "ok": true, "status": "scheduled" }

Otherwise `status: "skipped"` with a `reason`: not_included (plan), disabled, already_sent, opted_out.

Schedule a repeat-booking reminder

POST/rebook

Queue a months-out "time to get back on the schedule" text. Part of Marketing — AI Voice Pro & Scale — with repeat-booking on in Marketing → Referrals. It's a marketing message, so it also needs the marketing-consent switch (Marketing → Campaigns).

→ { "ok": true, "status": "scheduled" }

Otherwise `status: "skipped"` with a `reason`: not_included, disabled, no_marketing_consent, already_sent, opted_out.

Draft a review reply

POST/draft-review-response

AI drafts a reply to a given review for the OWNER to approve and post — it never writes review content itself, only responses.

→ { "ok": true, "draft": "…" }