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¶

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.
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.
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"
}