BookingSG

Beta Feature: This node is currently in beta. Features and functionality may be subject to changes.

The BookingSG Node allows your workflow to integrate with BookingSG, Singapore Government’s centralized appointment and facility booking platform. It enables you to search and manage bookings programmatically through the BookingSG API.

Prerequisites

Before using the BookingSG Node, ensure the following:

• BookingSG Account — You must have an active BookingSG agency account with API access enabled.
• API Key — You must have a valid BookingSG API key for your usecase. Contact your BookingSG administrator to obtain one.

Important: Please ensure that BookingSG has whitelisted OPUS’ IP addresses.

How Does It Work?

Setup Steps:

1. Build your workflow using Graph Edit Mode (minimum setup: input node → BookingSG node → output node, but you can add more nodes as needed)
2. Click on the BookingSG node settings to open its configuration
3. Select the environment (Staging or Production)
4. Enter your BookingSG API key
5. Select the operation you want to perform and configure the required parameters

Output:

The BookingSG Node returns the response from the BookingSG API. The output structure varies depending on the operation performed.

Search Bookings Output (Service Booking):

{
  "bookingType": "service",
  "id": "ylWEXKQNDX",
  "status": 2,
  "startDateTime": "2026-06-17T18:00:00+08:00",
  "endDateTime": "2026-06-17T19:00:00+08:00",
  "createdAt": "2026-06-08T16:28:28.677864+08:00",
  "updatedAt": "2026-06-08T16:28:43.526881+08:00",
  "fields": [
    { "label": "myinfo-name", "value": "John Doe" },
    { "label": "identifier", "value": "S1234567A" },
    { "label": "myinfo-mobile", "value": "+65 91234567" },
    { "label": "myinfo-email", "value": "john@example.gov.sg" }
  ],
  "service": {
    "id": "rLAWeka3",
    "name": "Service A",
    "loginType": "singpass",
    "usecaseId": "BYy9my4m",
    "usecaseName": "My Usecase"
  }
}Copy to clipboardErrorCopied

Search Bookings Output (Service Group Booking):

{
  "bookingType": "service-group",
  "groupId": "7f1001d2-4910-4eb8-afa7-ae1a44d93272",
  "status": 2,
  "startDateTime": "2026-06-10T13:00:00+08:00",
  "endDateTime": "2026-06-10T14:00:00+08:00",
  "fields": [
    { "label": "myinfo-name", "value": "Jane Doe" },
    { "label": "identifier", "value": "S9876543B" }
  ],
  "bookings": [
    {
      "id": "vmoQAgr9Dl",
      "status": 2,
      "serviceName": "Service A",
      "startDateTime": "2026-06-10T13:00:00+08:00",
      "endDateTime": "2026-06-10T14:00:00+08:00"
    }
  ],
  "serviceGroup": {
    "id": "mVpRZpPJ",
    "name": "Service A + B",
    "loginType": "singpass",
    "usecaseId": "BYy9my4m",
    "usecaseName": "My Usecase"
  }
}Copy to clipboardErrorCopied

Subsequent nodes can access the response data using field names like id, status, startDateTime, fields, service, etc.

Configuration

Connection Settings

Environment

The BookingSG environment you are connecting to.

API Key

Your BookingSG API key that identifies your agency usecase.

Format: Plain text string

Operations

Search Bookings

Searches for bookings using the BookingSG V3 search API. Supports filtering by various criteria including dates, status, service IDs, and custom fields.

Pagination & Sorting

Available Order By Key options:

Filter Mode

Choose how to build your search filters:

Fields Mode Configuration

When using Fields mode, you can configure the following filters:

Service IDs — Filter bookings by one or more service IDs.

Service Group IDs — Filter bookings by one or more service group IDs.

Main Block Filters — Add filter conditions to narrow search results:

Available Filter Keys and Operations:

Booking Status Values:

Additional Blocks — Add grouped filter conditions with AND/OR logic between blocks. Each additional block group contains:

JSON Mode Configuration

When using JSON mode, provide the full options object as a JSON string. This gives you direct control over the query payload sent to the BookingSG API.

Format: Valid JSON object

Example:

{
  "serviceIds": ["rLAWeka3"],
  "mainBlock": [
    {
      "key": "status",
      "value": [2],
      "operation": "IN"
    },
    {
      "key": "startDate",
      "value": ["2026-01-01T00:00:00+08:00"],
      "operation": "gte"
    }
  ]
}Copy to clipboardErrorCopied

Examples

Example 1: Search Active Bookings for a Service

A workflow that searches for all accepted bookings for a specific service, sorted by start date.

Configuration:

Connection:
  Environment: Production
  API Key: your-bookingsg-api-key

Operation: Search Bookings

Parameters:
  Page: 1
  Limit: 20
  Order By Key: startDate
  Order By: DESC
  Filter Mode: Fields
  Service IDs: ["rLAWeka3"]
  Main Block:
    - Key: status, Operation: IN, Value: [2]Copy to clipboardErrorCopied

Output:

{
  "data": [
    {
      "bookingType": "service",
      "id": "ylWEXKQNDX",
      "status": 2,
      "startDateTime": "2026-06-17T18:00:00+08:00",
      "endDateTime": "2026-06-17T19:00:00+08:00",
      "fields": [
        { "label": "myinfo-name", "value": "John Doe" },
        { "label": "identifier", "value": "S1234567A" }
      ],
      "service": {
        "id": "rLAWeka3",
        "name": "Service A"
      }
    }
  ]
}Copy to clipboardErrorCopied

Example 2: Search Bookings by Date Range

A workflow that retrieves bookings within a specific date range using dynamic input values.

Configuration:

Connection:
  Environment: Production
  API Key: your-bookingsg-api-key

Operation: Search Bookings

Parameters:
  Page: 1
  Limit: 50
  Order By Key: startDate
  Order By: ASC
  Filter Mode: Fields
  Main Block:
    - Key: startDate, Operation: >= (gte), Value: {{{input.startDate}}}
    - Key: endDate, Operation: <= (lte), Value: {{{input.endDate}}}
    - Key: status, Operation: IN, Value: [2]Copy to clipboardErrorCopied

Input:

{
  "startDate": "2026-07-01T00:00:00+08:00",
  "endDate": "2026-07-31T23:59:59+08:00"
}Copy to clipboardErrorCopied

Example 3: Search Bookings with Custom Fields Filter

A workflow that searches for bookings where a custom field matches a specific value.

Configuration:

Connection:
  Environment: Staging
  API Key: your-bookingsg-api-key

Operation: Search Bookings

Parameters:
  Page: 1
  Limit: 10
  Order By Key: createdAt
  Order By: DESC
  Filter Mode: Fields
  Main Block:
    - Key: fields, Operation: equal, Value: identifier:S1234567ACopy to clipboardErrorCopied

Example 4: Search Bookings Using JSON Mode

A workflow that uses raw JSON mode for complex queries.

Configuration:

Connection:
  Environment: Production
  API Key: your-bookingsg-api-key

Operation: Search Bookings

Parameters:
  Page: 1
  Limit: 10
  Order By Key: startDate
  Order By: DESC
  Filter Mode: JSON
  Options JSON:
    {
      "serviceIds": ["rLAWeka3", "xYZ123abc"],
      "mainBlock": [
        { "key": "status", "value": [2, 6], "operation": "IN" },
        { "key": "startDate", "value": ["2026-07-01T00:00:00+08:00"], "operation": "gte" }
      ],
      "additionalBlocks": [
        {
          "filterJoin": "OR",
          "blocks": [
            { "key": "fields", "value": ["department:Engineering"], "operation": "equal" },
            { "key": "fields", "value": ["department:Design"], "operation": "equal" }
          ]
        }
      ]
    }Copy to clipboardErrorCopied

Response Handling

Response Handling lets you decide which HTTP status codes returned by BookingSG count as a successful execution of the node. You list the status codes (or ranges) that should be treated as success — everything else is treated as an Error, including network failures and timeouts.

How it works:

• Treat as Success — Add the status codes or ranges that indicate success. When BookingSG responds with one of these, the node completes normally and passes its response to the next node.
• Everything else → Error — Any status code not listed as success (as well as network failures and timeouts) fails the node, which then follows its error path and retry policy.

Configuring the codes:

• Add a code or range — Type a single 3-digit code (e.g. 404) or an inclusive range (e.g. 400-429) and click Add.
• Quick add — Use the shortcut chips (2xx, 3xx, 4xx, 404) to add common patterns instantly.
• Remove — Click the × on any code chip to remove it from the success list.
• Reset to defaults — Restores the default configuration.
• Check a status code — Enter a status code in the tester to preview whether it would resolve to Success or Error with your current configuration.

Default configuration (new nodes):

Tip: Most workflows only need the defaults. Extend the success list when BookingSG returns a non-2xx/3xx code that your workflow should treat as a valid, non-retryable outcome — for example, treating a 4xx client error as a branchable result you handle with a downstream Switch Node.

Older nodes: BookingSG nodes created before this feature was introduced keep their original behaviour (client 4xx codes returned as output, except 429; 429 and 5xx treated as errors) until you first edit and save the Response Handling section.

This is the same Response Handling behaviour available on the API node.

When to Use It?

Use BookingSG Node when:

• You need to search and retrieve bookings from the BookingSG platform within a workflow
• You want to query bookings by status, date range, service, or custom fields
• You are building workflows that react to booking data (e.g., sending reminders, generating reports, triggering follow-up actions)
• You need to integrate booking information with other government systems in an automated workflow