Revenue Grid Scheduler API Endpoints¶

10 min read

RG Email Sidebar 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:mm: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:mm:ssZ
endTime end date/time of the Meeting in supported format YYYY-MM-ddThh:mm: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:mm:ssZ
endTime (optional) end date/time of the Meeting in supported format YYYY-MM-ddThh:mm: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:mm:ssZ
endTime end date/time of the Meeting in supported format YYYY-MM-ddThh:mm: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:mm: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:mm: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",
            }
        ]
    }
]

Get back to us
We would love to hear from you