Revenue Grid Scheduler API Endpoints¶


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.
- Omit
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
, orUnknown
. - Users are considered available if their status is
Free
,Tentative
, orWorking 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
andClientSecret
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 theClientId
andClientSecret
to the API caller. It is the caller’s responsibility to store theClientSecret
in a secure location for future use.
- The
- Use the generated
ClientId
andClientSecret
to construct a client credentials OAuth2 request to the/token
endpoint.- The
scope
parameter must be set touser_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.
- The
- 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"
}