List Available Times

Overview

The eAgenda platform API allows you to list available times for scheduling, both for a specific day (/api/v3/available-date-times/) and for random times within a range (/api/v3/available-date-times/random/). This practical guide details how to configure an HTTP GET request to these endpoints, using 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: See the authentication section in the API documentation to configure the token correctly: https://eagenda.com.br/api/v3/documents/#overview.

Query Parameter Definition

Parameters for the /available-date-times/ Endpoint

This endpoint lists available times for a specific day. Below are the query-string parameters:

action_new_appointment (optional)

Description: Defines the action for the appointment.
Possible values:
- new: Available times without restrictions.
- client: Times considering client restrictions.
- waiting: Times with a waiting list.
- force: Squeeze into occupied time slots.
Impact: Filters times based on the desired action.
Example: new

calendar_key (required)

Description: Calendar UUID key.
Impact: Specifies the calendar to query times from.
How to obtain: Use the calendar listing endpoint (/api/v3/calendars/).
Example: 19730681-29d0-4000-88d0-caf575494780

day (required)

Description: Calendar day (YYYY-MM-DD format).
Impact: Filters available times for the specified day.
Example: 2025-06-01

is_manual (optional)

Description: Indicates whether the date was created manually.
Impact: Filters times created manually (true) or automatically (false).
Example: true

min_vacancies_available (optional)

Description: Minimum number of vacancies available per time slot.
Impact: Filters times with at least the specified number of vacancies.
Example: 1

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 times returned per page.
Example: 20

service_keys (optional)

Description: List of service UUID keys.
Impact: Filters available times for specific services.
How to obtain: Use the service listing endpoint (/api/v3/services/).
Example: [“19730681-2aa0-4000-84b6-2bc54b4ace01”]

Parameters for the /available-date-times/random/ Endpoint

This endpoint lists random available times within a range. Below are the query-string parameters:

calendar_key (required)

Description: Calendar UUID key.
Impact: Specifies the calendar to query times from.
How to obtain: Use the calendar listing endpoint (/api/v3/calendars/).
Example: 19730681-29d0-4000-88d0-caf575494780

end_date (optional)

Description: Appointment end date (ISO 8601 format).
Impact: Limits times up to the specified date.
Example: 2025-06-30T23:59:59Z

min_vacancies_available (optional)

Description: Minimum number of vacancies available per time slot.
Impact: Filters times with at least the specified number of vacancies.
Example: 1

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 times returned per page.
Example: 20

quantity (optional)

Description: Number of times to return.
Impact: Defines the number of random times returned.
Example: 5

service_keys (optional)

Description: List of service UUID keys.
Impact: Filters available times for specific services.
How to obtain: Use the service listing endpoint (/api/v3/services/).
Example: [“19730681-2aa0-4000-84b6-2bc54b4ace01”]

start_date (optional)

Description: Appointment start date (ISO 8601 format).
Impact: Limits times from the specified date onward.
Example: 2025-06-01T00:00:00Z

Note: For the /available-date-times/ endpoint, calendar_key and day are required. For /available-date-times/random/, only calendar_key is required. Other parameters are optional for greater flexibility.

Sending the Request to List Times

To list available times, send an HTTP GET request to one of the endpoints:

For a specific day: https://eagenda.com.br/api/v3/available-date-times/
For random times: https://eagenda.com.br/api/v3/available-date-times/random/

Request Configuration

Method: GET
Headers:
- accept: application/json
- Authorization: Bearer
Query-string: Filter parameters (e.g., ?calendar_key=19730681-29d0-4000-88d0-caf575494780&day=2025-06-01).

cURL Request Example

For /available-date-times/

curl -X GET "https://eagenda.com.br/api/v3/available-date-times/?calendar_key=19730681-29d0-4000-88d0-caf575494780&day=2025-06-01&action_new_appointment=new&min_vacancies_available=1" \
-H "accept: application/json" \
-H "Authorization: Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999"

For /available-date-times/random/

curl -X GET "https://eagenda.com.br/api/v3/available-date-times/random/?calendar_key=19730681-29d0-4000-88d0-caf575494780&start_date=2025-06-01T00:00:00Z&quantity=5" \
-H "accept: application/json" \
-H "Authorization: Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999"

Python Example (using requests)

For /available-date-times/

import requests

url = "https://eagenda.com.br/api/v3/available-date-times/"
headers = {
    "accept": "application/json",
    "Authorization": "Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999"
}
params = {
    "calendar_key": "19730681-29d0-4000-88d0-caf575494780",
    "day": "2025-06-01",
    "action_new_appointment": "new",
    "min_vacancies_available": 1
}

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

For /available-date-times/random/

import requests

url = "https://eagenda.com.br/api/v3/available-date-times/random/"
headers = {
    "accept": "application/json",
    "Authorization": "Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999"
}
params = {
    "calendar_key": "19730681-29d0-4000-88d0-caf575494780",
    "start_date": "2025-06-01T00:00:00Z",
    "quantity": 5
}

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 available times. Check the following:

HTTP status code:
- 200 OK: List of times returned successfully.
- 400 Bad Request: Error in the query parameters (check the formatting).
- 401 Unauthorized: Invalid or missing token.
Response body: Contains a paginated list of times, with details such as:{ "count": 1, "next": null, "previous": null, "results": [ { "calendar": { "calendar_key": "19730681-29d0-4000-88d0-caf575494780", "calendar_name": "Agenda Principal" }, "day": "2025-06-01", "start_date": "2025-06-01T08:00:00Z", "end_date": "2025-06-01T08:30:00Z", "booked": false, "blocked": false, "max_number_people": 10, "number_people": 0, "number_available": 10, "is_open": true } ] }

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

Conclusion

With this tutorial, you learned how to list available times for scheduling via the eAgenda API, using the /api/v3/available-date-times/ and /api/v3/available-date-times/random/ endpoints. This integration is ideal for automating time slot queries, making it easier to create appointments. For more features, such as creating calendars or appointments, 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