# Group Booking API

The Group Booking API is a powerful tool designed to facilitate the automated scheduling of meetings within a group. It enables developers to gather availability information from multiple user calendars and find time slots when at least one user is available.

The API is built on top of the Aurinko User concept. Please see [User OAuth Flow](https://docs.aurinko.io/authentication/oauth-flow) section to understand how to add a user and one or more accounts/calendars.

### Booking profile

***

At the heart of the [Group Booking API](https://apirefs.aurinko.io/#tag/GroupBooking) lies a booking/availability profile for a set of accounts or groups of accounts. 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/group/profiles](https://apirefs.aurinko.io/#tag/GroupBooking/operation/createGroupBooking) endpoint:

```bash
curl -u ClientId:Secret
    -X POST https://api.aurinko.io/v1/book/group/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
}'  
```

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

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 additionalFields of the availability endpoint below).

*Use PATCH request to update existing profiles*:

```bash
curl -u ClientId:Secret
    -X PATCH https://api.aurinko.io/v1/book/group/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
}'
```

To associate accounts with a booking profile, use the [attachAccounts endpoint](https://apirefs.aurinko.io/#tag/GroupBooking/operation/attachAccountsGroupBooking):

```bash
curl -u ClientId:Secret
    -X POST https://api.aurinko.io/v1/book/group/profiles/{id}/attachAccounts
    -d '{ "accountIds": [accId1, accId2]
}'
```

To associate groups of accounts with a booking profile, use the [attachGroups endpoint](https://apirefs.aurinko.io/#tag/GroupBooking/operation/attachGroupsBooking):

```bash
curl -u ClientId:Secret
    -X POST https://api.aurinko.io/v1/book/group/profiles/{id}/attachGroups
    -d '{ "groups": [
    
    { "extId": "groupExtId1", 
                "accountIds": [accId1, accId2], 
                "required": "one" 
    },
                
    { "extId": "groupExtId2", 
                "accountIds": [accId3, accId4], 
                "required": "all" 
    }
  ] 
}'
```

The `required` field in the request body determines how the booking should handle group availability:

* `"one"` – The meeting can be scheduled if **at least one** member of the group is available.
* `"all"` – The meeting can be scheduled **only if all** members of the group are available.

### Availability

***

Once a booking profile is created, and its accounts/groups are defined the [availability endpoint](https://apirefs.aurinko.io/#tag/Availability/operation/getMeetingTimes) can be used to query the members 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/group/profiles/{id}/meeting?required=one|all`</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).

<mark style="color:red;">`groupXids`</mark> indicate which groups are available for a given time slot.

<mark style="color:red;">`accountIds`</mark> indicate which accounts are available for a given time slot.

{% 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",

            "groupXids": ["group1", "group2", "group3"],
            "accountIds": [id1, id2, id3, ...]        
        },
        ...
        
    ],
    "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
        },
        ...
        
    ]
}
```

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.

{% hint style="info" %}
**Note:** When dealing with larger groups (over 10 users) request next page with <mark style="color:red;">`offset`</mark> query parameter. The same time slots will be returned but for additional userIds.
{% endhint %}

### Schedule

***

Book a meeting by sending json payload to the <mark style="color:red;">`book/group/profiles/{id}/meeting?required=one|all`</mark> endpoint and specify groupXids and/or accountIds that you received earlier for the specified time slot:

```bash
curl -X POST {id}/meeting
    -d '{
    "time": {
        "start": "2024-01-27T14:00:00Z",
        "end": "2024-01-27T14:45:00Z"
    },
    "groupXids": ["group1", "group2", "group3"],
    "accountIds": [id1, id2, id3, ...],
    "name": "string",
    "email": "string",
    "substitutionData": {
        "property1": "string",
        "property2": "string"
    }
}'  
```

Specify the accountIds or groupXids that you received from the availability endpoint.

A new event will be created based on the profile:

* If an account is specified, the event will be scheduled in its primary calendar.
* If a group is specified, the event will be scheduled in the primary calendar of an available account within that group.

In both cases, the person specified in the <mark style="color:red;">`email`</mark> and <mark style="color:red;">`name`</mark> fields will be invited to the event. In the '?required=all' mode also all specified accounts will be invited.