Developers

Business API usage guide

Enterprise accounts can generate API keys to manage locations and free/busy data from external systems. Keys are issued in the dashboard; plaintext secrets are shown once.

Authentication

Send your API key on every request. Revoked or non-Enterprise keys return 401/402.

curl -s https://earliestappointment.com/api/v1/businesses \
  -H "Authorization: Bearer ea_YOUR_KEY"

List businesses

GET /api/v1/businesses — returns all locations owned by the key's account.

{
  "data": [
    {
      "id": "clx…",
      "name": "Riverside Dental",
      "slug": "riverside-dental-nyc",
      "city": "New York",
      "state": "NY",
      "nextAvailableDate": "2026-07-18T00:00:00.000Z",
      "category": { "slug": "dental", "name": "Dental" }
    }
  ]
}

Get one business

GET /api/v1/businesses/:id — includes hours and specialties.

Update profile

PATCH /api/v1/businesses/:id — partial update. Allowed fields: name, description, phone, email, websiteUrl, bookingUrl, address fields, timezone, lat, lng, nextAvailableDate.

curl -X PATCH https://earliestappointment.com/api/v1/businesses/BUSINESS_ID \
  -H "Authorization: Bearer ea_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "555-0100",
    "bookingUrl": "https://example.com/book",
    "nextAvailableDate": "2026-07-20T14:00:00.000Z"
  }'

Hours of operation

GET /api/v1/businesses/:id/hours
PUT /api/v1/businesses/:id/hours — replace the week. dayOfWeek is 0=Sunday … 6=Saturday.

{
  "hours": [
    { "dayOfWeek": 1, "closed": false, "openTime": "09:00", "closeTime": "17:00" },
    { "dayOfWeek": 0, "closed": true }
  ]
}

Availability (free/busy)

GET /api/v1/businesses/:id/availability
PUT /api/v1/businesses/:id/availability — send busy intervals only. By default, replaces blocks with the same source (default api).

{
  "source": "api",
  "replace": true,
  "nextAvailableDate": "2026-07-21T09:00:00.000Z",
  "blocks": [
    {
      "startAt": "2026-07-16T13:00:00.000Z",
      "endAt": "2026-07-16T14:00:00.000Z",
      "isBusy": true
    }
  ]
}

Do not send patient names, event titles, or other personal data — free/busy intervals only.

Errors

• 401 — missing or invalid key
• 402 — account is not on Enterprise
• 404 — business not found for this account
• 400 — validation error (error message in JSON)