# Booking API

## Aurinko Booking API

***

The Booking API is a powerful tool designed to facilitate the automated scheduling of meetings for one calendar. It enables developers to gather availability information from a calendar and find time slots when the calendar owner is available.

The API is built on top of the Aurinko Account concept. Please see [Account OAuth Flow](https://docs.aurinko.io/authentication/oauth-flow) section to understand how to add an account and get access to its calendars.

### Booking profile

***

At the heart of the [Booking API](https://apirefs.aurinko.io/#tag/Booking/operation/create) lies a booking/availability profile. This profile consists of a set of properties that describe calendar availability and the types of meetings that can be booked. It includes the following information:

1. Work hours
2. Meeting duration
3. Meeting subject
4. Meeting description
5. Meeting teleconference link
6. Meeting location
7. Profile scheduler link
8. Profile active period
9. And more...

To create a new booking profile POST json payload to the [/book/profiles](https://apirefs.aurinko.io/#tag/Booking/operation/create) endpoint:

```shell
curl -H 'Authorization: Bearer <access token>'
    -X POST https://api.aurinko.io/v1/book/account/profiles
    -d '{
        "id": 1,
        "name": "aurinkoDemo",
        "durationMinutes": 30,
        "availabilityStep": 15,
        "timeAvailableFor": "30D",
        "subject": "Aurinko Demo",
        "description": "A conference call with Aurinko.",
        "location": "Teleconference",
        "workHours": {
            "timezone": "Americas/New\_York",
            "daySchedules": [
                {
                    "dayOfWeek": "monday",
                    "workingIntervals": [{"start": "14:15:22Z","end": "14:15:22Z"},...]
                },
                ...
                
            ],
        },
        "context": "string",
        "startConference": true
}'  
```

You can insert variables like <mark style="color:red;">`{{name}}`</mark>, <mark style="color:red;">`{{comments}}`</mark> in the meeting description text. They will be passed to a scheduling widget to be filled by an end user booking a meeting (see <mark style="color:red;">`additionalFields`</mark> of the availability endpoint below).\
You can also use the <mark style="color:red;">`{{rescheduleToken}}`</mark> variable, which allows a client to reschedule an already booked event without requiring authentication or access to the original calendar provider.

*Use PATCH request to update existing profiles*:

```bash
curl -H 'Authorization: Bearer <access token>'
    -X PATCH https://api.aurinko.io/v1/book/account/profiles/{id}
    -d '{
        "name": "aurinkoDemo",
        "durationMinutes": 30,
        "availabilityStep": 15,
        "timeAvailableFor": "30D",
        "subject": "Aurinko Demo",
        "description": "My new event description",
        "location": "Google Hangout",
        "context": "string",
        "startConference": true
}'  
```

### Availability

***

Once a booking profile is created, the [Booking API](https://apirefs.aurinko.io/#tag/Availability/operation/getMeetingTimes) can be used to query a user's availability for the types of meetings defined in the profile and within the specified work hours. ) can be used to query a user's availability for the types of meetings defined in the profile and within the specified work hours.

<mark style="color:red;">`curl -X GET`</mark> \ <mark style="color:red;">`https://api.aurinko.io/v1/book/account/profiles/{id}/meeting`</mark>

This endpoint produces information that can be used to build a public calendar page like [Aurinko's Calendar Page](https://docs.aurinko.io/scheduling/calendar-booking-page).

{% hint style="info" %}
**Note:** this endpoint requires app-level authentication (ClientId+Secret)
{% endhint %}

```json
{
    "items": [
        {
            "start": "2024-01-27T14:00:00Z",
            "end": "2024-01-27T14:45:00Z"
        },...
    ],
    "startTime": "2024-01-01T00:00:00Z",
    "endTime": "2024-04-01T00:00:00Z",
    "durationMinutes": 45,
    "availabilityStep": 15,
    "subject": "Aurinko Demo",
    "primaryColor":"#303030",
    "secondaryColor":"#30A9EE",
    "additionalFields": [
        {
            "name":"comment",
            "type":"text",
            "default": null
        },
        ...
        
    ]
}
```

### Schedule

***

The <mark style="color:red;">`additionalFields`</mark> array contains the <mark style="color:red;">`{{variables}}`</mark> that you specified in the meeting description text. If you're building your own scheduling widget it needs to ask the end user for those inputs. Booking a meeting will require the fields that don't specify defaults.

Book a meeting by sending json payload to the \ <mark style="color:red;">`book/account/profiles/{id}/meeting`</mark> endpoint:

```bash
curl -X POST {id}/meeting
    -d '{
    "time": {
        "start": "2024-01-27T14:00:00Z",
        "end": "2024-01-27T14:45:00Z"
    },
    "name": "string",
    "email": "string",
    "substitutionData": {
        "property1": "string",
        "property2": "string"
    }
}'
```

A new event will be created on the calendar associated with the booking profile and the person specified by the email and name fields will be invited to the event.