Create a New Patient Appointment — POST /appointments

The Create Appointment endpoint lets you book a new appointment slot for a patient with a specific professional at your clinic. You must supply the patient and professional UUIDs, the start and end times in UTC, and optionally the appointment type and internal notes. By default, ByDoctor sends a WhatsApp confirmation to the patient immediately after the appointment is created — set notify_patient to false if you want to suppress this notification.

Request

POST https://api.bydoctor.com.br/v1/appointments Content-Type: application/json

string

required

The UUID of an existing patient in your clinic. You can find patient UUIDs via the Patients API.

string

required

The UUID of the professional who will conduct the appointment.

string

required

The appointment start time as an ISO 8601 UTC timestamp. Example: 2025-07-15T14:00:00Z.

string

required

The appointment end time as an ISO 8601 UTC timestamp. Must be strictly after starts_at.

string

default:"presencial"

The appointment modality. Accepted values: presencial (in-person) or teleconsulta (video call). When teleconsulta is set, a teleconsult_url is automatically generated and returned in the response.

string

Free-text notes visible to clinic staff. Not shared with the patient.

boolean

default:true

When true, ByDoctor sends a WhatsApp confirmation message to the patient’s registered phone number immediately after the appointment is created. This field is write-only and is not returned in responses.

Response Fields

string

Unique identifier for the newly created appointment (UUID).

string

The ID of the clinic that owns this appointment.

string

The ID of the patient linked to this appointment.

string

The ID of the professional assigned to this appointment.

string

Appointment start time in ISO 8601 UTC format.

string

Appointment end time in ISO 8601 UTC format.

string

Appointment type: presencial or teleconsulta.

string

Initial status of the appointment. Always scheduled on creation.

string

Notes attached to the appointment. null if not provided.

string

Initial payment status. Always pending on creation.

string

Auto-generated video room URL. Present only when type is teleconsulta. null for presencial appointments.

string

Timestamp when the appointment was created (ISO 8601 UTC).

string

Timestamp of the last update. Equal to created_at on a fresh record.

If the requested time slot is already occupied by another appointment for the same professional, the API returns a 409 Conflict error. Fetch the professional’s schedule first to identify available windows before attempting to create.

Example Request

curl --request POST \
  --url "https://api.bydoctor.com.br/v1/appointments" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "patient_id": "pat_01HX5678EFGH",
    "professional_id": "pro_01HX9012IJKL",
    "starts_at": "2025-07-15T14:00:00Z",
    "ends_at": "2025-07-15T14:30:00Z",
    "type": "teleconsulta",
    "notes": "Patient requested video call due to travel.",
    "notify_patient": true
  }'

Example Response (201 Created)

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "clinic_id": "clinic_01HX1234ABCD",
  "patient_id": "pat_01HX5678EFGH",
  "professional_id": "pro_01HX9012IJKL",
  "starts_at": "2025-07-15T14:00:00Z",
  "ends_at": "2025-07-15T14:30:00Z",
  "type": "teleconsulta",
  "status": "scheduled",
  "notes": "Patient requested video call due to travel.",
  "payment_status": "pending",
  "teleconsult_url": "https://meet.bydoctor.com.br/room/c3d4e5f6",
  "created_at": "2025-07-01T10:15:30Z",
  "updated_at": "2025-07-01T10:15:30Z"
}

Error Responses

400 Bad Request — One or more required fields are missing or malformed.

{
  "error": {
    "code": "validation_error",
    "message": "The field 'starts_at' is required and must be a valid ISO 8601 timestamp.",
    "field": "starts_at"
  }
}

401 Unauthorized — Your API key is missing or invalid.

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key. Provide a valid Bearer token in the Authorization header."
  }
}

404 Not Found — The specified patient or professional does not exist in your clinic.

{
  "error": {
    "code": "not_found",
    "message": "No patient found with id 'pat_01HX5678EFGH' in your clinic."
  }
}

409 Conflict — The professional already has an appointment overlapping the requested time slot.

{
  "error": {
    "code": "time_slot_conflict",
    "message": "Professional 'pro_01HX9012IJKL' already has an appointment between 2025-07-15T14:00:00Z and 2025-07-15T14:30:00Z.",
    "conflicting_appointment_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

422 Unprocessable Entity — The request body is structurally valid but logically inconsistent (for example, ends_at is before or equal to starts_at).

{
  "error": {
    "code": "unprocessable_entity",
    "message": "'ends_at' must be strictly after 'starts_at'."
  }
}

Appointments

Patients

Schedules & Availability

Payments

Webhooks

Create a New Patient Appointment — POST /appointments

Request

Response Fields

Example Request

Example Response (201 Created)

Error Responses

​Request

​Response Fields

​Example Request

​Example Response (201 Created)

​Error Responses

Request

Response Fields

Example Request

Example Response (201 Created)

Error Responses