ByDoctor API Quickstart: Your First API Calls in Minutes

This quickstart walks you through the end-to-end flow of connecting to the ByDoctor API for the first time. By the end you will have a working API key, a list of appointments, a newly created booking, and an active webhook subscription — all in under five minutes.

Create a ByDoctor account

If you don’t already have an account, sign up for free at app.bydoctor.com.br/auth/sign-up. Complete the clinic onboarding flow to provision your tenant. You need an active clinic account before you can issue API keys or access any data.

The account you create during sign-up is automatically assigned the Admin role, which is required to generate API keys.

Generate your API key

In your ByDoctor dashboard, navigate to Settings → API and click New API Key. Name it something descriptive like quickstart-test, select the read and write scopes, and click Create.Copy the key immediately — it is shown only once. Store it as an environment variable for the commands below:

export BYDOCTOR_API_KEY="your_api_key_here"

All subsequent examples read from this variable so you never have to paste the key directly into a command.

List your appointments

Fetch the list of appointments for your clinic with a GET request to /appointments. The response is a paginated array of appointment objects.

curl https://api.bydoctor.com.br/v1/appointments \
  -H "Authorization: Bearer $BYDOCTOR_API_KEY"

const response = await fetch('https://api.bydoctor.com.br/v1/appointments', {
  headers: {
    'Authorization': `Bearer ${process.env.BYDOCTOR_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

A successful response looks like this:

{
  "data": [
    {
      "id": "apt_01hx9k2mzf3v8nqp4c7yw6b0e",
      "clinic_id": "cln_01hx9j0abt2r5npq3c6vw5a9d",
      "patient_id": "pat_01hx9k1lye4u7mrq2c5vv4z8c",
      "professional_id": "pro_01hx9k0kxd3t6lop1c4uu3y7b",
      "starts_at": "2024-08-15T09:00:00-03:00",
      "ends_at": "2024-08-15T09:30:00-03:00",
      "type": "presencial",
      "status": "confirmed",
      "notes": "Follow-up consultation"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 20
  }
}

Use the query parameters starts_at and ends_at to filter appointments by date range, and professional_id to scope results to a specific doctor. For example: GET /appointments?starts_at=2024-08-01&ends_at=2024-08-31.

Create your first appointment

Send a POST request to /appointments with the required fields. The starts_at and ends_at fields must be ISO 8601 timestamps with a timezone offset.

curl -X POST https://api.bydoctor.com.br/v1/appointments \
  -H "Authorization: Bearer $BYDOCTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_id": "pat_01hx9k1lye4u7mrq2c5vv4z8c",
    "professional_id": "pro_01hx9k0kxd3t6lop1c4uu3y7b",
    "starts_at": "2024-08-20T14:00:00-03:00",
    "ends_at": "2024-08-20T14:30:00-03:00",
    "type": "teleconsulta",
    "notes": "Initial teleconsultation for new patient"
  }'

const response = await fetch('https://api.bydoctor.com.br/v1/appointments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.BYDOCTOR_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    patient_id: 'pat_01hx9k1lye4u7mrq2c5vv4z8c',
    professional_id: 'pro_01hx9k0kxd3t6lop1c4uu3y7b',
    starts_at: '2024-08-20T14:00:00-03:00',
    ends_at: '2024-08-20T14:30:00-03:00',
    type: 'teleconsulta',
    notes: 'Initial teleconsultation for new patient'
  })
});

const appointment = await response.json();
console.log(appointment);

On success, the API returns 201 Created with the full appointment object:

{
  "data": {
    "id": "apt_01hx9m3nag5w9orq5d8xx7c1f",
    "clinic_id": "cln_01hx9j0abt2r5npq3c6vw5a9d",
    "patient_id": "pat_01hx9k1lye4u7mrq2c5vv4z8c",
    "professional_id": "pro_01hx9k0kxd3t6lop1c4uu3y7b",
    "starts_at": "2024-08-20T14:00:00-03:00",
    "ends_at": "2024-08-20T14:30:00-03:00",
    "type": "teleconsulta",
    "status": "scheduled",
    "notes": "Initial teleconsultation for new patient",
    "created_at": "2024-08-01T10:23:45-03:00",
    "updated_at": "2024-08-01T10:23:45-03:00"
  }
}

The status field starts as "scheduled" when you create an appointment programmatically. The lifecycle values are:

Status	Meaning
`scheduled`	Booked, awaiting confirmation
`confirmed`	Confirmed by the clinic or patient
`cancelled`	Cancelled before the appointment time
`completed`	The appointment took place
`no_show`	The patient did not attend

Set up a webhook

Register a webhook endpoint to receive real-time notifications whenever an appointment is created. Send a POST request to /webhooks with your listener URL and the events you want to subscribe to.

curl -X POST https://api.bydoctor.com.br/v1/webhooks \
  -H "Authorization: Bearer $BYDOCTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/webhooks/bydoctor",
    "events": ["appointment.created"],
    "description": "Notify our scheduling service of new bookings"
  }'

const response = await fetch('https://api.bydoctor.com.br/v1/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.BYDOCTOR_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://your-app.example.com/webhooks/bydoctor',
    events: ['appointment.created'],
    description: 'Notify our scheduling service of new bookings'
  })
});

const webhook = await response.json();
console.log(webhook);

The API responds with 201 Created and your new webhook registration:

{
  "data": {
    "id": "wh_01hx9n4obh6x0psq6e9yy8d2g",
    "clinic_id": "cln_01hx9j0abt2r5npq3c6vw5a9d",
    "url": "https://your-app.example.com/webhooks/bydoctor",
    "events": ["appointment.created"],
    "description": "Notify our scheduling service of new bookings",
    "secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "active": true,
    "created_at": "2024-08-01T10:30:00-03:00"
  }
}

From now on, ByDoctor will send a signed POST request to your URL each time a new appointment is created. Use the secret field to verify the webhook signature and confirm that payloads originate from ByDoctor.

Store the webhook secret securely. ByDoctor includes a signature in the X-ByDoctor-Signature header of every delivery — always validate it before processing the payload.

Next Steps

You’ve made your first API calls and have a live webhook running. Explore the rest of the documentation to go deeper.

Explore the Data Model

Understand how clinics, professionals, patients, and appointments relate to each other in ByDoctor’s multi-tenant data structure.

Set Up Webhooks

Learn every available event type, how to validate webhook signatures, and best practices for building reliable event consumers.

API Reference

Browse the full reference for the Appointments resource — all query parameters, request body fields, and response schemas.

Scheduling Integration Guide

Follow a step-by-step guide to building a two-way sync between ByDoctor’s calendar and an external scheduling system.

Getting Started

Core Concepts

Webhooks

Guides

ByDoctor API Quickstart: Your First API Calls in Minutes

Next Steps

Explore the Data Model

Set Up Webhooks

API Reference

Scheduling Integration Guide

​Next Steps

Explore the Data Model

Set Up Webhooks

API Reference

Scheduling Integration Guide

Next Steps