Appointments

Book an appointment (Tier 2: the customer may be texted)

POST /v1/appointments

Scope

appointments:write

Tier

Tier 2 (reaches or unlocks real people)

Data

Personal data

Idempotency

Idempotency-Key: required

TIER 2. If the account has appointment confirmations on, the customer is texted that the appointment is booked, and the booking is synced to the account's connected calendar if it has one. Needs the appointments:write scope and the account switch tier2_appointment_write_enabled. Calendar-invite email is not offered, so the request carries no email address. A number in a country the platform does not contact answers 422 blocked_country.

Parameters

Request body

The appointment.

JSON: AppointmentCreateRequest

Response

201: The appointment.

Examples

Request example

curl

curl -sS -X POST \
  "https://app.dialerbee.com/api/v1/appointments" \
  -H "Authorization: Bearer $DIALERBEE_API_KEY" \
  -H 'Idempotency-Key: 5f2b7c1e-8a3d-4c6f-9b0e-2d4a6c8e1f3a' \
  -H "Content-Type: application/json" \
  --data '{
  "phone": "+12125550123",
  "scheduled_at": "2026-10-01T14:00:00Z",
  "duration_minutes": 30,
  "timezone": "Asia/Amman",
  "service_type": "Consultation",
  "contact_name": "Ann Lee",
  "notes": "Prefers calls after 5 pm."
}'

Python (SDK)

from dialerbee import DialerBee

db = DialerBee()  # reads DIALERBEE_API_KEY from the environment

result = db.appointments.create(
    phone="+12125550123",
    scheduled_at="2026-10-01T14:00:00Z",
    duration_minutes=30,
    timezone="Asia/Amman",
    service_type="Consultation",
    contact_name="Ann Lee",
    notes="Prefers calls after 5 pm.",
    idempotency_key="5f2b7c1e-8a3d-4c6f-9b0e-2d4a6c8e1f3a",
)

Response example

201

{
  "id": "appt_0f8fad5b-d9cb-469f-a165-70867728950e",
  "status": "scheduled",
  "scheduled_at": "2026-10-01T14:00:00Z",
  "timezone": "Asia/Amman",
  "duration_minutes": 30,
  "service_type": "Consultation",
  "contact_name": "Ann Lee",
  "phone": "+12125550101",
  "email": "[email protected]",
  "notes": "Prefers calls after 5 pm.",
  "source": "api",
  "created_at": "2026-09-29T09:15:00Z",
  "updated_at": "2026-09-29T09:20:00Z"
}

Error examples

422 blocked_country

{
  "type": "https://docs.dialerbee.com/errors/blocked-country",
  "title": "Destination country blocked",
  "status": 422,
  "detail": "The platform does not contact numbers in this country.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "blocked_country",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

403 tier_not_enabled

{
  "type": "https://docs.dialerbee.com/errors/tier-not-enabled",
  "title": "Capability not enabled",
  "status": 403,
  "detail": "This operation can reach or unlock real people.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "tier_not_enabled",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

409 outcome_unknown

{
  "type": "https://docs.dialerbee.com/errors/outcome-unknown",
  "title": "Outcome unknown",
  "status": 409,
  "detail": "An earlier request with this Idempotency-Key may or may not have taken effect: the platform did not confirm it.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "outcome_unknown",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

Errors

Objects

AppointmentCreateRequest

Appointment