Vivocalendar

Menu
Get Started

Getting started with the Vivocalendar API

Put your data to work so you can accomplish tasks quicker

API v2: Our current, actively maintained API. The Vivocalendar API v2 is REST-based and has predictable resource-oriented URLs. It uses JSON for request and response bodies and standard HTTP methods, authentication, and response codes.

Embed API: Our simpler, easy-to-use API that lets you add a Vivocalendar landing or booking page to your website.

Webhook API: Our friendly, lightweight API that lets you automatically receive Vivocalendar data with webhook subscriptions anytime invitees schedule, cancel, or reschedule a meeting.Build integrated apps for your team or customers

Authenticating requests

The Vivomeetings API v2 uses personal access tokens and OAuth 2.0 to authenticate requests. Choose either depending on who’s using the application you’re integrating with Vivocalendar.

  • If you’re integrating an internal application that only your team will use, authenticate with personal access tokens.
  • If you’re integrating a public application that many Vivocalendar users will use, authenticate with OAuth.

To see specific examples of when you might choose either authentication method, see when to choose between personal access tokens and OAuth 2.0.

Review your API and webhook permissions.

Access to the Vivocalendar API is determined by your subscription and user role in Vivocalendar, while access to webhooks is reserved for members on paid premium subscriptions and above. If your user role is insufficient, some HTTP methods, including those that access organization-wide Vivocalendar data, may not be available to you or others because of insufficient user privileges.

Accomplish tasks with the Bookafy API

See the articles below to help you get started with the Vivocalendar API for specific use cases you may have. To access and use Vivocalendar data, you’ll need to authenticate with the Vivocalendar API to retrieve your personal access token or OAuth token.

Sharing the scheduling pages of team members in your organization

Enhance your productivity when you use these guides to access the scheduling links of team members in your Vivocalendar organization or add Vivocalendar to your website for easy scheduling.

Working with webhooks to analyze data or trigger automations

Put your data to work when you use these guides to receive, understand, and report on Vivocalendar data when it arrives at an endpoint you specify.

Bridging the gap between Bookafy and your app

Provide a seamless experience when you help users of your app create new Vivocalendar accounts without ever leaving it. When you want to enhance their experience further, access and use Vivocalendar data on their behalf so they can focus on scheduling.

 

Trigger automation with other apps when invitees schedule, cancel, or reschedule events

Our webhook subscription will inform you when invitees book, cancel, or reschedule events. While the process is completely manual, you can use the values within the webhook payload to trigger follow up actions in the internal or custom-built apps you or your team use.

If you want to trigger automations without any development work, learn more about our integration with Zapier and Make.com, which connects Vivocalendar to apps you use daily.

  • When an event is scheduled, the invitee.created webhook is triggered.

  • When an event is canceled, the invitee.canceled webhook is triggered.

  • When an event is rescheduled, both the invitee.created and invitee.canceled webhooks are triggered.

To learn more about creating a webhook subscription, see receive scheduled event data in real time with webhook subscriptions.

Webhook payload values

To create your own follow up actions, use the values located within the webhook payload. Some that may be helpful include:

The event value

The event value identifies which payload was triggered as a result of the meeting being scheduled or canceled:

  • "event": "invitee.created" is triggered when an event is scheduled

  • "event": "invitee.canceled" is triggered when an event is canceled

The status value

The status value identifies if the invitee is attending or not attending the scheduled event

  • "status": "active" indicates that the invitee will attend the scheduled event

  • "status": "canceled" indicates that the invitee will not attend the scheduled event

The canceled value

The canceled value identifies if the event was canceled

  • "canceled": false indicates that the event has not been canceled

  • "canceled": true indicates that the event has been canceled

    • The canceled_by value identifies who, either the Calendly user or invitee, canceled the meeting

      • The reason value (if provided by the canceler) lists the textual response the canceler entered when canceling the event

The rescheduled value

The rescheduled value identifies if the event has been rescheduled

  • "rescheduled": true indicates the event has been rescheduled

  • "rescheduled": false indicates the event has not been rescheduled

Working with webhooks to analyze data or trigger automation

Put your data to work when you use these guides to receive, understand, and report on Vivocalendar data when it arrives at an endpoint you specify.

 

How to display the scheduling page for users of your app

First, you can embed our booking application within your website, without the API. We offer button code and and Iframe, both can be found in the integrations page. You can display the scheduling page for users of your app when you initialize one of three embed types based on information from the API such as the scheduling page link. To do this, you’ll need to generate an OAuth or personal access token for either public or private use, respectively.

To display the landing page of a specific user

  1. To display the current user’s landing page link, make a call /users/me to retrieve current user’s details. The landing page link can be found in the scheduling_url property. Proceed to step 4.

  2. To retrieve a specific user’s landing page link in an organization, use a personal access token generated by an admin or owner, then make a call to /organization_memberships including the organization query parameter in your request to get a list of users in the organization. Each returned user will have a scheduling_url property which contains the landing page link. Proceed to step 4

  3. To display the event scheduling page of a specific user, make a call to /event_types to get a list of event types associated with a user or an organization. The event type’s link can be found in the scheduling_url property. Proceed to step 4

  4. To use the link to initialize an embed, replace the myLink variable with the landing page link or event type link found in the scheduling_url property.

    1. To initilize an inline embed, use vivocalendar.initInlineWidget({url: myLink});

    2. To initialize a pop-up embed, use vivocalendar.initPopupWidget({url: myLink});

    3. to intialize a pop-up text embed, use vivocalendarinitBadgeWidget({ url: myLink, text: 'Schedule time with me', color: '#006bff', textColor: '#ffffff', branding: true });
      Note: The pop-up widget will require you to pass extra information when initializing the embed which define the floating button’s text and style.

To pass UTM and pre-filled information to each embed type, see the advanced embed options Help Center article.

Track and report on all scheduled events across your organization

Avoid pivots in your business plan when you analyze and report on your teams’ scheduled events

Vivocalendar owners and admins can report on scheduled events of teams across their organization when they generate and use a personal access token to authenticate requests they make to Vivocalendar’s API. There are two ways to report on scheduled events:

  1. Make POST requests to the Vivocalendar API to receive basic event and invitee data in real time via a webhook subscription. This method is suggested because after the webhook subscription is created, there is no further input required.

  2. Make periodic GET requests to the Vivocalendar API from your system to retrieve current event information to update your system with data from scheduled events.

The information received via either method will include UTM parameters, which help track the source of the booking. To learn more about using UTM parameters, see guide how to track conversions in our Help Center.

How to get event type and user calendar availability data

Event Type Availability

Vivocalendar users can retrieve information about availability for a specific event type when they generate and use a personal access token or OAuth token to authenticate requests to Vivocalendar’s API. 

Use cases that can be achieved with this API:

  • Take appropriate action based on available times for a given event type.

  • Effectively share available meeting times from an external application to increase the probability of meetings being booked and enhance the invitee experience.

    • For example: 

      • Display specific available times when sending communications to invitees directly from external applications.

      • Include and share first ‘X’ available times.

To retrieve a list of available times for a specific event type within a specified date range:

  1. Make a call to /event_types to retrieve a list of all event types (using the organization scope to get all event types across the organization or using the user scope to get all event types for a specific user). The endpoint will return a collection of event types with an event type  uri for each item in the array. 

  2. Make a call to /event_type_available_times and pass the event type uri for the event type you would like to retrieve information about. Please note that start_time and end_time parameters are required, must be in the future, and cannot be a range greater than 7 days. 

User Calendar Availability 

Vivocalendar users can retrieve information about the availability of users in their organization when they generate and use a personal access token or OAuth token to authenticate requests to Vivocalendar’s API. 

Use cases that can be achieved with this API:

  • Programmatically calculate total hours available for a given user for a given period of time. For example:

    • Total available hours

    • Total scheduled hours

  • Build a custom ‘Calendar View’ for a given user. 

  • View availability schedules and date overrides to determine if a user needs to open up more availability options.

To retrieve information about a specific user’s availability schedule and their busy times for a given period, make the following GET requests: 

To retrieve the availability schedules and date overrides for a specific user:

  1. Make a call to /organization_memberships to return a collection of users in an organization which includes a user.uri for each item in the array.

  2. Make a call to /user_availability_schedules and pass the specified user.uri .

To retrieve busy times for a specific user (based upon the connected calendars marked as “Check for Conflicts” in Vivocalendar ):

  1. Make a call to /organization_memberships to return a collection of users in an organization which includes a user.uri for each item in the array.

  2. Make a call to /user_busy_times and pass the specified user.uri . Please note that start_time and end_time parameters are required, must be in the future, and cannot be a range greater than 7 days.

Receive data from scheduled events in real time with webhook subscriptions

When you create a webhook subscription, payloads will be sent in real time to your server endpoint when events are scheduled or canceled by either the host or the invitee. When you create a webhook subscription, you can subscribe to either or both:

  • invitee.created for only data about scheduled events by invitees

  • invitee.canceled for only data about canceled events by invitees

  • routing_form_submission.created for only data about routing form submissions

Subscribing to both invitee.created and invitee.canceled events will return all scheduled and canceled events across all team members in your organization with a single subscription giving you full transparency into the success of meetings.

Subscribing to the routing_form_submission.created event will fire anytime someone submits a routing form, whether they book or not. NOTE: The only allowed subscription scope for Routing form submissions is organization.

If you’re an owner or admin, the personal access token you generate will authenticate the POST request with:

  • the user scope if you want to return a response payload for data about all scheduled events for yourself

  • the organization scope if you want to return a response payload for data about all scheduled events for your organization

If you’re a team member and not an owner of admin of a Bookafy organization, the personal access token you generate will only authenticate the POST request with the user scope to return a response payload for data about your own scheduled events.

To create a webhook subscription

Before you create a webhook subscription, ensure that you have the organization or the user URI (see how to find the organization or user uri) depending on which events you want to scope for.

  1. Make a POST request to the /webhook_subscriptions endpoint.

  2. Add your personal access token to authenticate the request.

  3. Set your server endpoint in the url value.

  4. Set invitee.created, or invitee.canceled, or routing_form_submission.created (or all 3) for the events value

  5. Choose the user or organization value to isolate scheduled events to yourself or the organization.

    1. Example request:
      curl --request POST --url https://api.vivocalendar.com/webhook_subscriptions
      --header 'Content-Type: application/json'
      --header 'authorization: Bearer <your personal access token>'
      --data '{
      "url":"http://yourserverendpoint.com",
      "events":["invitee.created",
      "invitee.canceled"],
      "organization":"https://api.vivocalendar.com/organizations/AAAAAAAAAAAAAAAA",
      "scope":"organization"}'

  6. (Optional) To get data about an invitee such as name, email, and their answers to custom questions on an event booking page, use the URI property in the webhook payload to make a GET request to the /scheduled_events/{event_uuid}/invitees/{invitee_uuid} endpoint.

When an invitee cancels an event, you can match them to an existing invitee in your system by comparing the URI. This will allow you to exclude the invitee or event from your data, or specifically track canceled or rescheduled events.

SSO Documentation

Enterprise solutions to fully integrate via API

SSO Tokens implementation

These are instructions on how to generate Single Sign-On tokens on your server. These token can be used to authenticate your users with
vivocalendar.

Here’s how it works:
To find your private key, login to partner dashboard as a White label Admin and
Store your private key on your server and don’t share it.
When a user wants to use the vivocalendar, send a request to your server to generate an SSO token.
On your server, generate a token using the snippet below.
Pass the token back to your app
We’ll use that token to authenticate your user.

1. Install a JWT library:
We use JSON Web Tokens to securely authenticate your users. First, install the appropriate JWT library for your server.
sudo gem install jwt

2. Generate tokens on your server:
Following sample code is in ruby.
require ‘jwt’
PrivateKey = ‘UNIQUE PRIVATE KEY’

3. SSO Signup:
You’ll create on your side for signup.
def createvivocalendarToken(user)
userData = {
iss: “abcd” , # or abcd
exp: Time.now.to_i + 900, # Time.now(in seconds) + 15 min(in seconds)
iat: Time.now.to_i, # Time.now(in seconds)
business_name: user.business_name,
email: user.email,
name: user.name,
time_zone: time_zone # default Pacific Time (US & Canada)
}
sso_token = JWT.encode(userData, PrivateKey, ‘HS276’)
end
After generating the token, You hit on http://app.examplescheduler.com/sso/signup?token=#{sso_token}
You’ll get in response.
Success Response:
Code: 201
User will be created.
Failure Response:
Send an error in response.
Error Response sample (in json):
{“status”:”forbidden”,”error”:”Validation failed: User email has already been taken”}
Once user created successfully, you’ll generate other token for login.

4. SSO login:
You’ll create on your side for sign in.
def createvivocalendarToken(user)
userData = {
email: user.email,
iss: “abcd”, # or abcd
logout_redirect_url: ‘https://xyz.com’,
exp: Time.now.to_i + 900,# Time.now(in seconds) + 15 min(in seconds)
iat: Time.now.to_i # Time.now(in seconds)
}
sso_token = JWT.encode(userData, PrivateKey, ‘HS276’)
end
http://app.exampleschedule.com/sso/login?token=#{sso_token}
You’ll get in response.
Success Case:
Code: 200
Redirected to home page if calendar connected otherwise redirected to calendar page.
Failure Response:
Send error message in response
Validation: If user not exist or you are trying with different iss
Code: 404
Error Response sample (in json)
{“status”:”forbidden”,”error”:”Validation failed: User email has already been taken”}
Note:
On logout, When User logout from the account and it will be redirected to logout_redirect_url

5. Time Zone list:
“American Samoa”, “America/Asuncion”, “Midway Island”, “Hawaii”, “Alaska”, “Pacific Time (US & Canada)”, “Tijuana”, “Arizona”, “Chihuahua”,
“Mazatlan”, “Mountain Time (US & Canada)”, “Central America”, “Central Time (US & Canada)”, “Guadalajara”, “Mexico City”, “Monterrey”,
“Saskatchewan”, “Bogota”, “Eastern Time (US & Canada)”, “Indiana East”, “Lima”, “Quito”, “Atlantic Time (Canada)”, “Caracas”, “Georgetown”,
“La Paz”, “Santiago”, “Newfoundland”, “Brasilia”, “Buenos Aires”, “Greenland”, “Montevideo”, “Mid-Atlantic”, “Azores”, “Cape Verde Is.”,
“Casablanca”, “Dublin”, “Edinburgh”, “Lisbon”, “London”, “Monrovia”, “UTC”, “Amsterdam”, “Belgrade”, “Berlin”, “Bern”, “Bratislava”, “Brussels”,
“Budapest”, “Copenhagen”, “Ljubljana”, “Madrid”, “Paris”, “Prague”, “Rome”, “Sarajevo”, “Skopje”, “Stockholm”, “Vienna”, “Warsaw”, “West
Central Africa”, “Zagreb”, “Athens”, “Bucharest”, “Cairo”, “Harare”, “Helsinki”, “Jerusalem”, “Kyiv”, “Pretoria”, “Riga”, “Sofia”, “Tallinn”, “Vilnius”,
“Baghdad”, “Istanbul”, “Kuwait”, “Minsk”, “Moscow”, “Nairobi”, “Riyadh”, “St. Petersburg”, “Volgograd”, “Tehran”, “Abu Dhabi”, “Baku”, “Muscat”,
“Tbilisi”, “Yerevan”, “Kabul”, “Ekaterinburg”, “Islamabad”, “Karachi”, “Tashkent”, “Chennai”, “Kolkata”, “Mumbai”, “New Delhi”, “Sri
Jayawardenepura”, “Kathmandu”, “Almaty”, “Astana”, “Dhaka”, “Urumqi”, “Rangoon”, “Bangkok”, “Hanoi”, “Jakarta”, “Krasnoyarsk”,
“Novosibirsk”, “Beijing”, “Chongqing”, “Hong Kong”, “Irkutsk”, “Kuala Lumpur”, “Perth”, “Singapore”, “Taipei”, “Ulaanbaatar”, “Osaka”, “Sapporo”,
“Seoul”, “Tokyo”, “Yakutsk”, “Adelaide”, “Darwin”, “Brisbane”, “Canberra”, “Guam”, “Hobart”, “Melbourne”, “Port Moresby”, “Sydney”,
“Vladivostok”, “Magadan”, “New Caledonia”, “Solomon Is.”, “Auckland”, “Fiji”, “Kamchatka”, “Marshall Is.”, “Wellington”, “Chatham Is.”,
“Nuku’alofa”, “Samoa”, “Tokelau Is.”

Start booking appointments today with your 7-day Pro Plan trial

No strings attached. No credit card required. No contracts to sign. And you can cancel anytime.

Sign Up Free

No credit card required. No spam. Cancel anytime.