Introduction
The API provides useful functionalities such as:
- Create events in Vyte directly from your app
- You will first need to register as a "third party" app in Vyte (through an endpoint)
- Then you'll be able to link to Vyte to schedule an event with all the members of a team, project, task (we call that a "group")
- You'll be able to retrieve all the events related to that group
- Link to a Vyte page and pass parameters in the URL
Register your app
Get your app secret
Examples
https://api.vyte.in/thirdparties/new?name=superapp&contact_email=superman@superapp.com&contact_name=Super%20Man
Result format 200 OK
{
"__v": 0,
"createdAt": "2016-01-18T00:13:35.203Z",
"updatedAt": "2016-01-18T00:13:35.203Z",
"secret": "mols1p5ay6comkzj73ca",
"name": "superapp",
"_id": "569c2e2fa28cc30300778c4c",
"contact": {
"email": "superman@superapp.com",
"name": "Super Man"
}
}
Result format 400 Bad Request
{}
This endpoint registers your app as a third party app and lets you obtain your app_id and app_secret.
HTTP Request
GET https://api.vyte.in/thirdparties/new
Query parameters
Parameter | Type | Required | Description |
---|---|---|---|
name |
string | true | Your application name |
contact_email |
string | true | Your e-mail address |
contact_name |
string | false | Your name |
The _id
attribute in the response object is your app_id. You will need it to identify the events created from your app and retrieve them.
Create events
Link to Vyte from your app
Example
https://www.vyte.in/add_invitees?aid=569c2e2fa28cc30300778c4c&agid=project_85fc5&et=vyte.in%20setup%20session&im=martin@vytein.com&in=Martin%20Saint-Macary&places=Skype%7Cmartin.saint-macary%7C%7CGoogle%20Hangouts%7Cmartin@vytein.com&em=Hi%20Martin,%20please%20find%20my%20suggestions%20for%20our%2015%20min%20call%20setup%20session%20on%20vyte.in.%20Best
You can set different parameters for the event creation such as title, invitees, places, and message.
You can link to Vyte using either the first step (/add_invitees), or the second step (/add_details). In both cases, all the parameters will be taken into account.
If the user creating the event already has a Vyte account, you don't need to authenticate him. If he has an account but is not logged in, he will be redirected to the login screen. Once logged in, he will be redirected back to the event creation page.
If you want to enable your users to create events with Vyte, without having a Vyte account, you need to authenticate their email with a simple token system.
HTTP Requests
GET https://www.vyte.in/add_invitees
GET https://www.vyte.in/add_details
URL Parameters
Examples
https://www.vyte.in/add_invitees?aid=569c2e2fa28cc30300778c4c
https://www.vyte.in/add_invitees?aid=569c2e2fa28cc30300778c4c&agid=project_85fc5
https://www.vyte.in/add_invitees?aid=569c2e2fa28cc30300778c4c&cm=johndoe@john.com
https://www.vyte.in/add_invitees?aid=569c2e2fa28cc30300778c4c&cn=John%20Doe
https://www.vyte.in/add_invitees?aid=569c2e2fa28cc30300778c4c&ct=qsdfjklmdqsjfklmqdjsfklmdjsqklfmjdsqkmf
https://www.vyte.in/add_invitees?aid=569c2e2fa28cc30300778c4c&em=Hello
https://www.vyte.in/add_invitees?aid=569c2e2fa28cc30300778c4c&et=Meeting%20to%20resolve%20this%20task%20for%20that%20project
https://www.vyte.in/add_invitees?aid=569c2e2fa28cc30300778c4c&places=Skype
Parameter | Required | Description |
---|---|---|
aid |
true | App ID: your app ID for Vyte. You get it when you register your app with GET /thirdparties/new |
agid |
false | App Group ID: this is an id you will provide to Vyte, that you will use to identify a group of users such as a team, a project, etc. |
cm |
true/false | Creator e-mail: optional if the user already has a Vyte account |
cn |
false | Creator name: useful to auto set a title with the name of all the participants |
ct |
true/false | Creator token: optional if the user already has a Vyte account |
em |
false | Event message |
et |
false | Event title |
im |
false | Invitee e-mail(s), separated by a pipe (|) |
in |
false | Invitee name(s), separated by a pipe (|). To be used with im , with emails and names listed in the same order |
places |
false | Event places, with place name and address separated by a single pipe (|) and several places separated by a double pipe (||) |
Authentication
To enable your users to create events with Vyte without having a Vyte account, you will need to provide cm
(Creator e-mail) and ct
(Creator token) parameters to the Vyte urls.
Compute the token yourself
Example in Node.js
const crypto = require('crypto');
const computeToken = (email, secret) => {
const hmac = crypto.createHmac('sha256', secret);
hmac.setEncoding('hex');
hmac.write(email);
hmac.end();
return hmac.read();
};
The Creator Token is computed from the Creator Email and your app_secret using the Hmac-sha256
algorithm.
You can compute it yourself using the code on sidebar.
Compute the token via the API
Result format 200 OK
{"token": "qsdfjklmdqsjfklmqdjsfklmdjsqklfmjdsqkmf"}
Result format 400 Bad Request
{}
This endpoint gives the Creator Token you need for the Vyte urls.
HTTP Request
GET https://api.vyte.in/thirdparties/token
Query parameters
Parameter | Type | Required | Description |
---|---|---|---|
cm |
string | true | Creator e-mail |
secret |
string | true | Your app secret |
Booking an appointment
Header
Content-Type: application/json
Example of body
{
"confirmed":{"flag": true},
"created_by":{"email": "user.name@domain.com"},
"dates":[{"all_day": false, "date": "2017-11-10T11:00:00.000Z", "end_date": "2017-11-10T12:00:00.000Z"}],
"invitees":[{"full_name": "Person booking a slot name", "email": "jean.dupont@domain.com", "phone": "0601020304"}],
"lang":"fr",
"locale":"fr",
"messages":[{"body": "I’m booking appointment about this"}],
"places":[{"name": "Office name", "address": "12 rue de Rivoli, 75004, Paris, France"}],
"timezone":"Europe/Paris",
"title":"Appointment about topic",
"vyteme":true,
"third_party": {
"ct": "creator_token",
"app": "app_id"
"group_ids": ["user123", "group456", "companyABC"]
}
}
HTTP Request
POST https://api.vyte.in/events
Comparing with the example on the sidebar of this page:
app_id
is your application id you got at step Register your app.creator_token
is the token computed from the address email of the user you want to book an appointment with and yourapp_secret
group_ids
is an array of arbitrary ids from your app that you would like to link to that event. You will then be able to query events by those group_ids.
Link to a Vyte Page from your app
You can make booking on your Vyte page even faster by setting pretty much everything but the dates directly in the URL. This could also prove interesting when adding a link to your Vyte page in an emailing campaign.
You don't need to register your app to do that, however you will need to have set up a Vyte page with a pro Vyte account.
- If you don't have a Vyte account yet, sign up from https://vyte.in/page to set up your Vyte page.
- If you already have a Vyte account, but don't have a Vyte page yet, set it up from your settings: https://www.vyte.in/settings#vyteme.
- Make sure to enable the "Enable API variables in URL" setting in the advanced Vyte page settings from https://www.vyte.in/settings#vyteme_pro.
Appointment duration
You can set the duration (in minutes) of an appointment directly in the URL as such:
- https://vyte.in/acme/30 for a 30 minutes appointment
- https://vyte.in/acme/120 for a 2 hours appointment
URL parameters
Example
https://www.vyte.in/emma/20?et=Meeting%20%7B%7Binvitee%7D%7D&cm=john.doe@domain.com&cn=John%20Doe&places=Skype%7Cjohn%7C%7CGoogle%20Hangouts%7Cjoh.doe@domain.com&em=Hello
You can use those parameters with the URL of your Vyte page (ex: https://vyte.in/acme)
Parameter | Required | Description |
---|---|---|
cn |
false | Creator name: useful to auto set a title with the name of all the participants |
cm |
false | Creator e-mail: if you set cn your invitees won't be prompted to put their name and emails or to login with Google to book you. We highly recommend to populate cm along. |
cc |
false | Creator company: make sure to enable the "Ask for company" setting in your advanced Vyte page settings. |
cp |
false | Creator phone number: make sure to enable the "Ask for phone number" setting in your advanced Vyte page settings. |
em |
false | Event message |
et |
false | Event title |
places |
false | Event places: place name and address separated by a single pipe (|) and several places separated by a double pipe (||) |
aid |
true | App ID: your app ID for Vyte. You get it when you register your app with GET /thirdparties/new |
agid |
false | App Group ID: this is an id you will provide to Vyte, that you will use to identify a group of users such as a team, a project, etc. |
Get free slots
This section of the documentation explains how to retrieve free slots for Vyte users to help you schedule your meetings.
Get slots in bulk
Examples
https://api.vyte.in/slots?duration=60&emails=user.name@domain.com&from=2017-11-10&to=2017-11-10
Response on success: 200 OK
{
"slots": [
{
"start": {
"dateTime": "2017-11-10T10:00:00.000+02:00"
},
"end": {
"dateTime": "2017-11-10T11:00:00.000+02:00"
}
},
{
"start": {
"dateTime": "2017-11-10T11:00:00.000+02:00"
},
"end": {
"dateTime": "2017-11-10T12:00:00.000+02:00"
}
},
]
}
HTTP request
GET /slots
Query parameters
Parameter | Type | Required | Description |
---|---|---|---|
duration |
number | true | Duration of the appointment in minutes |
emails |
string | true | Address of the person you want to book an appointment with. It has to be the address that person is signed up with on Vyte |
from |
string | true | Date from when you want to get available slots (included) formatted as YYYY-MM-DD |
to |
string | true | Date until when you want to get available slots (included) formatted as YYYY-MM-DD |
timezone |
string | false | timezone in the format Europe/Paris . See list of timezones on https://en.wikipedia.org/wiki/List_of_tz_database_time_zones |
Get slots grouped by days
Examples
https://api.vyte.in/slots/days?duration=30&emails=user.name@domain.com&from=2017-12-18&to=2017-12-18
Response on success: 200 OK
{
"days": {
"2017-12-18": {
"slots": [
{
"start": {
"dateTime": "2017-12-18T09:30:00.000+02:00"
},
"end": {
"dateTime": "2017-12-18T10:00:00.000+02:00"
}
},
{
"start": {
"dateTime": "2017-12-18T10:00:00.000+02:00"
},
"end": {
"dateTime": "2017-12-18T10:30:00.000+02:00"
}
},
]
}
}
}
Just add /days
to the previous end point to get the results formatted as a dictionary where keys are days formatted as YYYY-MM-DD
.
For completeness, we report here the relative documentation.
HTTP request
GET /slots/days
Query parameters
Parameter | Type | Required | Description |
---|---|---|---|
duration |
number | true | Duration of the appointment in minutes |
emails |
string | true | Address of the person you want to book an appointment with. It has to be the address that person is signed up with on Vyte |
from |
string | true | Date from when you want to get available slots (included) formatted as YYYY-MM-DD |
to |
string | true | Date until when you want to get available slots (included) formatted as YYYY-MM-DD |
Get next availability if no slots in the requested time frame
Response on success: 200 OK
{
"nextAvailability": {
"availableDate": "2017-12-18",
"availableSlot": {
"start": {
"dateTime": "2017-12-18T09:30:00+01:00"
},
"end": {
"dateTime": "2017-12-18T10:00:00+01:00"
}
}
},
"days": {},
}
If the user you are requesting available slots for has no availability in the requested time frame, Vyte’s API will tell you their next availability.
In this case you will have slots: []
if you’ve used /slots
(1.1) or days: {}
for /slots/days
(1.2)
The response will include a nextAvailability
object formatted as in the example.
Get events
Get events by group_id
Examples with one and two group IDs
https://api.vyte.in/thirdparties/569c2e2fa28cc30300778c4c/groups/groupABC/events
https://api.vyte.in/thirdparties/569c2e2fa28cc30300778c4c/groups/groupABC,groupDEF/events
HEADERS:
Authorization: your_app_secret
Result format 200 OK
[
{
"_id": "569c3b6105dc780300951bd0",
"key_store": "569c3b6105dc780300951bd7",
"email": "reply-to-participants-to-meeting-for-project-vqdhhcxqd@vyte.in",
"invitees_length": 3,
"createdAt": "2016-01-18T01:09:53.477Z",
"updatedAt": "2016-01-18T01:10:05.670Z",
"alias": "alias_web_522984fb35eaa70200000007_1453079356811",
"app_url": "https://www.vyte.in",
"lang": "en",
"locale": "en",
"timezone": "Europe/Paris",
"title": "Meeting for project",
"__v": 3,
"version": 3,
"third_party": {
"app": "569c2e2fa28cc30300778c4c",
"group_ids": ["project_85fc5"],
"name": "superapp"
},
"ics_sequence": 0,
"confirmed": {
"updated_at": null,
"flag": false
},
"places": [
{
"createdAt": "2016-01-18T01:09:53.290Z",
"updatedAt": "2016-01-18T01:10:05.665Z",
"name": "Appear.in",
"address": "http://appear.in/cool-meeting",
"icon": "P",
"_id": "569c3b6105dc780300951bd3",
"votes": {
"no": [],
"yes": [
{
"_id": "569c3b6105dc780300951bd6",
"createdAt": "2016-01-18T01:09:54.161Z",
"updatedAt": "2016-01-18T01:10:05.664Z",
"created_by": {
"user": "522984fb35eaa70200000007"
}
}
]
},
"created_by": {
"user": "522984fb35eaa70200000007"
},
"source": "Appear.in"
}
],
"dates": [
{
"createdAt": "2016-01-18T01:10:05.665Z",
"updatedAt": "2016-01-18T01:10:05.665Z",
"date": "2016-01-22T10:00:00.000Z",
"end_date": "2016-01-22T11:00:00.000Z",
"_id": "569c3b6da28cc30300778c72",
"votes": {
"no": [],
"yes": [
{
"_id": "569c3b6da28cc30300778c74",
"created_by": {
"user": "522984fb35eaa70200000007"
}
}
]
},
"created_by": {
"user": "522984fb35eaa70200000007"
},
"all_day": false
},
{
"createdAt": "2016-01-18T01:10:05.665Z",
"updatedAt": "2016-01-18T01:10:05.665Z",
"date": "2016-01-22T15:00:00.000Z",
"end_date": "2016-01-22T16:00:00.000Z",
"_id": "569c3b6da28cc30300778c73",
"votes": {
"no": [],
"yes": [
{
"_id": "569c3b6da28cc30300778c76",
"created_by": {
"user": "522984fb35eaa70200000007"
}
}
]
},
"created_by": {
"user": "522984fb35eaa70200000007"
},
"all_day": false
}
],
"declines": [],
"messages": [
{
"from": "martin.saintmac@gmail.com",
"createdAt": "2016-01-18T01:09:53.290Z",
"updatedAt": "2016-01-18T01:10:05.664Z",
"body": "Another meeting for that project",
"_id": "569c3b6105dc780300951bd4",
"created_by": {
"user": "522984fb35eaa70200000007"
}
}
],
"invitees": [],
"created_by": {
"full_name": "Martin Saint-Macary",
"picture_url": "https://lh3.googleusercontent.com/-PWeG6KmcyVw/AAAAAAAAAAI/AAAAAAAAJa4/kcQXhsmUmTQ/photo.jpg",
"user": "522984fb35eaa70200000007",
"email": "martin.saintmac@gmail.com"
}
},
{
"_id": "569c3afaa28cc30300778c69",
"key_store": "569c3afba28cc30300778c71",
"email": "reply-to-participants-to-meeting-martin-saint-macary-martin-saint-macary-awtdmgsnm@vyte.in",
"invitees_length": 2,
"createdAt": "2016-01-18T01:08:11.524Z",
"updatedAt": "2016-01-18T01:08:12.691Z",
"alias": "alias_web_522984fb35eaa70200000007_1453079284514",
"app_url": "https://www.vyte.in",
"lang": "en",
"locale": "en",
"timezone": "Europe/Paris",
"title": "Meeting Martin Saint-Macary, Martin Saint-Macary",
"__v": 1,
"version": 1,
"third_party": {
"app": "569c2e2fa28cc30300778c4c",
"group_ids": ["project_85fc5"],
"name": "superapp"
},
"ics_sequence": 0,
"confirmed": {
"updated_at": null,
"flag": false
},
"places": [
{
"createdAt": "2016-01-18T01:08:10.933Z",
"updatedAt": "2016-01-18T01:08:12.688Z",
"name": "Skype",
"address": "martin.saint-macary",
"_id": "569c3afaa28cc30300778c6c",
"votes": {
"no": [],
"yes": [
{
"_id": "569c3afba28cc30300778c6f",
"createdAt": "2016-01-18T01:08:12.688Z",
"updatedAt": "2016-01-18T01:08:12.688Z",
"created_by": {
"user": "522984fb35eaa70200000007"
}
}
]
},
"created_by": {
"user": "522984fb35eaa70200000007"
},
"source": "app"
},
{
"createdAt": "2016-01-18T01:08:10.934Z",
"updatedAt": "2016-01-18T01:08:12.689Z",
"name": "Google Hangouts",
"address": "martin@vytein.com",
"_id": "569c3afaa28cc30300778c6b",
"votes": {
"no": [],
"yes": [
{
"_id": "569c3afba28cc30300778c70",
"createdAt": "2016-01-18T01:08:12.688Z",
"updatedAt": "2016-01-18T01:08:12.688Z",
"created_by": {
"user": "522984fb35eaa70200000007"
}
}
]
},
"created_by": {
"user": "522984fb35eaa70200000007"
},
"source": "app"
}
],
"dates": [],
"declines": [],
"messages": [
{
"from": "martin.saintmac@gmail.com",
"createdAt": "2016-01-18T01:08:10.934Z",
"updatedAt": "2016-01-18T01:08:12.688Z",
"body": "Hi Martin, please find my suggestions for our 15 min call setup session on vyte.in. Best",
"_id": "569c3afaa28cc30300778c6d",
"created_by": {
"user": "522984fb35eaa70200000007"
}
}
],
"invitees": [],
"created_by": {
"full_name": "Martin Saint-Macary",
"picture_url": "https://lh3.googleusercontent.com/-PWeG6KmcyVw/AAAAAAAAAAI/AAAAAAAAJa4/kcQXhsmUmTQ/photo.jpg",
"user": "522984fb35eaa70200000007",
"email": "martin.saintmac@gmail.com"
}
}
]
Result format 400 Bad Request
{}
This endpoint lists the events created from your app for a group of users.
HTTP Request
GET https://api.vyte.in/thirdparties/:app_id/groups/:group_ids/events
Authentication
This request needs to be authenticated using your app secret, using the Authorization
header
Path parameters
Parameter | Type | Required | Description |
---|---|---|---|
:app_id |
string | true | Your app id |
:group_ids |
string | true | The custom group id you want the list for. If you want events belonging to several group IDs, separate them with a comma. |
Update events
Confirm an event
Examples
https://api.vyte.in/api/v1/events/569c2e2fa57cc30300778c4d/confirm
HEADERS:
Authorization: api_key_for_your_organization
Result format: 200 OK
This endpoint confirms an event of your Organization
HTTP Request
GET https://api.vyte.in/api/v1/events/:event_id/confirm
Authentication
You can confirm events whose created_by is in your Organization. This request needs to be authenticated with an API Key.
Path parameters
Parameter | Type | Required | Description |
---|---|---|---|
:event_id |
string | true | Id of the event. Found as _id in event resources. |
Query parameters
Parameter | Type | Required | Description |
---|---|---|---|
d |
string | false | Id of the date that you want to confirm. Found as the _id of the relevant date object in the dates array property of the event. Optional if the event has only one date. If the event has more than one date and it is not provided the closest date with more votes will be used. |
p |
string | false | Id of the place that you want to confirm. Found as the _id of the relevant date object in the places array property of the event. Optional if the event has only one place. If the event has more than one place and it is not provided the first place with more votes will be used. |
Cancel an event
Examples
https://api.vyte.in/api/v1/events/569c2e2fa57cc30300778c4d/cancel
HEADERS:
Authorization: api_key_for_your_organization
Result format: 200 OK
This endpoint cancels an events of your Organization
HTTP Request
GET https://api.vyte.in/api/v1/events/:event_id/cancel
Authentication
You can cancel events whose created_by is in your Organization This request needs to be authenticated with an API Key.
Path parameters
Parameter | Type | Required | Description |
---|---|---|---|
:event_id |
string | true | Id of the event. Found as _id in event resources. |
Update an event
Examples
PUT https://api.vyte.in/api/v1/events/569c2e2fa57cc30300778c4d
HEADERS:
Authorization: api_key_for_your_organization
Result format: 200 OK
This endpoint lets you update dates and / or places for an event
HTTP Request
PUT https://api.vyte.in/api/v1/events/:event_id
Authentication
You can confirm events whose created_by is in your Organization. This request needs to be authenticated with an API Key.
Path parameters
Parameter | Type | Required | Description |
---|---|---|---|
:event_id |
string | true | Id of the event. Found as _id in event resources. |
Body parameters
Parameter | Type | Required | Description |
---|---|---|---|
dates |
array | false | array of the dates for that event. Existing dates will be replaced. Each array element should have the following format: {date: string, end_date: string} where date and end_date are iso representation of the new dates |
places |
array | false | array of places for that event. Existing places will be replaced |
Organizations
Organizations are a way to group several users for 2 purposes:
Pay for multiple pro subscriptions with only 1 bill.
Share a branding across multiple users
Organizations can be used for deploying Vyte in an actual organization, but they can also be used to integrate Vyte into another app or service and pay for your users.
When you create an organization, you can then invite other people to it. If they are not users yet, they will be added to the organization as soon as they have signed up.
Once added to the organization theses users will be upgraded to a PRO plan automatically, granting them access to all the features of Vyte. The organization admin is billed for them.
If the organization admin creates a brand (or has created one), their custom subdomain, background and logo will be applied to all the members of the organization.
Creating an organization
To create an organization, just go to the Organization tab of your Vyte settings.
Private organizations
If you use an organization to integrate Vyte into your app or service, and pay for your users, you probably don't want your users to be able to see each other.
In that case you probably want to set your organization to private
.
This is a manual task for now, so just ping us on the chat window that is on the bottom right corner of Vyte's landing pages and web app, and mention that you are a developer using our API.
Getting an organization
Example
GET https://api.vyte.in/users/organizations
Organizations used to be called Teams
.
To get all the information about your organization, you can do an API call in your browser
Authentication
Just make sure you are connected to Vyte in that browser as the organization admin.
HTTP Request
GET /users/organizations
Response
Some interesting fields of the response body:
Field | Type | Definition |
---|---|---|
_id | String | The id of your organization |
name | String | The name of your organization |
private | Boolean | Wether your organization is private or not. Default to false |
members | Array | The members of your organization, including its admin. |
admins | Array | The admin of your organization. |
Link to join an organization on Vyte
Basic example:
https://www.vyte.in/organizations/14ce14c8a8ced358c78a5c231d/join
If you want to integrate Vyte into your app or service, you'll probably want to have access to your users availability. For that you will need to get them to create a Vyte account.
This can be done purely via API if you don't need them to connect a calendar or that you have access to their calendar credentials. In many cases though, you will want your users to connect their calendar themselves. If they are using Google or Microsoft Office 365 calendar, this needs to be done through Google / Microsoft OAuth 2 flows, and these need to happen in the frontend.
To do that you can point them to the link to join your organization:
GET https://www.vyte.in/organizations/:organization_id/join
Where :organization_id
is the id you got when getting your organization
This link will let them sign up for Vyte and automatically join your organization as soon as they have signed up.
If they were already Vyte users, they will just automatically join your organization by visiting this link.
Using a custom design on that signup page.
Example with a custom subdomain:
https://mycoolapp.vyte.in/organizations/14ce14c8a8ced358c78a5c231d/join
If you want that sign up page to showcase your brand, no problem, just set up your brand and subdomain in your Vyte's settings and use that subdomain instead of www
Knowing when a user joins your organization
You probably want to know when a user joins your organization after you have pointed them to the link to join your organization on Vyte.
For that, just subscribe to the user.joined
webhook
Matching your app users to Vyte's users
Example with a custom subdomain and an extid
https://mycoolapp.vyte.in/organizations/14ce14c8a8ced358c78a5c231d/join?extid=user55542
When pointing one of your users to sign up to Vyte, you can pass an extid
query Parameter.
This extid
can be whatever id you need to be able to match a Vyte user to your users when getting called back by the user.joined
webhook.
API keys
Some endpoints such as /hooks
needs to be authenticated with api keys.
Get an API key for your organization
Example
GET https://api.vyte.in/api/keys/organization
Response on success:
200 OK
{
"__v": 0,
"createdAt": "2018-01-04T11:49:28.220Z",
"updatedAt": "2018-01-04T11:49:28.220Z",
"key": "i2xthzol66q9zucx04ta4ljptg1bd26ctuf3curhtufoaxf8t8",
"organization": "14ce14c8a8ced358c78a5c231d",
"user": "14ce14c8a8ced3001c8a5c231d",
"_id": "5a4e14c8a8ced3001c8a5c231d",
"scope": "organization"
}
Get an API key for that organization by accessing /api/keys/organization
Make sure you have logged in with the Vyte account that is the admin of that organization before that.
If you access that link several times you will get the same API key. To get a new one you will need to delete it first and then get a new one.
HTTP request
GET /api/keys/organization
Response object main fields:
Field | Meaning |
---|---|
key | this is the key you will need to use to authenticate. |
_id | the id of this API key. You will need it to delete / revoke this API key. |
Delete an API key
Example
DELETE https://api.vyte.in/api/keys/:5a4e14c8a8ced3001c8a5c231d
Response on success:
204
HTTP request
DELETE /api/keys/:key_id
where :key_id
is the _id
property of your key.
Authenticating a request with an API key
There are 2 ways of doing so: using the api_key
query param or the Authorization
header.
Authenticating using the query param
Example
GET https://api.vyte.in/api/keys/organization?api_key=i2xthzol66q9zucx04ta4ljptg1bd26ctuf3curhtufoaxf8t8
Just add an api_key
query param, set to the key
obtained above, to the URL of your request
Authenticating using the Authorization header
Example
GET https://api.vyte.in/api/keys/organization
HEADERS:
Content-Type: application/json
Authorization: i2xthzol66q9zucx04ta4ljptg1bd26ctuf3curhtufoaxf8t8
Just add an Authorization
header, set to the key
obtained above, to your request.
Users
Users for your Organization can be created and configured through the API.
Create a user
To create a user perform a POST request to the users
endpoint. With that request you can actually set up most of the settings for that user
Example
POST https://api.vyte.in/api/v1/users
Body
{
"organization": "yourVyteOrganizationId",
"finish_signup_with": "email", /* Should be the literal "email" string, not the user email address. With this you'll get back a URL for the user to set their Vyte password. Use this if you need them to set a password on Vyte, otherwise don't put it*/
"user": {
"email": "jean.dupont@acme.fr",
"first_name": "Jean",
"last_name": "Dupont",
"language": "fr",
"timezone": "Europe/Paris",
"picture_url": "https://www.example.com/picture/jean",
"account": {
"organization": {
"extid": "userIdInThirdPartyAppDatabase"
}
}
},
"teams": [{ /* Useful if you would like to have team admins manage events of team members in the future */
"admin": false,
"name": "Management team",
"extid": "teamIdInThirdPartyAppDatabase"
}],
"availability": {
"timezone": "Europe/Paris",
"today_as_busy": false, // prevent from booking on the same day
"past_as_busy": true, // prevent from booking in the past
"days_after_as_busy": 60, // prevent from booking in more than n days
"buffer_before": 0, // ensure users have at least n minutes free before each meeting
"buffer_after": 0, // ensure users have at least n minutes free after each meeting
"all_day_busy": true, // if the user has busy all day events on its calendar the full day will be marked as busy on Vyte
"days": {
"monday": {
"enabled": true, // we enable bookings on that day
"slots": [
{
"start_time": "2018-01-01T10:00", // date part of the string doesn't matter
"end_time": "2018-01-01T12:30"
},
{
"start_time": "2018-01-01T14:00",
"end_time": "2018-01-01T18:30"
}
]
},
"tuesday": {
"enabled": true,
"slots": [
{
"start_time": "2018-01-01T10:00",
"end_time": "2018-01-01T12:30"
},
{
"start_time": "2018-01-01T14:00",
"end_time": "2018-01-01T18:30"
}
]
},
"wednesday": {
"enabled": true,
"slots": [
{
"start_time": "2018-01-01T10:00",
"end_time": "2018-01-01T17:30"
}
]
},
"thursday": {
"enabled": false
},
"friday": {
"enabled": true,
"slots": [
{
"start_time": "2018-01-01T10:00",
"end_time": "2018-01-01T17:30"
}
]
},
"saturday": {
"enabled": true,
"slots": [
{
"start_time": "2018-01-01T10:00",
"end_time": "2018-01-01T17:30"
}
]
},
"sunday": {
"enabled": false
}
}
},
"vyteme": { /* Useful to create a Vyte booking Page */
"nickname":"appName-userIdInThidPartyAppDatabase",
"message": "Bienvenue sur ma page de RDV",
"custom": {
"auto_message": "Merci d'avoir pris RDV avec moi, j'ai hate de vous rencontrer.",
"auto_title": "RDV {{invitee}} / {{me}}",
"ask_phone": true,
"ask_company": false,
"block_new_invitee": false,
"duration": 30,
"set_lang": true, // only use if you only accept bookings in one language
"enable_api": true, // to enable API variables
"fixed_lang": "fr",
"set_timezone": true,
"fixed_timezone": "Europe/Paris", // only use if you only accept bookings from people on your own timezone
"event_hide_decline": false,
"hide_places": false, // hide places from the booking page
"hide_support": true, // hide Vyte support button from the booking page (recommended for an integration)
"hide_title": true, // people booking cannot set a title / subject for the event
"forbid_add_places": true, // forbid from suggesting other places from the booking page
"min_dates": 1, // enforces a minimum number of slots on the booking page (only works for calendar vie, not slots view)
"one_slot": true, // only one slot can be suggsted on the calendar view
"auto_confirm": true, // if true the event will be booked as confirmed automatically
"invite_title": "Book a short appointment with", // customize the wording on the booking page
"redirect_url": "https://www.example.com/thanks-for-booking", // url to redirect people after the booking is made
"fixed_places": [ // set up a list of places on the booking page
{
"name": "Office",
"address": "Office address",
"source": "appName",
"source_id": "placeIdInThirdPartyAppDatabase"
},
{
"name": "Phone",
"address": "0102030405"
}
]
}
},
"calendars": [{ //if you have access to your google Exchange credentials you can set their calendars on Vyte directly
"source": "exchange",
"credentials": {
"server": "mail.exchangeserverdomain.com",
"username": "calendarUserName",
"password": "calendarPassword"
}
}],
"login": {
"credentials": {
"username": "jean.dupont@example.com",
"password": "youllneverguessit"
}
}
}
Response on success:
201 Created
{
"__v": 0,
"createdAt": "2018-01-04T15:00:58.486Z",
"updatedAt": "2018-01-04T15:00:58.486Z",
"organization": "14ce14c8a8ced358c78a5c231d",
"scope": "organization",
"action": "event.cancelled",
"target_url": "https://api.example.com/hooks/12345",
"_id": "5a4e41aaa8ced3001bf5da77"
}
HTTP request
POST https://api.vyte.in/api/v1/users
Authentication
This request needs to be authenticated with an API Key for your Organization
Body properties
Parameter | Type | Required | Description |
---|---|---|---|
organization |
string | true | The id of your your Organization. Found as _id when requesting your Organization. |
finish_signup_with |
string | false | If you want your user to finish signing up on Vyte to set their password, then set that to "email" (the actual "email" string, not the email of the user), otherwise don't use it. |
user |
object | true | The actual user object |
login |
object | false | To set username and password login credentials for the user |
teams |
object | false | Useful if you would like to have team admins manage events of team members. Contact our support about this. |
vyteme |
object | false | To create and set a Vyte page for the user |
availability |
object | false | To setup the availabilities of the user, just as they would set them on https://www.vyte.in/pages/1#availabilities |
calendars |
object | false | To set the user's Exchange or CalDav calendars if you have access to their credentials |
Update a user
Updating a user is very similar to creating one, in fact the POST endpoint is idempotent so you could use it to update the user, but to be more RESTful we provide a PUT endpoint.
To make sure that it is the same user that is updated, it is highly recommended to populate the user.account.organization.extid
property and reuse that same id for the update.
HTTP request
PUT https://api.vyte.in/api/v1/users
Authentication
This request needs to be authenticated with an API Key for your Organization
Webhooks
Available webhooks
When registering for webhooks, you register for actions
on resources. Actions are often called "events" in the webhooks terminology, but since Vyte's main resource is called "Event" we decided to name them actions
.
Event resource
This is the main resource on Vyte. An event
is a meeting, 1-on-1 or group. It can be already confirmed, or still in the planing phase.
Usually an event is created, then confirmed and sometimes updated or cancelled.
event.created
When an event has been created
event.confirmed
When an event has been confirmed which means a date and / or place have been decided.
Some events can be created already confirmed. In this case both event.created
and event.confirmed
actions are fired.
event.updated
When an event that was already confirmed has ben edited an reconfirmed. Usually the final date and / or place has been changed but there is no guarantee of it.
event.cancelled
When an event, confirmed or not, has been cancelled.
User resource
A user is someone that has signed up to Vyte.
user.joined
When a user has joined an organization using a link such as https://yourapp.vyte.in/organizations/1234/join
.
If you have passed us an external id from your app extid
as a query parameter, you will get it back as the resource.account.organization.extid
property
Authentication for Webhooks
To use webhooks you need to have a Vyte organization and an API key for your organization
All requests require to be authenticated
Creating a webhook
Example
POST https://api.vyte.in/hooks
Body
{
"action": "event.cancelled",
"target_url": "https://api.example.com/hooks/12345"
}
Response on success:
201 Created
{
"__v": 0,
"createdAt": "2018-01-04T15:00:58.486Z",
"updatedAt": "2018-01-04T15:00:58.486Z",
"organization": "14ce14c8a8ced358c78a5c231d",
"scope": "organization",
"action": "event.cancelled",
"target_url": "https://api.example.com/hooks/12345",
"_id": "5a4e41aaa8ced3001bf5da77"
}
HTTP request
POST /hooks
Request body
Field | Type | Mandatory | Definition |
---|---|---|---|
action | String | true | The action that you want to be aware of |
target_url | String | true | The URL you want to be called at when the action occurs. This must be a https url. |
The action
field is often called event
in the Webhooks terminology.
As Events are the main resource on Vyte's API, we named that field action
to avoid confusion.
Getting a webhook
Example
GET https://api.vyte.in/hooks/5a4e41aaa8ced3001bf5da77
Response on success:
200 OK
{
"__v": 0,
"createdAt": "2018-01-04T15:00:58.486Z",
"updatedAt": "2018-01-04T15:00:58.486Z",
"organization": "14ce14c8a8ced358c78a5c231d",
"scope": "organization",
"action": "event.cancelled",
"target_url": "https://api.example.com/hooks/12345",
"_id": "5a4e41aaa8ced3001bf5da77"
}
HTTP request
GET /hooks/:hook_id
where :hook_id
is the _id
of the webhook obtained when creating the webhook.
Updating a webhook
Example
PUT https://api.vyte.in/hooks/5a4e41aaa8ced3001bf5da77
Body
{
"action": "event.updated",
"target_url": "https://api.example.com/hooks/54321"
}
Response on success:
200 OK
{
"__v": 0,
"createdAt": "2018-01-04T15:00:58.486Z",
"updatedAt": "2018-01-04T15:00:58.486Z",
"organization": "14ce14c8a8ced358c78a5c231d",
"scope": "organization",
"action": "event.updated",
"target_url": "https://api.example.com/hooks/54321",
"_id": "5a4e41aaa8ced3001bf5da77"
}
HTTP request
PUT /hooks/:hook_id
where :hook_id
is the _id
of the webhook obtained when creating the webhook.
Request body
Field | Type | Mandatory | Definition |
---|---|---|---|
action | String | true | The action that you want to be aware of |
target_url | String | true | The URL you want to be called at when the action occurs. This must be a https url. |
Deleting a webhook
Example
DELETE https://api.vyte.in/hooks/1234
Response on success:
204 No Content
HTTP request
DELETE /hooks/:hook_id
where :hook_id
is the _id
of the webhook obtained when creating the webhook.
Listing all your webhooks
Example
GET https://api.vyte.in/hooks
Response on success:
200 OK
{
"hooks": [
{
"__v": 0,
"createdAt": "2018-01-04T15:00:58.486Z",
"updatedAt": "2018-01-04T15:00:58.486Z",
"organization": "14ce14c8a8ced358c78a5c231d",
"scope": "organization",
"action": "event.cancelled",
"target_url": "https://api.example.com/hooks/12345",
"_id": "5a4e41aaa8ced3001bf5da77"
}
]
}
HTTP request
GET /hooks
returns a hooks
array.
Getting a webhook call
Example:
POST https://api.example.com/hooks/12345
HEADERS:
Content-Type: application/json
BODY:
{
"action": "event.cancelled",
"resource": {
"cancelled": "2017-12-01T12:05:00.000Z",
"confirmed":{"flag": true},
"created_by":{"email": "user.name@domain.com"},
"dates":[{"all_day": false, "date": "2017-11-10T11:00:00.000Z", "end_date": "2017-11-10T12:00:00.000Z"}],
"invitees":[{"full_name": "Person booking a slot name", "email": "jean.dupont@domain.com", "phone": "0601020304"}],
"lang":"fr",
"locale":"fr",
"messages":[{"body": "I’m booking appointment about this"}],
"places":[{"name": "Office name", "address": "12 rue de Rivoli, 75004, Paris, France"}],
"timezone":"Europe/Paris",
"title":"Appointment about topic",
"vyteme":true
},
"organization": "14ce14c8a8ced358c78a5c231d"
}
When an action you have subscribed a webhook for is performed on a resource, Vyte will call your API at the target_url
you provided.
HTTP request
POST target_url
Vyte will perform a POST request at the target_url
provided
Request body
The request body is an array of objects representing actions that have happened on a resource linked to your api key. You can assume this array will always have a length of 1 but that may change in the future.
Object properties
Property | Type | Always present | Definition |
---|---|---|---|
action | String | true | The action that happened on the resource. ex: event.cancelled |
organization | String | false | The id of the organization linked to that action |
user | String | false | The id of the user linked to that action |
resource | Object | true | The resource that has been updated by this action. An event object for instance. |
Errors
The Vyte API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request was somehow incorrect. Make sure you include the right parameters in the query, body or headers |
401 | Unauthorized -- This request requires to be authenticated and you are not |
403 | Forbidden -- You are authenticated but you are not allowed to perform this Request |
404 | Resource not found -- We couldn't find the resource you are trying to access |
500 | Internal server error -- For some reason your request triggered an internal error in our API. Contact us to know more about it. |
503 | Request timed out -- Our API servers didn't respond in time and the request timed out. If this happens repeatedly, contact us. |