Quickstart

This quickstart walks you through creating an API key, making your first authenticated request, and registering a webhook endpoint to receive real-time appointment events.

1. Create an API key

Open the Dolores admin UI and go to Settings → API Keys. Click + Create key, give it a label like "Local development", and choose Test mode.

The plaintext key is shown once on creation. Copy it into your environment:

export DOLORES_API_KEY="sk_test_8fK2xPv..."

Live keys (sk_live_...) work the same way but trigger real billing and customer-facing behavior. Use a test key while you build.

2. Make your first request

The simplest authenticated endpoint is GET /v1/ping. It returns the project and mode behind the key.

curl https://app.meetdolores.ai/v1/ping \
  -H "Authorization: Bearer $DOLORES_API_KEY"

{
  "object": "ping",
  "project_id": 42,
  "project_name": "Acme Production",
  "livemode": false,
  "request_id": "req_01HXY7P3K9..."
}

Every response carries a Dolores-Request-Id header. Include it when contacting support so we can trace the request in our logs.

3. Create a customer

Customers are project-scoped. Phone numbers are canonicalized to E.164 at ingest; passing anything else returns a phone_invalid_format error.

curl https://app.meetdolores.ai/v1/customers \
  -H "Authorization: Bearer $DOLORES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+14155551234",
    "name": "Alice Carter",
    "email": "alice@example.com",
    "external_id": "crm-7821",
    "metadata": { "plan": "premium" }
  }'

{
  "id": "cust_01HXY7P3K9...",
  "object": "customer",
  "created_at": "2026-06-06T14:23:11Z",
  "updated_at": "2026-06-06T14:23:11Z",
  "phone": "+14155551234",
  "email": "alice@example.com",
  "name": "Alice Carter",
  "external_id": "crm-7821",
  "metadata": { "plan": "premium" },
  "deleted_at": null
}

Store cust_01HXY7P3K9... in your own database — that's the customer_id you'll reference everywhere else in the API.

4. Register a webhook endpoint

Dolores delivers appointment events to URLs you register. Sign up for a free endpoint at webhook.site for testing:

curl https://app.meetdolores.ai/v1/webhook_endpoints \
  -H "Authorization: Bearer $DOLORES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://webhook.site/your-uuid",
    "event_filters": ["appointment.*"]
  }'

The response includes a one-time secret field — save it. You'll use it to verify the HMAC signature on incoming deliveries.

5. Fire a test event

curl -X POST "https://app.meetdolores.ai/v1/webhook_endpoints/whk_.../test" \
  -H "Authorization: Bearer $DOLORES_API_KEY"

Within a second, your webhook URL receives an appointment.created event with a Dolores-Signature header. Read Your first webhook to learn how to verify the signature in your handler.

Next steps

• Authentication — livemode vs testmode, key rotation, best practices
• Errors — error envelope, type/code taxonomy
• Customers API reference — full CRUD docs with parameters
• Appointments API reference — CRUD + status state machine