/v1/me/calendar/availabilityGive it a guest list and a length, get back the first moments everybody is free. The account asking is always one of the party.
It sees what you see, and no more
This is not a free and busy service over the whole firm. A colleague whose
calendar is not shared with this account comes back in meta.people with
visible: false, and the slots say nothing about them. Sharing a calendar at
the busy level is what makes somebody schedulable without letting anybody read
their diary.
Working hours narrow it, each person's in their own timezone. Somebody who has never set any works Monday to Friday, nine until five. Appointments that last all day do not block: a holiday should and a "quarterly numbers due" should not, and there is no way to tell them apart.
Request
| Parameter | Description |
|---|---|
guests[] | Email addresses. Anyone who does not work here comes back as unknown |
minutes | How long the meeting is. Between 5 and 480, defaults to 60 |
from | ISO 8601, where to start looking. Defaults to now |
days | How far ahead. Between 1 and 30, defaults to 14 |
curl -G https://api.proppertrading.com/v1/me/calendar/availability \
-H "Authorization: Bearer ptat_9f2c1a44_3b8e7d2f5c9a1b4e6d8f0a2c4e6b8d1f" \
--data-urlencode "guests[][email protected]" \
--data-urlencode "minutes=30" \
--data-urlencode "days=7"
Response
{
"data": [
{
"object": "time_slot",
"starts_at": "2026-08-24T09:00:00+00:00",
"ends_at": "2026-08-24T09:30:00+00:00"
},
{
"object": "time_slot",
"starts_at": "2026-08-24T09:15:00+00:00",
"ends_at": "2026-08-24T09:45:00+00:00"
}
],
"meta": {
"request_id": "req_01kz4bkr1aj1gv63d8fv3133ey",
"people": [
{
"name": "Tom de Vries",
"email": "[email protected]",
"visible": true
}
]
}
}
Slots start on the quarter hour and overlap on purpose: 09:00 and 09:15 are two answers to the same question, not a mistake. At most six per day and twenty four in all, so a free Monday does not fill the list before Tuesday is reached.
An empty data means no moment in the window suits everybody. A shorter meeting
or a wider days is usually the answer.
Errors
| Status | Code | Meaning |
|---|---|---|
| 400 | validation_failed | A parameter was out of range. error.param names it |
| 400 | invalid_date | from was not ISO 8601 |
| 403 | insufficient_scope | This device does not hold calendar:read |
| 403 | calendar_not_permitted | The account may not open a calendar at all |