BizBlock API Documentation

API Reference

Booking infrastructure
for AI agents

Search local service businesses, check real-time availability, and create bookings. One API. Every AI agent.

Base URL https://api.bizblock.io

Authentication

API Keys

All requests require an API key passed via the X-API-Key header.

bb_test_ → Test mode (sandbox)

bb_live_ → Production (real bookings)

To request an API key, contact us at [email protected]

curl

curl https://api.bizblock.io/v1/businesses \
  -H "X-API-Key: bb_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

💡 Rate limit: 1,000 requests/hour per API key. Prices are in cents (7500 = $75.00). Timestamps include timezone offsets (e.g., -06:00).

Quickstart

Book your first appointment in 5 minutes

Search for a business

Find businesses by name or location. Get a business_id from the results.

# Find salons
curl "https://api.bizblock.io/v1/businesses?query=Salon" \
  -H "X-API-Key: $API_KEY"

Get services and pick one

List services to get a service_id, price, and duration.

curl "https://api.bizblock.io/v1/businesses/{business_id}/services" \
  -H "X-API-Key: $API_KEY"

Check availability

Get open time slots for a specific date. Slots include timezone offsets — pass them directly to booking.

curl "https://api.bizblock.io/v1/businesses/{business_id}/availability?service_id={service_id}&date=2026-02-02" \
  -H "X-API-Key: $API_KEY"

Create the booking

Book a slot. Pass the start_time exactly as returned by availability. Get a confirmation_code back.

curl -X POST "https://api.bizblock.io/v1/bookings" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "business_id": "{business_id}",
    "service_id": "{service_id}",
    "start_time": "2026-02-02T14:00:00-06:00",
    "customer": {
      "name": "Jane Smith",
      "email": "[email protected]",
      "phone": "+15551234567"
    }
  }'

✓ That's it. Four API calls: search → services → availability → book. A customer is created automatically.

Businesses

Search & Retrieve

GET /v1/businesses?query= Search businesses ▾

Search for businesses by name, keyword, or location. Pass lat, lng, and radius_miles for proximity search.

Query Parameters

Name	Type	Description
query	string	Search term (name, service type, keyword)
lat	number	Latitude for proximity search
lng	number	Longitude for proximity search
radius_miles	number	Search radius in miles (default: 10, max: 50)

200 Matching businesses

{
  "businesses": [
    {
      "id": "2a7d6d67-b43d-4dd5-a211-eb1e112ceed8",
      "name": "Salon Three One Four",
      "slug": "salon-three-one-four",
      "description": "Full-service salon in St. Louis"
    }
  ]
}

GET /v1/businesses/{business_id} Get business details ▾

Get detailed information about a specific business including hours, location, social links, and booking policies.

Path Parameters

Name	Type	Description
business_idREQUIRED	string	Business ID

200 Business details

{
  "id": "2a7d6d67-b43d-4dd5-a211-eb1e112ceed8",
  "name": "Salon Three One Four",
  "slug": "salon-three-one-four",
  "description": "Full-service salon in St. Louis",
  "logo": "https://..."
}

Services

Service Catalog

GET /v1/businesses/{business_id}/services List services ▾

Get all services offered by a business. Prices are in cents (7500 = $75.00).

200 Service list

{
  "services": [
    {
      "id": "cb62c081-59c7-4064-8460-a7b99227d10f",
      "name": "Men's Cut",
      "price": 7500,
      "currency": "USD",
      "duration": 60,
      "description": "Classic men's haircut"
    },
    {
      "id": "19f757e3-2e9c-407c-8848-3b08e58e40a1",
      "name": "Kérastase Scalp Facial",
      "price": 18000,
      "currency": "USD",
      "duration": 90
    }
  ]
}

GET /v1/businesses/{business_id}/services/{service_id} Get service details ▾

Get details for a specific service including price, duration, and description.

Team

Staff Members

GET /v1/businesses/{business_id}/team List team members ▾

List staff at a business. Use team member IDs to let customers choose a specific stylist, therapist, or provider when checking availability and creating bookings.

200 Team members

{
  "team_members": [
    {
      "id": "938b14c9-e259-4378-8ffe-1d57d2d8164e",
      "name": "Griffin Killion",
      "role": "owner"
    }
  ]
}

Availability

Real-time Scheduling

GET /v1/businesses/{business_id}/availability Get availability ▾

Get available time slots for a service on a specific date. Slots include timezone offsets — pass start_time directly to the booking endpoint. No timezone conversion needed.

Query Parameters

Name	Type	Description
service_idREQUIRED	uuid	Service ID to check availability for
dateREQUIRED	date	Date to check (YYYY-MM-DD)
team_member_id	string	Filter slots to a specific team member

200 Available slots

{
  "business_id": "2a7d6d67-b43d-4dd5-a211-eb1e112ceed8",
  "timezone": "America/Chicago",
  "service_id": "cb62c081-59c7-4064-8460-a7b99227d10f",
  "duration": 60,
  "slots": [
    {
      "start_time": "2026-02-02T09:00:00-06:00",
      "end_time": "2026-02-02T10:00:00-06:00"
    },
    {
      "start_time": "2026-02-02T10:00:00-06:00",
      "end_time": "2026-02-02T11:00:00-06:00"
    }
  ]
}

⏰ Slots use the business's local timezone with UTC offset. -06:00 = Central (winter), -05:00 = Central (summer). DST-aware.

GET /v1/businesses/{business_id}/availability/next Next available slot ▾

Get the soonest available slot for a service. Useful when a customer says "book me the next available appointment."

Query Parameters

Name	Type	Description
service_idREQUIRED	uuid	Service ID to check

Bookings

Create & Manage

POST /v1/bookings Create booking ▾

Create a booking. Pass the start_time from availability — timezone offset included. A customer record is created automatically. Records are scoped per business (same email at different businesses = separate records).

Request Body

Name	Type	Description
business_idREQUIRED	string	Business ID
service_idREQUIRED	uuid	Service to book
start_timeREQUIRED	datetime	ISO 8601 with offset (e.g., `2026-02-02T14:00:00-06:00`)
customerREQUIRED	object	Customer info: `{ name, email, phone? }`
team_member_id	string	Assign a specific staff member
notes	string	Booking notes (max 1000 chars)
agent_id	string	AI agent identifier (max 100 chars)

Request

curl -X POST "https://api.bizblock.io/v1/bookings" \
  -H "X-API-Key: bb_test_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "business_id": "2a7d6d67-b43d-4dd5-a211-eb1e112ceed8",
    "service_id": "cb62c081-59c7-4064-8460-a7b99227d10f",
    "start_time": "2026-02-02T14:00:00-06:00",
    "customer": {
      "name": "Jane Smith",
      "email": "[email protected]",
      "phone": "+15551234567"
    },
    "notes": "First visit"
  }'

201 Booking created

{
  "id": "8a273c98-35b4-4f80-8c0a-6f031880e893",
  "business_id": "2a7d6d67-b43d-4dd5-a211-eb1e112ceed8",
  "business_name": "Salon Three One Four",
  "service_name": "Men's Cut",
  "customer": {
    "id": "f28bf149-f636-4185-ab6c-fa6e52233268",
    "name": "Jane Smith",
    "email": "[email protected]",
    "verified": false
  },
  "start_time": "2026-02-02T20:00:00.000Z",
  "end_time": "2026-02-02T21:00:00.000Z",
  "status": "confirmed",
  "price": 7500,
  "currency": "USD",
  "team_member_name": "Griffin Killion",
  "confirmation_code": "341458",
  "cancellation_policy": "Free cancellation up to 24 hours before appointment"
}

GET /v1/bookings/{booking_id} Get booking ▾

Retrieve details of an existing booking by ID.

POST /v1/bookings/{booking_id}/confirm Confirm booking ▾

Confirm a booking using the 6-digit confirmation code.

Request Body

Name	Type	Description
confirmation_codeREQUIRED	string	6-digit code from booking creation

POST /v1/bookings/{booking_id}/cancel Cancel booking ▾

Cancel a booking. Subject to the business's cancellation policy.

Request Body (optional)

Name	Type	Description
cancel_reason	string	Reason for cancellation (max 500 chars)

POST /v1/bookings/{booking_id}/reschedule Reschedule booking ▾

Move a booking to a new time. The new slot must be available.

Request Body

Name	Type	Description
new_start_timeREQUIRED	datetime	New time with timezone offset
team_member_id	string	Optionally change the assigned staff member

Customers

Verification

POST /v1/customers/verify Start verification ▾

Send a verification code to a customer's email or phone.

Request Body

Name	Type	Description
business_idREQUIRED	string	Business ID
contactREQUIRED	string	Email address or phone number
methodREQUIRED	string	`"email"` or `"sms"`

POST /v1/customers/verify/complete Complete verification ▾

Submit the verification code the customer received.

Request Body

Name	Type	Description
verification_idREQUIRED	string	ID returned from the verify endpoint
codeREQUIRED	string	Verification code

Booking infrastructurefor AI agents

API Keys

Book your first appointment in 5 minutes

Search & Retrieve

Service Catalog

Staff Members

Real-time Scheduling

Create & Manage

Verification

Booking infrastructure
for AI agents