Skip to content

Revenue Grid Scheduler API Endpoints

10 min read · For users on:


Revenue Grid provides API endpoints to enable various apps and services to take advantage of meeting scheduling capabilities. These endpoints support the following scenarios:

  • Parse actual calendar availability from your own or colleagues’ Microsoft Outlook calendars.
  • Perform meeting scheduling in Outlook calendars, including create, update, and delete operations.

Overview

Scheduler API is designed for server-to-server integrations and can operate across all users in a customer’s organization.

Meeting Organizers referenced by this API should be valid Revenue Grid users with properly configured Microsoft 365 or Microsoft Exchange connectivity.

For internal (organization) users, the API can be used to schedule meetings on users’ behalf or retrieve their calendar availability spans.

External users may be referenced only as attendees for the meetings scheduled with this API.

API authorization

Scheduler API supports 2 authorization methods:

  • OAuth2 client credentials flow (preferred)
  • HMAC custom authentication (for single-tenant deployments only)

API conventions

Date and time

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

Organizer mailbox determination

Scheduler API calls operate in the context of a specified organizer mailbox. The mailbox is determined using one of the following methods:

  • For OAuth2 client credentials flow, the calling user is considered the meeting organizer. Their mailbox is used to look up availability, create meetings, and perform related operations.
  • For HMAC server-to-server authentication, the organizer mailbox must be specified in the request header using X-OrganizerMailbox.
X-OrganizerMailbox header format

The X-OrganizerMailbox header value must follow the format {type}:{value}, where:

  • {type} is one of the supported mailbox determination types (must be lowercase).
  • {value} is the identifier used to look up the user.

Important

There must be no spaces between the type, the colon character, and the value.

The following determination types are supported:

Type Description Sample value Notes
email Organizer’s primary email address X-OrganizerMailbox: email:[email protected] Only the primary email address is supported. Alternative aliases are not supported.
crmid Salesforce 18-digit user ID X-OrganizerMailbox: crmid:0058c000009w3DLAAY Use only when your tenant includes users exclusively from the production Salesforce organization (not a sandbox).
crmurl Salesforce Identity URL (learn more) X-OrganizerMailbox: crmurl:https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P Recommended when the tenant includes users from both the production and sandbox Salesforce organizations, as this format ensures accurate identification and separation of users from different environments.

Mailbox determination may fail if the user is not found in Revenue Grid using the provided email address or Salesforce user ID. This may happen if the identifier is incorrect or if the user has not been provisioned.

Email addresses

Attendee email addresses in the Scheduler API can be either primary or alias addresses of internal or external users.

API call correlation for diagnostics

All meeting scheduling API calls support the optional X-CorrelationId header. This header allows the caller to uniquely identify each request. When provided, the API logs the correlation ID along with any related outbound requests to help simplify debugging and troubleshooting by the Revenue Grid team.

Error handling

The API indicates success or failure using standard HTTP status codes.

Success responses
Status code Description
200 OK
204 No Content

Response samples for successful calls are provided in the relevant sections of this document.

Error responses
Status code Description
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
409 Conflict (Microsoft 365/Microsoft Exchange error)
412 Precondition Failed (User misconfiguration)
429 Too Many Requests

For failed calls, the response may include a JSON payload with the following properties:

  • ErrorCode: A machine-readable error code for automated handling.
  • Message: A human-readable description of the error.
ErrorCode values
ErrorCode Description Status code
OrganizerMailboxNotFound The mailbox specified in the X-OrganizerMailbox header was not found. 400
InvalidInput The operation failed due to invalid input parameters. 400
Forbidden The caller does not have permission to perform the operation. 403
MeetingNotFound The meeting identified by the X-OrganizerMailbox header and ID was not found. 404
RetryLater The backend API is temporarily unavailable and cannot process the request. 429

Note

Responses with status code 429 Too Many Requests may include a Retry-After header specifying how many seconds to wait before retrying the request.

API Endpoints

The endpoints are also described in Swagger documentation.

Endpoint 1: Schedule a meeting in Outlook calendar

This API allows the caller to create a meeting on behalf of an internal organizer and invite one or more internal or external attendees:

  • A meeting invite is sent to all listed attendees.
  • The requested time slot is reserved as Busy for all participants.
  • A reminder is set for all participants 15 minutes before the meeting starts.

Attendees can accept, decline, or forward the invite. These responses can be retrieved later using the meeting retrieval API (Endpoint 4).

API request parameters

Parameter Required Description
TENANT_URL Required The URL of your Revenue Grid tenant (e.g., customer.revenuegrid.com).
X-OrganizerMailbox Required Instruction to determine the meeting organizer’s mailbox.
id Required A non-empty, unique alphanumerical ID of the meeting in your system. Must be reused for future updates to the meeting. Note: If the ID is not unique, the result is unpredictable.
attendees Optional A list of meeting attendees. Each attendee object must include:
- email (Required) - The attendee’s email address.
- isRequired (Required) - Indicates whether the attendee is required (true) or optional (false).
body Optional The meeting description, in plain text format.
subject Required The meeting subject line.
startTime Required The meeting start time in ISO 8601 format: YYYY-MM-DDThh:mm:ssZ.
endTime Required The meeting end time in ISO 8601 format: YYYY-MM-DDThh:mm:ssZ.
location Optional The meeting location. Can include a Zoom or WebEx link, a room name, or "MS Teams" (for Microsoft 365 users with MS Graph).

Note

  • For Microsoft 365 users with MS Graph connectivity, setting location to "MS Teams" will auto-generate a Teams link and append it to the meeting body.
  • The meeting organizer is automatically determined by the X-OrganizerMailbox header (for HMAC auth) or by the calling user (for OAuth2). Do not include the organizer as an attendee.

Sample request

POST {TENANT_URL}/sync/scheduler/meeting
Authorization: Bearer XXXX
Content-Type: application/json
Content-Length: XXX
X-OrganizerMailbox: email:[email protected]
X-CorrelationId: ac7b40b4-2c33-723b-8aaie-8bpf077z7539

{
  "id": "f9b58255-8e2e-81e2-a6db-27461fa3f11e",
  "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
    },
    {
      "email": "[email protected]",
      "isRequired": false
    }
  ]
}

Success response

204 No Content

Endpoint 2: Update a previously created meeting in Outlook calendar

This API allows you to update a meeting previously created via the Scheduler API by changing the date, time, attendee list, or other meeting properties.

API request parameters

Parameter Required Description
TENANT_URL Required The URL of your Revenue Grid tenant (e.g., customer.revenuegrid.com).
X-OrganizerMailbox Required Instruction to determine the meeting organizer’s mailbox.
id Required Unique alphanumerical ID of the meeting in your system. Must match the ID used when the meeting was created. Provided in the query string.
subject Optional New subject for the meeting.
body Optional Updated meeting description in plain text.
startTime Optional New start time of the meeting in ISO 8601 format: YYYY-MM-DDThh:mm:ssZ.
endTime Optional New end time of the meeting in ISO 8601 format: YYYY-MM-DDThh:mm:ssZ.
location Optional Updated location. Can include a room name, Zoom or WebEx URL, or "MS Teams" (for Microsoft 365 users with MS Graph).
attendees Optional A list of updated meeting attendees. Each attendee object must include:
- email (Required) - The attendee’s email address.
- isRequired (Required) - Indicates whether the attendee is required (true) or optional (false).

Note

  • The organizer mailbox cannot be changed for an existing meeting. To use a different organizer, delete and re-create the meeting.
  • Include only the properties you want to change; omitted properties remain unchanged.
  • Updating a meeting triggers an update notification to all attendees. They may accept or decline the updated invite.
  • For Microsoft 365 users with MS Graph connectivity, setting location to "MS Teams" will auto-generate a Teams link and append it to the meeting body.
  • Updating the body of an MS Teams meeting replaces the original Teams link.
  • Attendee list behavior:
    • Omit attendees to leave the current list unchanged.
    • Use an empty array ([]) to remove all attendees.
    • Provide a new list to fully replace the existing attendees.

Sample request

This sample updates the subject and attendee list; other properties are unchanged.

PATCH {TENANT_URL}/sync/scheduler/meeting/f9b54553-8e2a-47r2-a6db-27425fb3f11e
Authorization: Bearer XXXX
Content-Type: application/json
Content-Length: XXX
X-OrganizerMailbox: crmid:0058c000009w3DLAAY

{
  "subject": "New subject",
  "attendees": [
    {
      "email": "[email protected]",
      "isRequired": true
    },
    {
      "email": "[email protected]",
      "isRequired": false
    },
    {
      "email": "[email protected]",
      "isRequired": true
    }
  ]
}

Success response

204 No Content

Endpoint 3: Delete a meeting from Outlook calendar

This API allows you to delete a meeting that was previously created using the Scheduler API.

API request parameters

Parameter Required Description
TENANT_URL Required The URL of your Revenue Grid tenant (e.g., customer.revenuegrid.com).
X-OrganizerMailbox Required Instruction to determine the meeting organizer’s mailbox.
id Required Unique alphanumerical ID of the meeting in your system. Must match the ID used when the meeting was created. Provided as part of the query string.

Sample request

DELETE {TENANT_URL}/sync/scheduler/meeting/f9b54553-8e2a-47r2-a6db-27425fb3f11e
Authorization: Bearer XXXX
X-OrganizerMailbox: email:[email protected]

Success response

204 No Content

Endpoint 4: Retrieve previously created meeting’s details from Outlook calendar

This API retrieves details of a meeting previously created via the Scheduler API, including attendee responses such as NoResponseReceived, Accepted, or Declined.

API request parameters

Parameter Required Description
TENANT_URL Required The URL of your Revenue Grid tenant (e.g., customer.revenuegrid.com).
X-OrganizerMailbox Required Instruction to determine the meeting organizer’s mailbox.
id Required Unique alphanumerical ID of the meeting in your system. Must match the ID used when the meeting was created. Provided in the query string.

Sample request

GET {TENANT_URL}/sync/scheduler/meeting/f9b58255-8e2e-81e2-a6db-27461fa3f11e
Authorization: Bearer XXXX
X-OrganizerMailbox: crmid:0058c000009w3DLAAY
X-CorrelationId: ac7b40b4-2c33-723b-8aaie-8bpf077z7539

Success response

200 OK

{
  "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": "Accepted"
    },
    {
      "email": "[email protected]",
      "isRequired": false,
      "response": "Declined"
    }
  ]
}

Response description

The API response includes the following data:

Field Type Description
id String Unique alphanumerical ID of the meeting in your system. Same ID used in the original creation request.
organizerEmail String Email address of the meeting organizer.
body String Description of the meeting, in plain text format.
subject String Subject of the meeting.
location String Location of the meeting. May include a Zoom or WebEx URL, a room name, or "MS Teams" (for Microsoft 365 users with MS Graph).
startTime String Start time of the meeting in ISO 8601 format: YYYY-MM-DDThh:mm:ssZ.
endTime String End time of the meeting in ISO 8601 format: YYYY-MM-DDThh:mm:ssZ.
attendees Array A list of meeting attendees. Each attendee object includes:
- email (String) - The attendee’s email address.
- isRequired (Boolean) - Indicates whether the attendee is required (true) or optional (false).
- response (String) - The attendee’s response: "NoResponseReceived", "Accepted", "Declined", "Tentative", "Organizer", or "Unknown".

Endpoint 5: Retrieve attendees’ calendar availability from Outlook calendars

This API retrieves occupied time slots from calendars of users in your Microsoft 365 or Exchange organization.

API request parameters

Parameter Required Description
TENANT_URL Required The URL of your Revenue Grid tenant (e.g., customer.revenuegrid.com).
X-OrganizerMailbox Required Instruction to determine the meeting organizer’s mailbox.
from , to Required Start and end of the time span to check for occupied slots, added as query string parameters: from=2020-10-15T00:00:00Z&to=2020-10-17T12:00:00Z
attendees Optional A list of updated meeting attendees. Each attendee object must include:
- email (Required) - The attendee’s email address.

Note

  • This API returns availability only for users in the same Microsoft 365 or Exchange organization.
  • The meeting organizer’s availability is included in the response automatically.
  • Time slots are marked as unavailable if the user’s status in Microsoft 365 or Exchange is Busy, Out of Office, or Unknown.
  • Users are considered available if their status is Free, Tentative, or Working Elsewhere.

Sample request

POST {TENANT_URL}/sync/scheduler/availability
Authorization: Bearer XXXX
Content-Type: application/json
Content-Length: XXX
X-OrganizerMailbox: email:[email protected]
X-CorrelationId: ac7b40b4-2c33-723b-8aaie-8bpf077z7539

{
  "from": "2020-10-15T00:00:00Z",
  "to": "2020-10-17T12:00:00Z",
  "attendees": [
    {
      "email": "[email protected]"
    },
    {
      "email": "[email protected]"
    }
  ]
}

Success response

200 OK

[
  {
    "email": "[email protected]",
    "statusCode": "Success",
    "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]",
    "statusCode": "MailboxNotFound",
    "unavailableTimeslots": []
  },
  {
    "email": "[email protected]",
    "statusCode": "Success",
    "unavailableTimeslots": []
  }
]

Response description

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

Field Type Description
email String The email of the attendee or organizer. Matches the email in the request.
statusCode String Indicates an error code, if any, and Success is returned when no error.
unavailableTimeslots Array A list of time slots when the attendee is unavailable. Each object includes:
- timeMin (String) - Start time of an unavailable period in ISO 8601 format: YYYY-MM-DDThh:mm:ssZ.
- timeMax (String) - End time of an unavailable period in ISO 8601 format: YYYY-MM-DDThh:mm:ssZ.

OAuth2 client credentials flow

The OAuth2 client credentials flow allows a caller to authenticate as a user and perform operations on that user’s behalf.

Configuration steps

  1. In your Revenue Grid tenant, the tenant administrator must go to the App integrations section (Settings > Administration > App integrations) to create a named integration and generate a ClientId and ClientSecret for the application.
    • The ClientSecret is valid for up to one year or less, as agreed between the administrator and the API caller.
    • The ClientSecret is displayed only once at the time of creation and is not stored in Revenue Grid. The administrator must securely transfer the ClientId and ClientSecret to the API caller. It is the caller’s responsibility to store the ClientSecret in a secure location for future use.
  2. Use the generated ClientId and ClientSecret to construct a client credentials OAuth2 request to the /token endpoint.
    • The scope parameter must be set to user_id <user-guid> (with a space separator). You can find the <user-guid> on the user’s details page in the Revenue Grid interface. For instructions, see this article.
  3. Use the returned access token to authorize calls to Scheduler API endpoints.
    • Monitor the token’s validity interval and renew it as needed.

Sample request

POST {TENANT_URL}/token
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Content-Length: XXX

grant_type=client_credentials&client_id=XXXX&client_secret=YYYY&scope=user_id%20e9322420-3584-4827-8abb-9e747b4bb21a

Success response

200 OK

{
  "userEmail": "[email protected]",
  "userId": "e9322420-3584-4827-8abb-9e747b4bb21a",
  "organizationId": "308d36e1-d0d3-4f47-90c7-36a5f112f59b",
  "tenantId": "3d9677c2-6a70-4c09-8359-f1dfe016b9aa",
  "instance": "instance url",
  ...
  "issued_at": "2025-05-23T16:21:07.3567824Z",
  "token_type": "bearer",
  "access_token": "XXXXX",
  "expires_in": "7200"
}