Documentation / Recursos Avançados
Recursos Avançados

How to List and Filter Appointments Via API

List and Filter Appointments

Overview

The eAgenda platform API allows you to list and filter appointments programmatically, enabling you to query details such as status, services, dates, and attendees. This practical guide explains how to configure an HTTP GET request to the /api/v3/appointments/ endpoint with query parameters to filter results. 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 accept: application/json.

Tip: Refer to the eAgenda authentication documentation to configure the token correctly.

Query Parameter Definition

To list or filter appointments, send parameters in the query string of the GET request. All parameters are optional, allowing flexibility in your queries. Below are the available parameters:

account_slug (optional)

  • Description: Account or sub-account slug.
  • Impact: Filters appointments for a specific account.
  • How to obtain: Use the eAgenda account listing endpoint.
  • Example: my-account

calendar_key (optional)

  • Description: UUID key of the calendar.
  • Impact: Filters appointments for a specific calendar.
  • How to obtain: Use the calendar listing endpoint.
  • Example: 550e8400-e29b-41d4-a716-446655440000

client_key (optional)

  • Description: UUID key of the client.
  • Impact: Filters appointments associated with a specific client.
  • How to obtain: Use the client listing endpoint.
  • Example: 123e4567-e89b-12d3-a456-426614174000

created_at (optional)

  • Description: Appointment creation date (ISO 8601 format).
  • Impact: Filters appointments created on a specific date.
  • Example: 2025-06-01T10:00:00Z

email (optional)

  • Description: Attendee email.
  • Impact: Filters appointments associated with an email address.
  • Example: joao.silva@example.com

end_date (optional)

  • Description: Maximum appointment start date (ISO 8601 format).
  • Impact: Filters appointments that start before this date.
  • Example: 2025-06-30T23:59:59Z

identification_code (optional)

  • Description: Attendee tax identification number (e.g., CPF).
  • Impact: Filters appointments by identification document.
  • Example: 123.456.789-00

is_cancelled (optional)

  • Description: Indicates whether the appointment was cancelled.
  • Impact: Filters cancelled appointments (true) or active ones (false).
  • Example: true

name (optional)

  • Description: Attendee name.
  • Impact: Filters appointments by person name.
  • Example: João Silva

owner_user (optional)

  • Description: Email of the user responsible for the appointment.
  • Impact: Filters appointments by responsible user.
  • Example: responsible@example.com

page (optional)

  • Description: Page number in paginated results.
  • Impact: Navigates through result pages.
  • Example: 1

page_size (optional)

  • Description: Number of results per page.
  • Impact: Defines the number of appointments returned per page.
  • Example: 20

phone (optional)

  • Description: Attendee phone number (E.164 format).
  • Impact: Filters appointments by phone number.
  • Example: +5511999999999

service_keys (optional)

  • Description: List of service UUID keys.
  • Impact: Filters appointments associated with specific services.
  • How to obtain: Use the service listing endpoint.
  • Example: [“19730681-2aa0-4000-84b6-2bc54b4ace01”]

start_date (optional)

  • Description: Minimum appointment start date (ISO 8601 format).
  • Impact: Filters appointments that start after this date.
  • Example: 2025-06-01T00:00:00Z

status (optional)

  • Description: Appointment status.
  • Possible values: ATTENDED, CANCELED, CANCELED_CLIENT, CANCELED_GOOGLE, CONFIRMED, IN_PROGRESS, NO_SHOW, PENDING, PENDING_COMPANIONS, PENDING_FORM, PENDING_PAYMENT.
  • Impact: Filters appointments by status.
  • Example: CONFIRMED

tag_keys (optional)

  • Description: List of tag UUID keys.
  • Impact: Filters appointments associated with specific tags.
  • How to obtain: Use the tag listing endpoint.
  • Example: [“a1b2c3d4-e5f6-7890-1234-567890abcdef”]

Note: All parameters are optional. Combine them to filter for specific results.

Sending the Request to List/Filter Appointments

To list or filter appointments, send an HTTP GET request to the endpoint:

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

Request Configuration

  • Method: GET
  • Headers:
    • accept: application/json
    • Authorization: Bearer
  • Query string: Filter parameters (e.g., ?account_slug=my-account&status=CONFIRMED).

cURL Request Example

curl -X GET "https://eagenda.com.br/api/v3/appointments/?account_slug=minha-conta&status=CONFIRMED&start_date=2025-06-01T00:00:00Z" \
-H "accept: application/json" \
-H "Authorization: Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999"

Python Example (using requests)

import requests

url = "https://eagenda.com.br/api/v3/appointments/"
headers = {
    "accept": "application/json",
    "Authorization": "Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999"
}
params = {
    "account_slug": "minha-conta",
    "status": "CONFIRMED",
    "start_date": "2025-06-01T00:00:00Z"
}

response = requests.get(url, headers=headers, params=params)
print(response.status_code)
print(response.json())

Response Verification

The API will return a response with the query status and the filtered appointments. Check the following points:

  • HTTP status code:
    • 200 OK: Appointment list returned successfully.
    • 400 Bad Request: Error in query parameters (check the formatting).
    • 401 Unauthorized: Invalid or missing token.
  • Response body: Contains a paginated list of appointments, with details such as:{ "count": 1, "next": null, "previous": null, "results": [ { "appointment_key": "550e8400-e29b-41d4-a716-446655440000", "search_code": "A001", "status": "CONFIRMED", "calendar": { "calendar_key": "123e4567-e89b-12d3-a456-426614174000", "calendar_name": "Agenda Principal" }, "service_list": [ { "service_key": "19730681-2aa0-4000-84b6-2bc54b4ace01", "service_name": "Consulta Médica" } ], "tag_list": [ { "tag_key": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "label": "Urgente" } ], "attendees": [ { "person_key": "789abcde-f123-4567-89ab-cdef12345678", "name": "João Silva", "email": "joao.silva@example.com", "phone": "+5511999999999", "identification_code": "123.456.789-00", "identification_type": "br_cpf" } ], "owner_user": { "email": "responsavel@example.com", "full_name": "Maria Souza" }, "start": { "dateTime": "2025-06-01T10:00:00Z", "timeZone": "America/Sao_Paulo" }, "end": { "dateTime": "2025-06-01T10:30:00Z", "timeZone": "America/Sao_Paulo" }, "description": "Consulta de rotina", "location": "Clínica Central", "conference_data": { "provider": "meet", "url": "https://meet.google.com/abc-defg-hij", "label": "Reunião Virtual" }, "account_slug": "minha-conta" } ] }

The returned appointments respect the applied filters. Use the next and previous fields to navigate through result pages.

Conclusion

With this tutorial, you learned how to list and filter appointments via the eAgenda API, using query parameters to obtain specific results. This integration is ideal for managing appointments, monitoring statuses, and integrating with external systems. For additional features such as creating 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