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 section to understand how to add a user and one or more accounts/calendars.

Booking profile

At the heart of the Group Booking API lies a booking/availability profile for a group of users. 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 endpoint:

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
}'

Note, this endpoint requires app-level authentication (ClientId+Secret)

You can insert variables like {{name}}, {{comments}} 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:

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
}'

Associate users with the profile using attachUsers endpoint


curl -u ClientId:Secret \
    -X POST https://api.aurinko.io/v1/book/group/profiles/{id}/attachUsers \
    -d '{ "users": [

    {
      "id": "{aurinko-user-id}",
      "accounts": [accId1,accId2,...]
    },
  ]
}'


Availability

Once a booking profile is created, and its users are defined the availability endpoint can be used to query the users availability for the types of meetings defined in the profile and within the specified work hours.

curl -X GET https://api.aurinko.io/v1/book/{aurinkoClientId}/{profileName}/meeting

This endpoint produces information that can be used to build a public calendar page like Aurinko’s Calendar Page.

userIds show the users that are available for a given time slot.

Note, that this endpoint does not require any authentication.

{
    "items": [
        {
            "start": "2024-01-27T14:00:00Z",
            "end": "2024-01-27T14:45:00Z",

            "userIds": [uid1,uid2,uid3,...]        },...
    ],
    "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 additionalFields array contains the {{variables}} 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.

When dealing with larger groups (over 10 users) request next page with offset query parameter. The same time slots will be returned but for additional userIds.

Schedule

Book a meeting by sending json payload to the /book/{auringoClientId}/{profileName}/meeting endpoint and specify userIds that you received earlier for the specified time slot:

curl -X POST {aurinkoClientId}/{profileName}/meeting \
    -d '{
    "time": {
        "start": "2024-01-27T14:00:00Z",
        "end": "2024-01-27T14:45:00Z"
    },
    "userIds": [uid1,uid2,...],
    "name": "string",
    "email": "string",
    "substitutionData": {
        "property1": "string",
        "property2": "string"
    }
}'

A new event will be created according to the profile on the primary calendar of one specified user (the first user that still has the time slot available) and the person specified by the email and name fields will be invited to the event.