> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bydoctor.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# ByDoctor API Quickstart: Your First API Calls in Minutes

> Create a ByDoctor account, generate an API key, and make your first live API calls — listing appointments, creating a booking, and setting up a webhook.

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.

<Steps>
  <Step title="Create a ByDoctor account">
    If you don't already have an account, sign up for free at [app.bydoctor.com.br/auth/sign-up](https://www.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.

    <Info>
      The account you create during sign-up is automatically assigned the **Admin** role, which is required to generate API keys.
    </Info>
  </Step>

  <Step title="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:

    ```bash theme={null}
    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.
  </Step>

  <Step title="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.

    <CodeGroup>
      ```bash cURL theme={null}
      curl https://api.bydoctor.com.br/v1/appointments \
        -H "Authorization: Bearer $BYDOCTOR_API_KEY"
      ```

      ```javascript JavaScript (fetch) theme={null}
      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);
      ```
    </CodeGroup>

    A successful response looks like this:

    ```json theme={null}
    {
      "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
      }
    }
    ```

    <Tip>
      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`.
    </Tip>
  </Step>

  <Step title="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.

    <CodeGroup>
      ```bash cURL theme={null}
      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"
        }'
      ```

      ```javascript JavaScript (fetch) theme={null}
      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);
      ```
    </CodeGroup>

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

    ```json theme={null}
    {
      "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            |
  </Step>

  <Step title="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.

    <CodeGroup>
      ```bash cURL theme={null}
      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"
        }'
      ```

      ```javascript JavaScript (fetch) theme={null}
      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);
      ```
    </CodeGroup>

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

    ```json theme={null}
    {
      "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.

    <Warning>
      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.
    </Warning>
  </Step>
</Steps>

## Next Steps

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

<CardGroup cols={2}>
  <Card title="Explore the Data Model" icon="database" href="/concepts/data-model">
    Understand how clinics, professionals, patients, and appointments relate to each other in ByDoctor's multi-tenant data structure.
  </Card>

  <Card title="Set Up Webhooks" icon="bell" href="/webhooks/overview">
    Learn every available event type, how to validate webhook signatures, and best practices for building reliable event consumers.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/appointments/list">
    Browse the full reference for the Appointments resource — all query parameters, request body fields, and response schemas.
  </Card>

  <Card title="Scheduling Integration Guide" icon="calendar" href="/guides/scheduling-integration">
    Follow a step-by-step guide to building a two-way sync between ByDoctor's calendar and an external scheduling system.
  </Card>
</CardGroup>