Skip to main content
Version: 2.0.1

Schedule Service API Specification

This page describes how to integrate with the Schedule Service on a technical level.

REST Resources​

The Schedule Service provides a resource for creating and managing schedules.

Scheduled Message​

A scheduled message defines a task that will execute at a specific time or interval. It consists of two main parts: the message payload to be processed and a crontab expression that dictates the schedule. This enables the Banqup platform to trigger automated actions, such as sending notifications or initiating workflows, at predetermined times.

An example of a scheduled message request in JSON format:

{
  "message": {
    "category": "Document",
    "type": "DocumentCreated",
    "data": {
      "relatedDocumentId": "bb23bbff-7326-462f-80bc-4a3c5d66567e"
    }
  },
  "crontab": "0 9 * * *"
}

When this schedule is created, the service will return the full scheduled message object, including its unique ID:

{
  "id": "5f125986-4297-4a9d-b36f-79911b213a65",
  "message": {
    "category": "Document",
    "type": "DocumentCreated",
    "data": {
      "relatedDocumentId": "bb23bbff-7326-462f-80bc-4a3c5d66567e"
    }
  },
  "crontab": "0 9 * * *"
}

The service uses standard crontab expressions for defining schedules, providing flexible and precise control over task execution timing.

Managing Scheduled Messages​

Creating a Scheduled Message​

To create a new message schedule, you'll perform a POST request to the **/core/schedule/v1/scheduledMessages ** endpoint, providing the message payload and crontab expression in the request body.

For example, to schedule a DocumentCreated message:

POST /v1/scheduledMessages
Content-Type: application/json

{
  "message": {
    "category": "Document",
    "type": "DocumentCreated",
    "data": {
      "relatedDocumentId": "bb23bbff-7326-462f-80bc-4a3c5d66567e"
    }
  },
  "crontab": "0 9 * * *"
}

A successful response (HTTP 201 Created) will return the newly created scheduled message object, including its unique id.

Retrieving Scheduled Messages​

You can retrieve a list of all existing message schedules or fetch a specific one by its ID.

For example, to retrieve a specific schedule:

GET /v1/scheduledMessages/5f125986-4297-4a9d-b36f-79911b213a65

A successful response (HTTP 200 OK) will return the full scheduled message object.

Updating a Scheduled Message​

To update an existing schedule, perform a PUT request to **/core/schedule/v1/scheduledMessages/:scheduledMessageId **, providing the full, updated scheduled message object in the request body.

For example, to change the crontab for an existing schedule:

PUT /v1/scheduledMessages/5f125986-4297-4a9d-b36f-79911b213a65
Content-Type: application/json

{
  "message": {
    "category": "Document",
    "type": "DocumentCreated",
    "data": {
      "relatedDocumentId": "bb23bbff-7326-462f-80bc-4a3c5d66567e"
    }
  },
  "crontab": "0 9 * * *"
}

A successful update will return an HTTP 200 OK response with the updated object.

Deleting a Scheduled Message​

To delete a message schedule, perform a DELETE request to **/core/schedule/v1/scheduledMessages/:scheduledMessageId **.

DELETE /v1/scheduledMessages/5f125986-4297-4a9d-b36f-79911b213a65

A successful deletion will return an HTTP 204 No Content response.

Security​

Access to create, retrieve, update, and delete scheduled messages is controlled by the schedule_manage security scope. All requests to the Scheduled Message API must be authenticated using an OAuth security scheme. The provided token must meet two conditions:

  1. It must include the schedule_manage scope to authorize the request itself.
  2. It must be eligible for impersonation, allowing the Schedule Service to use it in a Token Exchange flow to access other services as the user.

Authentication​

Security Scheme Type:

oauth2

OAuth Flow (clientCredentials):

Scopes:

  • info: Scopes are endpoint-specific, see each endpoint for required scope.

OAuth Flow (authorizationCode):

Scopes:

  • info: Scopes are endpoint-specific, see each endpoint for required scope.