Documentation / Recursos Avançados
Recursos Avançados

How to Create a Calendar Via API

Create a Calendar

Overview

The eAgenda platform API allows you to create calendars programmatically, configuring schedules, services, appointment modes, and permissions. This practical guide details how to send an HTTP POST request to the /api/v3/calendars/ endpoint and process the response. For more details, see the official eAgenda API documentation.

Environment Setup

Before you begin, you will need:

  • API Key: Access the eAgenda dashboard to obtain your Bearer token.
  • HTTP request tool: Use cURL, Postman, or libraries such as requests (Python) or axios (JavaScript).
  • Header configuration: Authentication is done via Bearer Token. Set the header Authorization: Bearer and define Content-Type: application/json.

Tip: See the authentication section in the API documentation to configure the token correctly: https://eagenda.com.br/api/v3/documents/#overview.

Calendar Data Definition

To create a calendar, send a JSON object in the request body with the following fields:

{
  "calendar_name": "string",
  "slug": "string",
  "is_internal": boolean,
  "service_list": [
    {
      "service_key": "uuid"
    }
  ],
  "time_config": {
    "opening_hours": [
      {
        "week_day": "string",
        "opening_time": "time",
        "closing_time": "time",
        "max_people": integer
      }
    ],
    "slot_interval": "string",
    "duration": "string",
    "minimum_notice": integer,
    "maximum_notice": integer,
    "start_date": "date",
    "end_date": "date"
  },
  "online_meeting_platform": "string",
  "max_people": integer,
  "request_email": boolean,
  "email_required": boolean,
  "request_phone": boolean,
  "phone_required": boolean,
  "max_companions": integer,
  "max_services": integer,
  "count_companions": boolean,
  "appointment_mode": "string",
  "owner_user": "email",
  "account_slug": "string"
}

calendar_name (required)

  • Description: Calendar name.
  • Constraints: Minimum of 1 character.
  • Impact: Identifies the calendar in the system.
  • Example: “Main Calendar”

slug (optional)

  • Description: Link name for the calendar.
  • Constraints: Maximum of 250 characters, pattern ^[-a-zA-Z0-9_]+$.
  • Impact: Defines a user-friendly identifier for the calendar URL.
  • Example: “main-calendar”

is_internal (required)

  • Description: Indicates whether the calendar is for internal use only (administrators only).
  • Impact: Restricts access to administrators if true.
  • Example: false

service_list (optional)

  • Description: List of services associated with the calendar.
  • Structure: Array of objects, each with a service_key (UUID).
  • How to obtain: Use the service listing endpoint (/api/v3/services/).
  • Impact: Defines the services available for scheduling.
  • Example:[ { "service_key": "19730681-29f0-4000-848c-34869ad83880" } ]

time_config (required)

  • Description: Schedule and appointment settings.
  • Structure: Object with:
    • opening_hours: List of business hours per day of the week.
      • week_day: Day of the week (e.g., “1” for Monday, up to “7” for Sunday).
      • opening_time: Opening time (HH:MM:SS format).
      • closing_time: Closing time (HH:MM:SS format).
      • max_people: Maximum number of people per time slot (min. 0, max. 2147483647).
      • Example:[ { "week_day": "1", "opening_time": "08:00:00", "closing_time": "17:00:00", "max_people": 10 } ]
    • slot_interval: Interval between scheduling options (e.g., “00:15:00” for 15 minutes).
    • duration: Default appointment duration (e.g., “00:30:00”).
    • minimum_notice: Minimum advance notice required to schedule (in hours).
    • maximum_notice: Maximum advance notice allowed to schedule (in days).
    • start_date: Start date for appointments (YYYY-MM-DD format).
    • end_date: End date for appointments (YYYY-MM-DD format).
  • Example:{ "opening_hours": [ { "week_day": "1", "opening_time": "08:00:00", "closing_time": "17:00:00", "max_people": 10 } ], "slot_interval": "00:15:00", "duration": "00:30:00", "minimum_notice": 2, "maximum_notice": 30, "start_date": "2025-06-01", "end_date": "2025-12-31" }

online_meeting_platform (optional)

  • Description: Video conferencing provider.
  • Possible values: meet, teams, zoom, other.
  • Impact: Sets the platform for online meetings.
  • Example: “meet”

max_people (required)

  • Description: Maximum number of people per time slot.
  • Impact: Limits the scheduling capacity.
  • Example: 10

request_email (optional)

  • Description: Request a contact email.
  • Impact: Includes an email field in the scheduling form if true.
  • Example: true

email_required (optional)

  • Description: Email required to schedule.
  • Impact: Requires email if true.
  • Example: false

request_phone (optional)

  • Description: Request a contact phone number.
  • Impact: Includes a phone field in the scheduling form if true.
  • Example: true

phone_required (optional)

  • Description: Phone number required to schedule.
  • Impact: Requires phone number if true.
  • Example: false

max_companions (optional)

  • Description: Maximum number of companions per appointment.
  • Constraints: Minimum of 0, default 0.
  • Impact: Limits the number of companions.
  • Example: 2

max_services (optional)

  • Description: Maximum number of services per appointment.
  • Constraints: Minimum of 0, default 0.
  • Impact: Limits the selectable services.
  • Example: 3

count_companions (optional)

  • Description: Count companions in the total number of people.
  • Impact: Includes companions in the max_people count if true.
  • Example: false

appointment_mode (optional)

  • Description: Appointment mode.
  • Possible values: hybrid, online, on_site, off_site.
  • Impact: Defines whether the appointment is in-person, online, or hybrid.
  • Example: “hybrid”

owner_user (optional)

  • Description: Email of the user responsible for the calendar.
  • Impact: Links the calendar to a responsible user.
  • Example: “responsavel@example.com”

account_slug (optional)

  • Description: Account or sub-account slug.
  • Constraints: Minimum of 1 character, pattern ^[-a-zA-Z0-9_]+$.
  • How to obtain: Use the account listing endpoint.
  • Impact: Links the calendar to a specific account.
  • Example: “minha-conta”

Note: The required fields are calendar_name, is_internal, time_config, and max_people. The remaining fields are optional but recommended for greater control.

Sending the Request to Create a Calendar

To create a calendar, send an HTTP POST request to the endpoint:

https://eagenda.com.br/api/v3/calendars/

Request Configuration

  • Method: POST
  • Headers:
    • accept: application/json
    • Authorization: Bearer
    • Content-Type: application/json
  • Request body: JSON with the calendar data.

cURL Request Example

curl -X POST https://eagenda.com.br/api/v3/calendars/ \
-H "accept: application/json" \
-H "Authorization: Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999" \
-H "Content-Type: application/json" \
-d '{
  "calendar_name": "Agenda Principal",
  "slug": "agenda-principal",
  "is_internal": false,
  "service_list": [
    {
      "service_key": "19730681-29f0-4000-848c-34869ad83880"
    }
  ],
  "time_config": {
    "opening_hours": [
      {
        "week_day": "1",
        "opening_time": "08:00:00",
        "closing_time": "17:00:00",
        "max_people": 10
      }
    ],
    "slot_interval": "00:15:00",
    "duration": "00:30:00",
    "minimum_notice": 2,
    "maximum_notice": 30,
    "start_date": "2025-06-01",
    "end_date": "2025-12-31"
  },
  "online_meeting_platform": "meet",
  "max_people": 10,
  "request_email": true,
  "email_required": false,
  "request_phone": true,
  "phone_required": false,
  "max_companions": 2,
  "max_services": 3,
  "count_companions": false,
  "appointment_mode": "hybrid",
  "owner_user": "responsavel@example.com",
  "account_slug": "minha-conta"
}'

Python Example (using requests)

import requests

url = "https://eagenda.com.br/api/v3/calendars/"
headers = {
    "accept": "application/json",
    "Authorization": "Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999",
    "Content-Type": "application/json"
}
data = {
    "calendar_name": "Agenda Principal",
    "slug": "agenda-principal",
    "is_internal": False,
    "service_list": [
        {
            "service_key": "19730681-29f0-4000-848c-34869ad83880"
        }
    ],
    "time_config": {
        "opening_hours": [
            {
                "week_day": "1",
                "opening_time": "08:00:00",
                "closing_time": "17:00:00",
                "max_people": 10
            }
        ],
        "slot_interval": "00:15:00",
        "duration": "00:30:00",
        "minimum_notice": 2,
        "maximum_notice": 30,
        "start_date": "2025-06-01",
        "end_date": "2025-12-31"
    },
    "online_meeting_platform": "meet",
    "max_people": 10,
    "request_email": True,
    "email_required": False,
    "request_phone": True,
    "phone_required": False,
    "max_companions": 2,
    "max_services": 3,
    "count_companions": False,
    "appointment_mode": "hybrid",
    "owner_user": "responsavel@example.com",
    "account_slug": "minha-conta"
}

response = requests.post(url, json=data, headers=headers)
print(response.status_code)
print(response.json())

Response Verification

The API will return a response with the calendar creation status. Check the following:

  • HTTP status code:
    • 201 Created: Calendar created successfully.
    • 400 Bad Request: Error in the submitted data (check the JSON).
    • 401 Unauthorized: Invalid or missing token.
  • Response body: Contains details of the created calendar, such as:{ "calendar_key": "19730681-29f0-4000-8d78-94e4d6116180", "calendar_name": "Agenda Principal", "slug": "agenda-principal", "is_active": false, "is_internal": false, "service_list": [ { "service_key": "19730681-29f0-4000-848c-34869ad83880", "service_name": "Consulta Médica" } ], "appointment_link": "https://eagenda.com.br/agenda-principal", "time_config": { "opening_hours": [ { "week_day": "1", "opening_time": "08:00:00", "closing_time": "17:00:00", "max_people": 10 } ], "slot_interval": "00:15:00", "duration": "00:30:00", "minimum_notice": 2, "maximum_notice": 30, "start_date": "2025-06-01", "end_date": "2025-12-31" }, "online_meeting_platform": "meet", "max_people": 10, "request_email": true, "email_required": false, "request_phone": true, "phone_required": false, "max_companions": 2, "max_services": 3, "count_companions": false, "appointment_mode": "hybrid", "owner_user": "responsavel@example.com", "address": { "postal_code": "12345-678", "street": "Rua Exemplo", "neighborhood": "Centro", "number": "123", "complement": "Sala 101", "city": { "name": "São Paulo", "state_name": "São Paulo", "state_code": "SP", "country_code": "BR" } }, "account_slug": "minha-conta" }

The calendar will be registered in the system and ready to receive appointments, following the defined settings.

Conclusion

With this tutorial, you learned how to create a calendar via the eAgenda API, configuring schedules, services, and permissions efficiently. This integration is ideal for managing appointments in different contexts, such as in-person, online, or hybrid. For more features, such as listing or editing calendars, see the complete eAgenda API documentation.

Get in Touch or Learn More

We are here to help! Access our official channels:

📞 WhatsApp : Click here to send us a message 🌐 eAgenda Platform : Discover eAgenda 🏢 Our Company : Mupi Systems – Innovative Solutions 📧 Email : contato@mupisystems.com.br 📚 Tutorials and Documentation : Access our guides and tutorials