In this tutorial, you’ll learn the complete flow for creating an appointment via API: from querying calendars and time slots to confirming the appointment.

Appointment flow

The process follows 4 steps:

List calendars — Get the available calendars
List services — See the offered services
Check time slots — Verify availability
Create the appointment — Submit the appointment data

Step 1: List calendars

First, get the list of calendars for your account:

curl -X GET "https://eagenda.com.br/api/v3/calendars/?is_active=true" \
  -H "Authorization: Basic YOUR_TOKEN"

Response:

{
  "count": 2,
  "results": [
    {
      "calendar_key": "abc12345-1234-5678-9abc-def012345678",
      "name": "Dr. Silva's Office",
      "slug": "dr-silvas-office",
      "is_active": true,
      "appointment_mode": "hybrid"
    }
  ]
}

Save the calendar_key — you’ll need it in the next steps.

Step 2: List services

Query the available services for scheduling:

curl -X GET "https://eagenda.com.br/api/v3/services/" \
  -H "Authorization: Basic YOUR_TOKEN"

Response:

{
  "count": 3,
  "results": [
    {
      "service_key": "srv12345-1234-5678-9abc-def012345678",
      "name": "Initial Consultation",
      "duration": 60,
      "price": "150.00",
      "is_active": true
    }
  ]
}

Save the service_key of the desired services.

Step 3: Check available time slots

With the calendar_key and service_keys, query the available time slots for a specific day:

curl -X GET "https://eagenda.com.br/api/v3/available-date-times/?calendar_key=abc12345-1234-5678-9abc-def012345678&day=2026-06-10&service_keys=srv12345-1234-5678-9abc-def012345678" \
  -H "Authorization: Basic YOUR_TOKEN"

Response:

{
  "count": 8,
  "results": [
    {
      "start_date": "2026-06-10T09:00:00-03:00",
      "end_date": "2026-06-10T10:00:00-03:00",
      "vacancies_available": 1
    },
    {
      "start_date": "2026-06-10T10:00:00-03:00",
      "end_date": "2026-06-10T11:00:00-03:00",
      "vacancies_available": 1
    }
  ]
}

Tip: Use the action_new_appointment=client parameter to see only time slots available considering client scheduling restrictions.

Step 4: Create the appointment

With all the information, create the appointment:

curl -X POST "https://eagenda.com.br/api/v3/appointments/" \
  -H "Authorization: Basic YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "calendar_key": "abc12345-1234-5678-9abc-def012345678",
    "start_date": "2026-06-10T09:00:00-03:00",
    "service_keys": ["srv12345-1234-5678-9abc-def012345678"],
    "person": {
      "full_name": "John Smith",
      "email": "john@example.com",
      "phone": "+15551234567"
    }
  }'

Response (201 Created):

{
  "appointment_key": "apt12345-1234-5678-9abc-def012345678",
  "search_code": "AGD-2026-001234",
  "status": "CONFIRMED",
  "start_date": "2026-06-10T09:00:00-03:00",
  "end_date": "2026-06-10T10:00:00-03:00",
  "calendar": {
    "calendar_key": "abc12345-1234-5678-9abc-def012345678",
    "name": "Dr. Silva's Office"
  },
  "person": {
    "person_key": "prs12345-1234-5678-9abc-def012345678",
    "full_name": "John Smith",
    "email": "john@example.com"
  },
  "services": [
    {
      "service_key": "srv12345-1234-5678-9abc-def012345678",
      "name": "Initial Consultation"
    }
  ]
}

Complete example in Python

import requests

BASE_URL = "https://eagenda.com.br/api/v3"
AUTH = ("my@email.com", "my_password")

# 1. List active calendars
calendars = requests.get(
    f"{BASE_URL}/calendars/",
    auth=AUTH,
    params={"is_active": True}
).json()

calendar_key = calendars["results"][0]["calendar_key"]

# 2. List services
services = requests.get(f"{BASE_URL}/services/", auth=AUTH).json()
service_key = services["results"][0]["service_key"]

# 3. Check available time slots
slots = requests.get(
    f"{BASE_URL}/available-date-times/",
    auth=AUTH,
    params={
        "calendar_key": calendar_key,
        "day": "2026-06-10",
        "service_keys": service_key,
    }
).json()

start_date = slots["results"][0]["start_date"]

# 4. Create the appointment
appointment = requests.post(
    f"{BASE_URL}/appointments/",
    auth=AUTH,
    json={
        "calendar_key": calendar_key,
        "start_date": start_date,
        "service_keys": [service_key],
        "person": {
            "full_name": "John Smith",
            "email": "john@example.com",
            "phone": "+15551234567",
        },
    }
).json()

print(f"Appointment created: {appointment['search_code']}")
print(f"Status: {appointment['status']}")

Possible errors

Code	Cause	Solution
`400`	Invalid or incomplete data	Check the required fields
`400`	Time slot not available	Query available times again
`401`	Not authenticated	Check your credentials
`403`	No permission	Check account permissions