NAV Navbar
  • Introduction
  • Register your app
  • Create events
  • Link to a Vyte Page from your app
  • Get free slots
  • Get events
  • Update events
  • Organizations
  • API keys
  • Users
  • Webhooks
  • Errors
  • Introduction

    The API provides useful functionalities such as:

    1. Create events in Vyte directly from your app
      1. You will first need to register as a "third party" app in Vyte (through an endpoint)
      2. 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")
      3. You'll be able to retrieve all the events related to that group
    2. 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

    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:

    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.

    Appointment duration

    You can set the duration (in minutes) of an appointment directly in the URL as such:

    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:

    1. Pay for multiple pro subscriptions with only 1 bill.

    2. 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.

    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.