bobbuilt.io

Overview

A small REST API for reading your agency's calendar, booking appointments, and syncing contacts — built for voice agents, quiz funnels, and your own automations. Every request is scoped to a single agency by its API key.

All endpoints accept and return JSON over HTTPS. Timestamps are ISO 8601 in UTC; dates and times you send for booking are interpreted in the agency's configured booking timezone, which every availability response echoes back. CORS is open and each endpoint answers OPTIONS preflight, so browser-based tools and no-code platforms can call the API directly.

Notice

API keys grant access to a single agency's calendar and contacts. Keep them server-side, never ship them in a browser bundle, and revoke any key you suspect has leaked. Contact us to report an issue or request access.

AuthorizationBearer token

Key

Authorization

Value

Bearer bb_live_XXXXXXXXXXXXXXXXXXXXXXXX

Base URL

https://bobbuilt.io

Inbound webhook endpoints use the agency webhook secret instead, since they are configured inside third-party tools like GoHighLevel.

Authenticated request

curl

curl --location "https://bobbuilt.io/api/public/webhooks/contacts" \
--header "Authorization: Bearer $BOBBUILT_API_KEY"

GET/book/availability

https://bobbuilt.io/api/public/webhooks/book/availability?from=2026-08-10&to=2026-08-24

List available dates

Returns every date in the requested range that has at least one open appointment slot, along with the agency's booking timezone and slot length.

AuthorizationAgency API key

Header

Authorization: Bearer <token>

Params

fromrequired

string (YYYY-MM-DD)

First date of the range.

torequired

string (YYYY-MM-DD)

Last date of the range. Max 62 days after from.

Example Request

curl

curl --location "https://bobbuilt.io/api/public/webhooks/book/availability?from=2026-08-10&to=2026-08-24" \
--header "Authorization: Bearer $BOBBUILT_API_KEY"

Example Response

200 OK

json

{
  "agency_id": "8f1c...c2a1",
  "timezone": "America/Chicago",
  "slot_minutes": 30,
  "from": "2026-08-10",
  "to": "2026-08-24",
  "available_dates": [
    { "date": "2026-08-10", "slots": 9 },
    { "date": "2026-08-11", "slots": 12 }
  ]
}

GET/book/availability/{date}

https://bobbuilt.io/api/public/webhooks/book/availability/2026-08-11

List slots for a date

Returns the open slots for a single date. time is the local wall clock in the agency's timezone; iso is the same instant in UTC and is the value the booking endpoint validates against.

AuthorizationAgency API key

Header

Authorization: Bearer <token>

Params

daterequired

string (YYYY-MM-DD)

Path segment. The date to inspect.

Example Request

curl

curl --location "https://bobbuilt.io/api/public/webhooks/book/availability/2026-08-11" \
--header "Authorization: Bearer $BOBBUILT_API_KEY"

Example Response

200 OK

json

{
  "agency_id": "8f1c...c2a1",
  "date": "2026-08-11",
  "timezone": "America/Chicago",
  "slot_minutes": 30,
  "slots": [
    { "time": "09:00", "iso": "2026-08-11T14:00:00.000Z" },
    { "time": "09:30", "iso": "2026-08-11T14:30:00.000Z" }
  ]
}

POST/book

https://bobbuilt.io/api/public/webhooks/book

Book an appointment

Books an appointment on the agency calendar. The contact is matched by phone number — an existing lead is updated, otherwise a new lead is created and marked as qualified. date and time are interpreted in the agency's booking timezone.

AuthorizationAgency API key

Header

Authorization: Bearer <token>

Bodyraw (json)

daterequired

string (YYYY-MM-DD)

Appointment date, agency local.

timerequired

string (HH:MM)

24-hour local start time. Must match an open slot.

first_namerequired

string

Contact first name.

last_namerequired

string

Contact last name.

emailrequired

string

Valid email address.

phonerequired

string

Phone number. Used as the dedupe key for the lead.

notes

string

Optional free-text note stored on the appointment (max 2000 chars).

Example Request

curl

curl --location --request POST "https://bobbuilt.io/api/public/webhooks/book" \
--header "Authorization: Bearer $BOBBUILT_API_KEY" \
--header "Content-Type: application/json" \
--data '{
  "date": "2026-08-11",
  "time": "09:30",
  "first_name": "Dana",
  "last_name": "Ruiz",
  "email": "dana@example.com",
  "phone": "+15125550188",
  "notes": "Wants term coverage, prefers mornings"
}'

Example Response

200 OK

json

{
  "ok": true,
  "appointment_id": "4c2e...9ab0",
  "lead_id": "7d10...1f42",
  "scheduled_at": "2026-08-11T14:30:00.000Z",
  "agent_name": "Bob Kleffner"
}

GET/contacts

https://bobbuilt.io/api/public/webhooks/contacts?q=ruiz&limit=25

List contacts

Lists leads for the authenticated agency, newest first. Combine filters to narrow the result set.

AuthorizationAgency API key

Header

Authorization: Bearer <token>

Params

phone

string

Exact phone match.

string

Exact email match.

string

Partial match across first name, last name, email, and phone.

limit

integer

Max rows to return. Default 50, max 200.

Example Request

curl

curl --location "https://bobbuilt.io/api/public/webhooks/contacts?q=ruiz&limit=25" \
--header "Authorization: Bearer $BOBBUILT_API_KEY"

Example Response

200 OK

json

{
  "contacts": [
    {
      "id": "7d10...1f42",
      "first_name": "Dana",
      "last_name": "Ruiz",
      "email": "dana@example.com",
      "phone": "+15125550188",
      "status": "qualified",
      "source": "voice_ai",
      "created_at": "2026-08-06T18:04:11.220Z"
    }
  ]
}

GET/contacts/{id}

https://bobbuilt.io/api/public/webhooks/contacts/+15125550188

Get a contact

Returns one contact plus all of their appointments. The path segment accepts either the lead UUID or the contact's phone number.

AuthorizationAgency API key

Header

Authorization: Bearer <token>

Params

idrequired

string (uuid | phone)

Lead id or phone number.

Example Request

curl

curl --location "https://bobbuilt.io/api/public/webhooks/contacts/+15125550188" \
--header "Authorization: Bearer $BOBBUILT_API_KEY"

Example Response

200 OK

json

{
  "contact": {
    "id": "7d10...1f42",
    "first_name": "Dana",
    "last_name": "Ruiz",
    "email": "dana@example.com",
    "phone": "+15125550188",
    "status": "qualified",
    "source": "voice_ai",
    "created_at": "2026-08-06T18:04:11.220Z",
    "quiz_answers": { "project_type": "Book a consultation", "service_level": "Premium" }
  },
  "appointments": [
    { "id": "4c2e...9ab0", "scheduled_at": "2026-08-11T14:30:00.000Z", "status": "scheduled" }
  ]
}

POST/funnel/webhook

https://bobbuilt.io/api/public/funnel/webhook

Create a lead from an external quiz

Accepts a flexible JSON payload from an external quiz or form. Known fields map to lead columns; anything else is preserved in quiz_answers. Returns a booking URL that already carries the lead token, so you can redirect the prospect straight into a tracked calendar.

AuthorizationAgency webhook secret

Header

Authorization: Bearer <token>

Bodyraw (json)

first_name / last_name

string

Or send name / full_name and it will be split.

string

Valid email address.

phone

string

Phone number.

dob

string

Date of birth. Common formats including ordinals ("July 4th, 1985") are parsed.

state, zip, gender, tobacco_use, coverage_amount, coverage_reason, health_rating

mixed

Optional qualification fields.

utm_source, utm_medium, utm_campaign, utm_content, utm_term, fbclid

string

Attribution, stored on the lead.

Example Request

curl

curl --location --request POST "https://bobbuilt.io/api/public/funnel/webhook" \
--header "Authorization: Bearer $AGENCY_WEBHOOK_SECRET" \
--header "Content-Type: application/json" \
--data '{
  "first_name": "Dana",
  "last_name": "Ruiz",
  "email": "dana@example.com",
  "phone": "+15125550188",
  "dob": "July 4th, 1985",
  "coverage_amount": 250000,
  "utm_source": "facebook"
}'

Example Response

200 OK

json

{
  "lead_token": "lt_9f2c...",
  "booking_url": "https://bobbuilt.io/kleffner/book?lt=lt_9f2c..."
}

POST/webhooks/ghl

https://bobbuilt.io/api/public/webhooks/ghl

GoHighLevel contact webhook

Drop-in endpoint for a GoHighLevel workflow webhook action. Point a "Contact Created" (or form submitted) trigger at this URL with the agency webhook secret in the Authorization header and a custom JSON body containing agency_id and the contact fields. New leads fire the owner's new-lead notification email.

AuthorizationAgency webhook secret

Header

Authorization: Bearer <token>

Example Request

curl

curl --location --request POST "https://bobbuilt.io/api/public/webhooks/ghl" \
--header "Authorization: Bearer $AGENCY_WEBHOOK_SECRET" \
--header "Content-Type: application/json" \
--data '{
  "agency_id": "8f1c...c2a1",
  "first_name": "{{contact.first_name}}",
  "last_name": "{{contact.last_name}}",
  "email": "{{contact.email}}",
  "phone": "{{contact.phone}}"
}'

Example Response

200 OK

json

{ "ok": true, "lead_id": "7d10...1f42" }

MCP server

Bobbuilt also exposes a Model Context Protocol server so AI assistants can work with your workspace directly. Add the URL to any MCP-compatible client, sign in with your Bobbuilt account when prompted, and approve access. Tools run as you, with the same row-level permissions as the dashboard.

get_meReturns the signed-in user's profile, agency, and roles.

list_leadsSearch and page through the agency's leads by name, email, phone, or status.

get_leadFetch one lead including quiz answers and UTM attribution.

create_leadCreate a new lead in the agency.

list_appointmentsList upcoming (or all) appointments on the agency calendar.

Server URL

url

https://bobbuilt.io/mcp

Errors

Errors return the appropriate HTTP status with a JSON body of the shape { "error": "..." }.

400Validation failed — a required field is missing or malformed. The response includes issues when the payload failed schema validation.

401Missing bearer token, or the API key is invalid or revoked.

404The agency or contact could not be found for this key.

409The requested slot is not available, or was booked between your availability check and the booking call. The availability response is included so you can retry.

500Unexpected server error. Safe to retry with backoff.

Error body

4xx / 5xx

json

{
  "error": "Slot is no longer available"
}

Recipe: booking from a voice agent

The intended flow for a voice assistant that books on the agency calendar during a live call.

1Look the caller up with GET /contacts?phone=… so the agent can greet a returning lead by name.
2Call GET /book/availability for the next 7–14 days to find dates with openings.
3Call GET /book/availability/{date} for the chosen day and read two or three times back to the caller.
4Call POST /book with the caller's details and the confirmed date and time.
5On 409, the slot was taken mid-call — re-read the returned availability and offer another time.

Need a key or have a question about the API? Get in touch.

Step 4 — book the slot

curl

curl --location --request POST "https://bobbuilt.io/api/public/webhooks/book" \
--header "Authorization: Bearer $BOBBUILT_API_KEY" \
--header "Content-Type: application/json" \
--data '{"date":"2026-08-11","time":"09:30",
  "first_name":"Dana","last_name":"Ruiz",
  "email":"dana@example.com","phone":"+15125550188"}'