> ## Documentation Index
> Fetch the complete documentation index at: https://developers.nova.money/llms.txt
> Use this file to discover all available pages before exploring further.

# Companies API — Query Appointment Schedule Availability

> Query available appointment time slots for a Nova.Pay company on a specific date. Use this to populate a time picker in your checkout flow.

The Companies API lets you query scheduling availability for a company. Use it to populate a time picker in your checkout flow whenever appointment scheduling is required. All endpoints are relative to the base URL `https://pay.nova.money/api/v1`.

***

## List available schedules

Retrieve the available appointment time slots for a company on a specific date. The response is a list of `HH:MM` strings representing times that are open for booking.

```text theme={null}
GET /companies/{id}/available_schedules
```

### Path parameters

<ParamField path="id" type="integer" required>
  The numeric ID of the company whose scheduling availability you want to query.
</ParamField>

### Query parameters

<ParamField query="date" type="date">
  The date to check availability for, in `YYYY-MM-DD` format (e.g., `2024-09-15`).
</ParamField>

### Response

An array of available time slot strings in `HH:MM` format (24-hour clock).

An **empty array** is returned when any of the following conditions apply:

* No `date` or `id` parameter was provided.
* The requested date is in the past.
* The company has no schedule configured for the weekday of the requested date.

### Example request and response

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://pay.nova.money/api/v1/companies/5/available_schedules?date=2024-09-15"
  ```
</CodeGroup>

<CodeGroup>
  ```json Response — slots available theme={null}
  ["09:00", "10:30", "14:00", "16:30"]
  ```

  ```json Response — no slots available theme={null}
  []
  ```
</CodeGroup>

<Note>
  This endpoint is typically used when a checkout page has `require_scheduling: true` configured. Fetch available slots when the customer lands on the page, then render a time picker with the returned values so the customer can choose their preferred appointment time.
</Note>

Once the customer selects a time slot, combine it with the chosen date and pass the result as `scheduled_at` (ISO 8601 datetime) in your payment request body — for example:

<CodeGroup>
  ```json Passing scheduled_at in a payment request theme={null}
  {
    "scheduled_at": "2024-09-15T14:00:00-03:00",
    "customer": {
      "email": "jane.doe@example.com",
      "name": "Jane Doe",
      "phone": "11999998888"
    },
    "items": [
      { "product_id": 101, "quantity": 1 }
    ]
  }
  ```
</CodeGroup>

<Tip>
  Always re-fetch available slots just before the customer confirms their booking. Slots can be claimed by other customers in the time between your initial fetch and the final submission.
</Tip>


## Related topics

- [Webhooks API — Handle Payment Gateway Event Callbacks](/api-reference/webhooks.md)
- [Receive and Handle Payment Webhook Events in Nova.Pay](/guides/webhooks.md)
- [Payment Plans API — List and Retrieve Installment Options](/api-reference/payment-plans.md)
- [Checkout Pages API — List and Retrieve Checkout Pages](/api-reference/checkout-pages.md)
- [Order Lifecycle and Status Transitions in Nova.Pay](/concepts/orders-lifecycle.md)