Documentation / Recursos Avançados
Recursos Avançados

How to Create an Appointment Via API in eAgenda

Create an Appointment Via eAgenda API

Overview

The eAgenda platform API allows you to create an appointment programmatically, configuring details such as calendar, services, attendees, and time slots. This practical guide explains how to send an HTTP POST request to the /api/v3/appointments/ 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: Refer to the authentication section in the API documentation to configure the token correctly: https://eagenda.com.br/api/v3/documents/#overview.

Appointment Data Definition

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

{
  "status": "string",
  "calendar_key": "uuid",
  "service_list": [
    {
      "service_key": "uuid"
    }
  ],
  "tag_list": [
    {
      "tag_key": "uuid"
    }
  ],
  "owner_user": {
    "email": "email"
  },
  "attendees": [
    {
      "name": "string",
      "email": "email",
      "phone": "string",
      "identification_code": "string",
      "identification_type": "string"
    }
  ],
  "start": {
    "dateTime": "date-time"
  },
  "description": "string",
  "verify_limits": boolean,
  "send_email": boolean,
  "include_flows": boolean,
  "account_slug": "string"
}

status (optional)

  • Description: Initial status of the appointment.
  • Possible values: ATTENDED, CANCELED, CANCELED_CLIENT, CANCELED_GOOGLE, CONFIRMED, IN_PROGRESS, NO_SHOW, PENDING, PENDING_COMPANIONS, PENDING_FORM, PENDING_PAYMENT.
  • Impact: Sets the appointment state; defaults to PENDING if not provided.
  • Example: “PENDING”

calendar_key (required)

  • Description: UUID key of the calendar.
  • Impact: Links the appointment to a specific calendar.
  • How to obtain: Use the calendar listing endpoint (/api/v3/calendars/).
  • Example: “1973125a-ab10-4000-8674-eef17b31e080”

service_list (optional)

  • Description: List of services associated with the appointment.
  • Structure: Array of objects, each with service_key (UUID).
  • How to obtain: Use the service listing endpoint (/api/v3/services/).
  • Impact: Specifies the services to be performed.
  • Example:[ { "service_key": "19730681-2aa0-4000-84b6-2bc54b4ace01" } ]

tag_list (optional)

  • Description: List of tags associated with the appointment.
  • Structure: Array of objects, each with tag_key (UUID).
  • How to obtain: Use the tag listing endpoint.
  • Impact: Allows categorizing the appointment.
  • Example:[ { "tag_key": "a1b2c3d4-e5f6-7890-1234-567890abcdef" } ]

owner_user (optional)

  • Description: User responsible for the appointment.
  • Structure: Object with email.
  • Impact: Links the appointment to a responsible user.
  • Example:{ "email": "responsible@example.com" }

attendees (required)

  • Description: List of appointment attendees.
  • Structure: Array of objects, each with:
    • name (required): Attendee name (1 to 200 characters).
    • email (optional): Attendee email.
    • phone (optional): Phone number in E.164 format.
    • identification_code (optional): Identification document number.
    • identification_type (optional): Document type (e.g., br_cpf, ar_dni).
  • Impact: Defines who will participate in the appointment.
  • Example:[ { "name": "João Silva", "email": "joao.silva@example.com", "phone": "+5511999999999", "identification_code": "123.456.789-00", "identification_type": "br_cpf" } ]

start (required)

  • Description: Appointment start date and time.
  • Structure: Object with dateTime (ISO 8601 format).
  • Impact: Sets the appointment time.
  • Example:{ "dateTime": "2025-06-01T10:00:00Z" }

description (optional)

  • Description: Appointment description.
  • Restrictions: Minimum of 1 character.
  • Impact: Adds contextual information.
  • Example: “Routine consultation”

verify_limits (optional)

  • Description: Verifies the configured scheduling limits.
  • Impact: Ensures compliance with calendar rules if set to true.
  • Example: true

send_email (optional)

  • Description: Sends appointment confirmation email.
  • Impact: Notifies attendees if set to true.
  • Example: false

include_flows (optional)

  • Description: Includes the appointment in notification rules (if status is CONFIRMED).
  • Impact: Activates notification flows if set to true.
  • Example: false

account_slug (optional)

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

Note: The required fields are calendar_key, attendees, and start. The remaining fields are optional but recommended for greater control.

Basic Example:

{
  "status": "PENDING",
  "calendar_key": "1973125a-ab10-4000-8674-eef17b31e080",
  "attendees": [
    {
      "name": "João Silva",
      "email": "joao.silva@example.com"
    }
  ],
  "start": {
    "dateTime": "2025-06-01T10:00:00Z"
  }
}

Sending the Request to Create an Appointment

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

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

Request Configuration

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

cURL Request Example

curl -X POST https://eagenda.com.br/api/v3/appointments/ \
-H "accept: application/json" \
-H "Authorization: Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999" \
-H "Content-Type: application/json" \
-d '{
  "status": "PENDING",
  "calendar_key": "1973125a-ab10-4000-8674-eef17b31e080",
  "attendees": [
    {
      "name": "João Silva",
      "email": "joao.silva@example.com"
    }
  ],
  "start": {
    "dateTime": "2025-06-01T10:00:00Z"
  }
}'

Python Example (using requests)

import requests

url = "https://eagenda.com.br/api/v3/appointments/"
headers = {
    "accept": "application/json",
    "Authorization": "Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999",
    "Content-Type": "application/json"
}
data = {
    "status": "PENDING",
    "calendar_key": "1973125a-ab10-4000-8674-eef17b31e080",
    "attendees": [
        {
            "name": "João Silva",
            "email": "joao.silva@example.com"
        }
    ],
    "start": {
        "dateTime": "2025-06-01T10:00:00Z"
    }
}

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 appointment creation status. Check the following points:

  • HTTP status code:
    • 201 Created: Appointment successfully created.
    • 400 Bad Request: Error in the submitted data (check the JSON).
    • 401 Unauthorized: Invalid or missing token.
  • Response body: Contains details of the created appointment, such as:
{
  "appointment_key": "19730681-29a0-4000-8ddf-025c8f2d1401",
  "search_code": "A001",
  "status": "PENDING",
  "calendar": {
    "calendar_key": "1973125a-ab10-4000-8674-eef17b31e080",
    "calendar_name": "Agenda Principal"
  },
  "service_list": [],
  "tag_list": [],
  "attendees": [
    {
      "person_key": "19730681-29a0-4000-8584-d036c75a2f80",
      "name": "João Silva",
      "email": "joao.silva@example.com",
      "phone": null,
      "identification_code": null,
      "identification_type": null
    }
  ],
  "owner_user": null,
  "start": {
    "dateTime": "2025-06-01T10:00:00Z",
    "timeZone": "UTC"
  },
  "end": {
    "dateTime": "2025-06-01T10:30:00Z",
    "timeZone": "UTC"
  },
  "description": null,
  "questionnaires": [],
  "created_at": {
    "dateTime": "2025-06-01T09:58:00Z",
    "timeZone": "UTC"
  },
  "location": null,
  "conference_data": null,
  "account_slug": null
}

The appointment will be registered in the system, respecting the calendar settings and the provided data. Use the appointment_key to manage the appointment in subsequent requests.

Conclusion

With this tutorial, you learned how to create an appointment via the eAgenda API, configuring attendees, time slots, and other details efficiently. This integration is ideal for automating appointment creation, optimizing schedule management. For additional features such as listing available time slots or editing appointments, see the complete eAgenda API documentation.

Contact Us 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