Skip to content

Revenue Grid Scheduler API Endpoints

For users of the Email Sidebar on:

 

10 min read

 

RG Scheduler API includes a set of special API endpoints to enable various apps and services to take an advantage of its meeting scheduling capabilities. Provided endpoints are intended for meeting scheduling scenarios:

  • Parse own and colleagues’ actual calendar availability data from their MS Outlook calendars
  • Easily perform meetings scheduling in MS Outlook and Salesforce calendars by the means of API calls and update scheduled meetings

 

Overview

Scheduler API is designed for server-to-server integrations and can perform meeting scheduling/data retrieval across all users in a customer’s organization. Any Meeting Organizer referenced by this API should be a valid Revenue Inbox user with properly configured Office 365 or MS Exchange connectivity. The feature is compatible with MS Graph and allows MS Teams integration through it. It is scalable to accommodate customer-specified volumes of API calls.
For internal (in-org) users, the API can be used to schedule meetings on users’ behalf or retrieve their calendar availability spans.
External (out of org) contacts may only be referenced as attendees for the meetings scheduled over this API.

 

API Authorization

Scheduler API supports 3 authorization methods:

  • (Legacy approach, disabled by default) Via Administrator user login/password
  • (Recommended) OAuth 2.0 Refresh token flow
  • (Single tenant deployments only) HMAC custom authentication

 

All date and time properties in the requests and responses are set in the ISO 8601 standard: YYYY-MM-DDThh🇲🇲ssZ

All input and output dates and times are set in GMT time zone.

 

 

RG Scheduler API Endpoints

 

Endpoint 1: Schedule a Meeting in Outlook Calendar

This API allows the caller to create meetings on behalf of a certain internal organizer and invite one or multiple internal (in-org) or external attendees. The meeting invite will be sent out to all listed attendees; the requested slot will be reserved as Busy for all participants.

The attendees may accept, decline, or forward a meeting invite to additional attendees. These details can later be read over the meeting data retrieval API (Endpoint 4).

 

API request parameters

Note: All parameters except those marked as (optional) are required

  • TENANT_URL URL of Revenue Grid Tenant allocated for your organization

  • id a non-void alphanumerical value, unique ID of the Meeting in your system. Revenue Grid accepts any identifier here and requires passing of the same identifier to API for any further modifications of the meeting

  • organizerEmail email address of Meeting Organizer

  • attendees the list of Meeting attendee entries:

    • email attendees’ email addresses

    • isRequired defines if an attendee is required or optional: true or false

  • body Body (description) of the Meeting, in plain text format

  • subject Meeting’s subject

  • startTime start date/time of the Meeting in supported format YYYY-MM-ddThh🇲🇲ssZ

  • endTime end date/time of the Meeting in supported format YYYY-MM-ddThh🇲🇲ssZ

  • location location of the Meeting; may include a Zoom or WebEx meeting URL or a room name

Note: for Office 365 users with MS Graph connectivity, you may set the location “MS Teams” to set up a meeting in MS Teams; room link will be auto-generated and appended to meeting Body

  • salesforceCorrelationId (optional) used for telemetry correlation; specify a request ID for end-to-end telemetry tracking

 

Sample request

POST {TENANT_URL}/api/salesforce/scheduler/meeting
Body:
{
    "id": "f9b58255-8e2e-81e2-a6db-27461fa3f11e",
    "organizerEmail": "[email protected]",
    "body": "meeting description",
    "subject": "meeting subject",
    "location": "meeting room 1",
    "startTime": "2020-10-16T10:00:00Z",
    "endTime": "2020-10-20T23:00:00Z",
    "salesforceCorrelationId": "ac7b40b4-2c33-723b-8aaie-8bpf077z7539",
    "attendees": [
        {
            "email": "[email protected]",
            "isRequired": "true",
        },
        {
            "email": "[email protected]",
            "isRequired": "false",
        }
    ]
}

 

Sample response

{
    "email": "[email protected]",
    "errorCode": "NoError"
}
 

 

Endpoint 2: Update a previously created Meeting in Outlook calendar

This API allows updating a meeting previously created over Scheduler API by changing the date, time, meeting attendees list, or other meeting properties.

 

Special notes:

  • All parameters except those marked as (optional) are required

  • The ‘organizerEmail’ parameter cannot be changed later. If you need to modify it: delete the meeting for the original organizer and re-schedule it for another organizer

  • Include in the request only those meeting properties you want to change. Omitted properties will keep their original values

  • Making any changes to a meeting results in update notifications being auto-sent to all attendees. After getting such updates, the attendees will be able to accept or decline the meeting afresh

 

API request parameters

  • TENANT_URL URL of Revenue Grid Tenant allocated for your organization

  • id a non-void alphanumerical value. Unique ID of the Meeting in your system, consistent with one used for the Schedule a Meeting call

  • organizerEmail email address of Meeting Organizer

  • attendees (optional) list of Meeting attendee entries:

  • email attendees’ email addresses

    • isRequired defines if an attendee is required or optional: true or false

    • body (optional) Body (description) of the Meeting, in plain text format

Note: Modifying Body of an existing meeting that was sent as an MS Teams invitation may override the meeting link appended to the Body

  • subject (optional) Meeting’s subject

  • startTime (optional) start date/time of the Meeting in supported format YYYY-MM-ddThh🇲🇲ssZ

  • endTime (optional) end date/time of the Meeting in supported format YYYY-MM-ddThh🇲🇲ssZ

  • location (optional) location of the Meeting; may include a Zoom or WebEx meeting URL or a room name

Note: for Office 365 users with MS Graph connectivity, you may set the location “MS Teams” to set up a meeting in MS Teams; room link will be auto-generated and appended to meeting Body

  • salesforceCorrelationId (optional) used for telemetry correlation; specify a request ID for end-to-end telemetry tracking

 

Sample request

(includes meeting Subject modifying and adding an extra attendee, other properties were left unchanged) 

PATCH {TENANT_URL}/api/salesforce/scheduler/meeting
Body:
{
  "id": "f9b58255-8e2e-81e2-a6db-27461fa3f11e",
  "organizerEmail": "[email protected]",
  "subject": "New subject",
  "salesforceCorrelationId": "ac7b40b4-2c33-723b-8aaie-8bpf077z7539",
  "attendees": [
      {
          "email": "[email protected]",
          "isRequired": "true",
      },
      {
          "email": "[email protected]",
          "isRequired": "false",
      },
      {
          "email": "[email protected]",
          "isRequired": "true",
      }
  ]
}
 

Sample response

{
    "email": "[email protected]",
    "errorCode": "NoError"
}
 

 

Endpoint 3: Delete a Meeting from Outlook calendar

This API allows deleting meetings previously created over Scheduler API.

 

**API request parameters **

  • TENANT_URL URL of Revenue Grid Tenant allocated for your organization

  • id a non-void alphanumerical value. Unique ID of the Meeting in your system, consistent with one used for the Schedule a Meeting call

  • organizerEmail email address of Meeting Organizer

  • salesforceCorrelationId (optional) telemetry correlation, specify a request ID for end-to-end telemetry tracking

 

Sample request

DELETE {TENANT_URL}/api/salesforce/scheduler/meeting
Body:
{
  "id": "f9b54553-8e2a-47r2-a6db-27425fb3f11e",
  "organizerEmail": "[email protected]",
  "salesforceCorrelationId": "1234567—9012-3456-789012345678"
}

 

Sample response

{
  "email": "[email protected]",
  "errorCode": "NoError"
}

 

 

Endpoint 4: Retrieve previously created Meeting’s details from Outlook Calendar

This API allows retrieving meeting details for meetings previously created over Scheduler API, including registered attendee reactions to the Meeting invite: No response, Accepted, Declined.

 

GET string parameters

Note: All parameters except those marked as (optional) are required

  • TENANT_URL URL of Revenue Grid Tenant allocated for your organization

  • id a non-void alphanumerical value. Unique ID of the Meeting in your system, consistent with one used for the Schedule a Meeting call

  • organizerEmail email address of Meeting Organizer

  • salesforceCorrelationId (optional) telemetry correlation added at the end of the query string, specify a request ID for end-to-end telemetry tracking

 

Sample request

GET {TENANT_URL}/api/salesforce/scheduler/meeting?id=f9b58255-8e2e-81e2-a6db-27461fa3f11e&[email protected]&salesforceCorrelationId=ac7b40b4-2c33-723b-8aaie-8bpf077z7539

 

API response parameters

The API response includes the following data retrieved for Meeting attendees.

  • id a non-void alphanumerical value. Unique ID of the Meeting in your system, consistent with one used for the Schedule a Meeting call

  • organizerEmail email address of Meeting Organizer

  • attendees list of Meeting attendee entries:

    • email attendees’ email addresses

    • isRequired defines if an attendee is required or optional: true or false

    • response each attendee’s reaction to the invite: “NoResponseReceived”, “Accepted”, “Declined”, “Tentative”, “Organizer”, or “Unknown”

  • body Body (description) of the Meeting, in plain text format

  • subject Meeting’s subject

  • startTime start date/time of the Meeting in supported format YYYY-MM-ddThh🇲🇲ssZ

  • endTime end date/time of the Meeting in supported format YYYY-MM-ddThh🇲🇲ssZ

  • location location of the Meeting; may include a Zoom or WebEx meeting URL or a room name

 

Sample response: Success

{
  "id": "f9b58255-8e2e-81e2-a6db-27461fa3f11e",
  "organizerEmail": "[email protected]",
  "body": "meeting description",
  "subject": "meeting subject",
  "location": "meeting room 1",
  "startTime": "2020-10-16T10:00:00Z",
  "endTime": "2020-10-20T23:00:00Z",
  "attendees": [
      {
          "email": "[email protected]",
          "isRequired": "true",
          "response": "Accept"
      },
      {
          "email": "[email protected]",
          "isRequired": "false",
          "response": "Decline"
      }
  ]
}

 

Sample response: Error

{  
  "email": "[email protected]",
  "errorCode": "MeetingNotFound"
}
 

 

Endpoint 5: Retrieve attendees’ calendar availability from Outlook Calendars

This call is used to collect occupied slots data from attendees’ calendars in your MS Exchange Organization.

POST query string Parameters

  • TENANT_URL URL of Revenue Grid Tenant allocated for your organization

  • From and To the date-time span to check for occupied slots added at the end of the query string, e.g. from=2020-10-15T00:00:00Z&to=2020-10-17T12:00:00Z

  • salesforceCorrelationId (optional) telemetry correlation added at the end of the query string, specify request ID for end-to-end telemetry tracking

API POST body includes the following property:

  • email email addresses of attendees to retrieve occupied slots for.

Note: this API works only for users from the same MS Exchange Organization

 

Sample request

POST {TENANT_URL}/api/salesforce/scheduler/availability?from=2020-10-15T00:00:00Z&to=2020-10-17T12:00:00Z&salesforceCorrelationId=abcdefg
[
    {
     "email": "[email protected]"
    },
    {
     "email": "[email protected]"
    }
]
 

Sample response

Availability API response includes the following data for every attendee listed in the request:

  • errorCode indicates an error code for troubleshooting, if an error occurred. NoError is displayed if there were no errors; other error indicators are also self-explanatory

  • unavaialbleTimeSlots contains the list of attendee calendars’ unavailable slots, each slot is defined by two parameters:

    • timeMin is the date and time of the start of an occupied span in the attendee’s calendar in supported format YYYY-MM-ddThh🇲🇲ssZ

    • timeMax is the date and time of the end of an occupied span in the attendee’s calendar in supported format YYYY-MM-ddThh🇲🇲ssZ 

[
    {
        "email": "[email protected]",
        "errorCode": "NoError",
        "unavailableTimeslots": [
            {
                "timeMin": "2020-10-16T10:00:00Z",
                "timeMax": "2020-10-16T12:00:00Z",
            },
            {
                "timeMin": "2020-10-16T14:00:00Z",
                "timeMax": "2020-10-16T15:00:00Z",
            },
        ]
    },
    {
        "email": "[email protected]",
        "errorCode": "NoError",
        "unavailableTimeslots": [
            {
                "timeMin": "2020-10-16T10:00:00Z",
                "timeMax": "2020-10-16T16:00:00Z",
            }
        ]
    }
]