logo
API docs by Redocly

SGBuildex APIs

Download OpenAPI specification:Download

APIs for external integrators to call SGBuildex for creation of data exchange.

INTRODUCTION

SGBuildex provides a common set of APIs for integrating with pitstops.

The APIs are divided into the following categories:

  • Data Exchange
  • Utilities

API CATEGORIES

Data Exchange

Data Exchange in SGBuildex happens in an asynchronous fashion.
You can either request for data from another participant (PULL) or send data directly to another participant (PUSH).

Requesting for Data

Requesting Data

When requesting for data, the following are the sequence of events described by the diagram:

  1. Consuming source system sends a PULL request to consuming pitstop (Pitstop A) on SGBuildex.
  2. SGBuildex forwards the call from consuming pitstop to the destination pitstop.
  3. Provider pitstop requests for the data from the provider source system by calling the provider source system with a PROVIDE call. If available, the provider source system will respond with the requested data payload.
  4. SGBuildex encrypts and forwards the encrypted data payload back to the consuming pitstop.
  5. Consuming pitstop calls the consuming source system with a RECEIVE call with the data payload.
  6. Consuming pitstop calls the consuming source system with a NOTIFY call to let the consuming source system know of the success/failure of the PULL request.

Sending Data

Sending Data

When sending data, the following are the sequence of events described by the diagram:

  1. Provider source system calls provider pitstop (Pitstop A) in SGBuildex with a PUSH call containing the data payload.
  2. SGBuildex encrypts and forwards the data payload to the consuming pitstop (Pitstop B).
  3. Consuming pitstop calls the consuming source system with a RECEIVE call with the data payload.
  4. The result of the push is forwarded back to the provider pitstop
  5. Provider pitstop calls the provider source system with a NOTIFY call to let the provider source system know of the success/failure of the PUSH request.

Utilities

SGBuildex provides the following utility APIs:

Ingress Utility APIs

  • Health Check
  • Pitstop Config
  • Upload File(s)
  • File Download

Egress Utility APIs

  • Health Check
  • Notify

INGRESS/EGRESS APIs

To integrate successfully to SGBuildex, there are 2 types of APIs:

  • Ingress APIs: APIs that your system will call SGBuildex
  • Egress APIs: APIs that SGBuildex will call your system
    Note: your system will need to provide these APIs for integration to be successful.

Ingress APIs

Ingress APIs are APIs provided by SGBuildex, and which your system will need to call.

Data Exchange APIs

Data Exchange APIs are used for sending and requesting for data. These are:

API uri Description
PULL /api/v1/data/pull/{dataElementId} Request to pull data from provider
PUSH /api/v1/data/push/{dataElementId} Push data to pitstop
STORE /api/v1/data/store/{dataElementId} Store data element in pitstop for subsequent use
FORWARD /api/v1/data/forward/{dataElementId} Forward data existing in pitstop to another participant

Each of the APIs will take in a dataElementId path parameter to denote the Data Element type of the transaction. The Data Element type will determine the payload and parameters attributes in your request/responses (see specifications in each API for details).

Data Element types are defined based on the use case they are in. Each use case defines the schema for the Data Elements.

Utility APIs

Ingress Utility APIs are additional utility APIs provided by SGBuildex system.

API uri Description
HEALTH /api/v1/health Health check to see if pitstop is healthy. Will return 200 if pitstop is healthy.
CONFIG /api/v1/config This will return the list of Data Elements / documents that your pitstop is configured to produce and consume, as well as the recipients that you have consented to share them with.
UPLOAD FILES /api/v1/files Uploads file(s) to the pitstop Uploads the files in multipart format to the pitstop and return references to each of them for use to send the data.
DOWNLOAD FILE /api/v1/files/{file_id} Downloads the binary file with the corresponding ID from the pitstop.

Egress APIs

Egress APIs are APIs which SGBuildex pitstop will call your system.
Note: your system will need to provide these APIs for integration to be successful.

Data Exchange APIs

Data Exchange APIs are used for sending and receiving for data.

API uri Description
PROVIDE /data/provide/{dataElementId} Request for source system to provide data
RECEIVE /data/receive/{dataElementId} Receive data from pitstop
NOTIFY /notify Notification from pitstop on the success/failure of previous request

Each of the APIs will take in a dataElementId path parameter to denote the Data Element type of the transaction. The Data Element type will determine the payload and parameters attributes in your request/responses (see specifications in each API for details).

Data Element types are defined based on the use case they are in. Each use case defines the schema for the Data Elements.

Utility APIs

Egress Utility APIs are additional utility APIs which SGBuildex pitstop will call your system.

API uri Description
HEALTH /health Pitstop will call source system to check if source system is healthy.
NOTIFY /notify Notification from pitstop on the success/failure of previous request

SCHEMAS

The payload and parameters attributes in the various data exchange APIs are available in the payload sections of the individual APIs. However, if you need to refer to them in detail, see below:

CLICK HERE for the payload and parameters schemas for the various use cases.

VERSIONING

This section mentions all information related to versioning.

Releases and Compatibility

Releases

SGBuildex's RESTful API adopts Semantic Versioning 2.0.0 for releases with the following format:

{MAJOR}.{MINOR}.{PATCH}

The table below lists the possible changes to the release version numbers and what they imply.

{MAJOR} increments {MINOR} increments {PATCH} increments
Introduces incompatible API changes with the previous {MAJOR} version Introduces new functionalities or information that are backward compatible Introduces bug fixes and remains backward compatible
e.g. v1.2.1 --> v2.0.0 e.g. v1.2.1 --> v1.3.0 e.g. v1.2.1 --> v1.2.2

Despite backward compatibility provided in {MINOR} and {PATCH} releases, developers should still ensure that their existing implementations are not disrupted as a result of these new releases.

Pre-releases/Drafts

Pre-release or draft versions, when provided, are denoted by an appended hypen- with a series of separate identifiers {LABEL}-{VERSION} following the{PATCH} number.

{MAJOR}.{MINOR}.{PATCH}-{LABEl}-{VERSION}

Such releases are unstable and may not provide the intended compatibility with the specification in draft status.

Release Notes

0.0.1 (DRAFT 2 October 2023)

  • new draft specs for SGBuildex

0.1.0 (DRAFT 5 Mar 2025)

  • combined schemas into main specifications page for easy reference.

0.1.1 (DRAFT 5 Mar 2025)

  • remove simulate for now as it is not in use.

0.1.2 (DRAFT 6 Mar 2025)

  • cleanup references

INGRESS Utilities

Utility APIs

Pitstop Config

This will return the list of documents that your pitstop is configured to produce and consume, as well as the recipients that you have consented to share them with.

Responses

Response samples

Content type
application/json
{
  • "identity": {
    },
  • "produces": [
    ],
  • "consumes": [
    ],
  • "contributes": [
    ]
}

Health Check

For the Participant / Pitstop to monitor whether their Pitstop / Source System is operational or not. Should return a 200 if it is working.
Note:

  • For INGRESS (i.e. hosted by Pitstop), returns 200 if pitstop is healthy.
  • For EGRESS (i.e. hosted by source system), pitstop will call to check if source system is healthy.

    • Responses

    Health Check

    For the Participant / Pitstop to monitor whether their Pitstop / Source System is operational or not. Should return a 200 if it is working.
    Note:

  • For INGRESS (i.e. hosted by Pitstop), returns 200 if pitstop is healthy.
  • For EGRESS (i.e. hosted by source system), pitstop will call to check if source system is healthy.

    • Responses

    Upload File(s)

    Uploads file(s) to the pitstop Uploads the files in multipart format to the pitstop and return references to each of them for use to send the data.

    Request Body schema: multipart/form-data
    object

    Any key with the file as the value will all be read

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    File Download

    Downloads the binary file with the corresponding ID from the pitstop.

    path Parameters
    file_id
    required
    string

    Responses

    Response samples

    Content type
    application/json
    {
    • "timestamp": "2019-08-24T14:15:22Z",
    • "data": "string"
    }

    Generate Presigned URL

    Generates and returns a presigned S3 URL for uploading an attachment. The URL is valid for 15 minutes (900 seconds). The response includes headers that must be included when uploading to S3.

    Bulk Upload Flow

    Important Notes:

    • S3 Key: The S3 key is automatically generated and embedded in the presigned URL path. It follows the format {original-filename}-{uuid}.{extension} (e.g., test-document-5mb-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.pdf). You need this s3 key to be replaced under file_content field inside attachments when you are using the push API.

    • Required Headers: When uploading to S3 using the presigned URL, you must include all headers returned in the headers object of this response. These headers are pre-signed and must match exactly, including:

      • Content-Length: Must match the exact file size in bytes
      • Content-Type: Must match the MIME type specified in the request
      • Host: The S3 bucket endpoint
      • X-Amz-Meta-*: Custom metadata headers for tracking and security validation

    • Upload Method: Use HTTP PUT to upload the file directly to the presigned URL with the binary file content as the request body.

    Request Body schema: application/json
    fileName
    required
    string

    The name of the file to be uploaded with extension.

    fileSize
    required
    integer

    The exact file size in bytes (maximum 200MB or 200,000,000 bytes).

    contentType
    required
    string

    The MIME type of the file (e.g., application/pdf, image/jpeg, application/msword).

    Responses

    Request samples

    Content type
    application/json
    {
    • "fileName": "test-document-5mb.pdf",
    • "fileSize": 5242880,
    • "contentType": "application/pdf"
    }

    Response samples

    Content type
    application/json
    {}

    Upload File to S3

    Uploads a file to S3 using the presigned URL obtained from the /api/v1/attachments/presigned-url endpoint. This is Step 3 of the bulk upload workflow. The presigned URL and required headers are provided in the response from the presigned URL endpoint.

    AWS S3 Presigned URL Documentation
    query Parameters
    X-Amz-Algorithm
    required
    string
    Example: X-Amz-Algorithm=AWS4-HMAC-SHA256

    AWS signature algorithm (provided in presigned URL).

    X-Amz-Credential
    required
    string
    Example: X-Amz-Credential=ASIAQC4KLVIDVOD63YHQ/20251127/ap-southeast-1/s3/aws4_request

    AWS credential scope (provided in presigned URL).

    X-Amz-Date
    required
    string
    Example: X-Amz-Date=20251127T085047Z

    Request timestamp (provided in presigned URL).

    X-Amz-Expires
    required
    integer
    Example: X-Amz-Expires=900

    URL expiration time in seconds (provided in presigned URL).

    X-Amz-Security-Token
    required
    string
    Example: X-Amz-Security-Token=IQoJb3JpZ2luX2VjENH...

    AWS security token for temporary credentials (provided in presigned URL).

    X-Amz-SignedHeaders
    required
    string
    Example: X-Amz-SignedHeaders=content-length;content-type;host;x-amz-meta-pitstop_host;x-amz-meta-pitstop_id;x-amz-meta-security_check_status

    Headers included in signature (provided in presigned URL).

    x-id
    required
    string
    Example: x-id=PutObject

    The S3 operation identifier (provided in presigned URL).

    X-Amz-Signature
    required
    string
    Example: X-Amz-Signature=e39cd18dfa31c87d801e54b4218f61f01010466d8137c1774e61865f7d705fae

    Request signature (provided in presigned URL).

    header Parameters
    Content-Length
    required
    integer
    Example: 10705702

    The exact file size in bytes. Must match the fileSize used when generating the presigned URL.

    Content-Type
    required
    string
    Example: application/pdf

    The MIME type of the file being uploaded. Must match the contentType used when generating the presigned URL.

    X-Amz-Meta-Pitstop_host
    required
    string
    Example: demo2preprod-sgbuildex.pitstop.pre-prod.dextech.ai

    Pitstop host metadata (from presigned URL response headers).

    X-Amz-Meta-Pitstop_id
    required
    string <uuid>
    Example: aec437b6-30bd-454e-936c-54462af05b03

    Pitstop ID metadata (from presigned URL response headers).

    X-Amz-Meta-Security_check_status
    required
    string
    Example: PENDING

    Security check status metadata (from presigned URL response headers).

    Request Body schema:

    The binary file content to upload.

    string <binary>

    Responses

    INGRESS Data Exchange

    Data Exchange related APIs

    PUSH DATA

    Add a document of specified Data Element type into an existing data package to participants.
    Created document_id will be returned in the response body.

    path Parameters
    dataElementId
    required
    string
    Enum: "lift_datahub" "piling_installation_record" "ultimate_load_test" "working_load_test" "concrete_cube_test_contractor" "concrete_cube_test_laboratory" "steel_element_test" "steel_rebar_test" "site_progress" "qualified_person_site_supervisor_attendance" "manpower_utilization" "manpower_distribution" "erss_approval" "monitoring_of_building_settlement" "notification_to_commissioner_of_building_control" "project_document"

    Data Element ID of the data element to be sent

    Request Body schema: application/json
    required
    Array of Lift Datahub (object) or Piling Installation Record (object) or Ultimate Load Test (object) or Working Load Test (object) or Concrete Cube Test (Contractor) (object) or Concrete Cube Test (Laboratory) (object) or Steel Element Test (object) or Steel Rebar Test (object) or Site Progress (object) or Qualified Person and Site Supervisor Attendance (object) or Manpower Utilization (object) or Manpower Distribution (object) or ERSS Approval (object) or Monitoring of Building Settlement (object) or Notification to Commissioner of Building Control (object) or Project Document (object) (Data Element JSON)

    JSON payload of data element documents.
    Must be one of the defined dataElementId types as per below.
    See the examples.
    Note currently only supports 1 payload in the array

    requestId
    string

    Optional field. Include if you know the requestId for your resource.
    requestId - Unique ID generated for the request

    sourceSystemId
    string (Source System Id)

    Optional field. Own Source System's Id for Notification. Participant can ignore it when flow is anything other than PUSH or PULL.

    required
    Array of objects (participant)
    Array of objects

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "participants": [
      ],
    • "payload": [
      ],
    • "requestId": "string",
    • "on_behalf_of": [
      ],
    • "sourceSystemId": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "timestamp": "2019-08-24T14:15:22Z",
    • "data": {
      }
    }

    STORE DATA

    Store the Data Element in the pitstop for future retrieval

    path Parameters
    dataElementId
    required
    string
    Enum: "lift_datahub" "piling_installation_record" "ultimate_load_test" "working_load_test" "concrete_cube_test_contractor" "concrete_cube_test_laboratory" "steel_element_test" "steel_rebar_test" "site_progress" "qualified_person_site_supervisor_attendance" "manpower_utilization" "manpower_distribution" "erss_approval" "monitoring_of_building_settlement" "notification_to_commissioner_of_building_control" "project_document"

    ID of the data element to be stored

    Request Body schema: application/json
    required
    Array of Lift Datahub (object) or Piling Installation Record (object) or Ultimate Load Test (object) or Working Load Test (object) or Concrete Cube Test (Contractor) (object) or Concrete Cube Test (Laboratory) (object) or Steel Element Test (object) or Steel Rebar Test (object) or Site Progress (object) or Qualified Person and Site Supervisor Attendance (object) or Manpower Utilization (object) or Manpower Distribution (object) or ERSS Approval (object) or Monitoring of Building Settlement (object) or Notification to Commissioner of Building Control (object) or Project Document (object) (Data Element JSON)

    JSON payload of data element documents.
    Must be one of the defined dataElementId types as per below.
    See the examples.
    Note currently only supports 1 payload in the array

    requestId
    string

    Optional field. Include if you know the requestId for your resource.
    requestId - Unique ID generated for the request

    sourceSystemId
    string (Source System Id)

    Optional field. Own Source System's Id for Notification. Participant can ignore it when flow is anything other than PUSH or PULL.

    required
    Array of objects (participant)
    Array of objects

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "participants": [
      ],
    • "payload": [
      ],
    • "requestId": "string",
    • "on_behalf_of": [
      ],
    • "sourceSystemId": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "data": [
      ]
    }

    LIST FAILED REQUEST IDS

    List request IDs of messages that previously failed delivery to the receiver's system across all data element types. The returned requestIds can be used with /api/v1/data/fetch/{requestId} to retrieve the original payload(s) that were sent in the corresponding push/pull request. Note: The request IDs returned are limited by the platform's data retention period or 1 month, whichever is shorter. This endpoint supports a limit query parameter to cap the number of request IDs returned. The default is 50 and the maximum allowed is 200. It also supports a skip parameter to fetch the next slice after the previous call. Use skip = previous skip + previous limit to page. Results are sorted by most recent failure first. The response includes data.remaining, which indicates how many additional request IDs remain beyond this page, and data.nextSkip, a suggested value for the next skip parameter. Continue paging by increasing skip until data.remaining is 0 to fetch all available request IDs.

    query Parameters
    skip
    integer >= 0
    Default: 0

    Number of request IDs to skip from the start of the result set (default 0).

    limit
    integer [ 1 .. 200 ]
    Default: 50

    Maximum number of request IDs to return (default 50, max 200).

    Responses

    Response samples

    Content type
    application/json
    {
    • "timestamp": "2019-08-24T14:15:22Z",
    • "data": {
      }
    }

    FETCH PAYLOAD BY REQUEST ID

    Retrieve the original payload(s) corresponding to a request by its requestId, regardless of whether previous delivery attempts failed. The JSON array returned mirrors the payload array in the original PUSH/PULL request. Note: requestIds that are fetched will no longer be reflected in the List Failed Request IDs API and availability of the requestId and its original payload(s) is limited by the platform's data retention period.

    path Parameters
    requestId
    required
    string <uuid>

    Request ID to retrieve payload(s) for.

    Responses

    Response samples

    Content type
    application/json
    [
    • "<JSON_DATA_PAYLOAD_1",
    • "<JSON_DATA_PAYLOAD_2>",
    • "<JSON_DATA_PAYLOAD_3>"
    ]

    EGRESS Utilities

    Utility APIs

    Health Check

    For the Participant / Pitstop to monitor whether their Pitstop / Source System is operational or not. Should return a 200 if it is working.
    Note:

  • For INGRESS (i.e. hosted by Pitstop), returns 200 if pitstop is healthy.
  • For EGRESS (i.e. hosted by source system), pitstop will call to check if source system is healthy.

    • Responses

    Health Check

    For the Participant / Pitstop to monitor whether their Pitstop / Source System is operational or not. Should return a 200 if it is working.
    Note:

  • For INGRESS (i.e. hosted by Pitstop), returns 200 if pitstop is healthy.
  • For EGRESS (i.e. hosted by source system), pitstop will call to check if source system is healthy.

    • Responses

    Notify Changes

    This endpoint will be used to notify participant with status message as well as about the config changes. This will return the notification of the message and config changes.

    Request Body schema: application/json
    timestamp
    required
    string (Timestamp)

    Date and Time of the request sent/received

    notify_message
    required
    string (Notify Message)
    Enum: "REFRESH_CONFIG" "PUSH_FAIL" "PUSH_SUCCESS" "PULL_FAIL"

    REFRESH_CONFIG | PUSH_FAIL | PULL_FAIL | PUSH_SUCCESS

    notify_message_stage
    string or null (Notify Message Stage)
    Enum: "PITSTOP" "SOURCE"

    PITSTOP | SOURCE

    request_id
    string or null (Request Id)

    Original request from source or pitstop from which the request is originated

    error_code
    number or null (Error Code)

    Internal error code from DEX Pitstop

    error_message
    string or null (Error Mesage)

    Internal error message from DEX Pitstop

    (Source System Error (string or null)) or (Source System Error (object or null)) (Source System Error)

    This field captures and relays the exact error message returned by the API consumer system. No additional processing or classification is performed on this field, ensuring that the error information is relayed exactly as received from the API consumer system.

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "timestamp": "2021-05-11T03:35:38.464Z",
    • "notify_message": "PUSH_FAIL",
    • "request_id": "d4002d09-f0d7-4258-8428-0032fd8d2f52",
    • "error_code": 500,
    • "error_message": "Consumer source API error",
    • "source_system_error": { }
    }

    Response samples

    Content type
    application/json
    {
    • "timestamp": "string"
    }

    EGRESS Data Exchange

    Data Exchange related APIs

    Notify Changes

    This endpoint will be used to notify participant with status message as well as about the config changes. This will return the notification of the message and config changes.

    Request Body schema: application/json
    timestamp
    required
    string (Timestamp)

    Date and Time of the request sent/received

    notify_message
    required
    string (Notify Message)
    Enum: "REFRESH_CONFIG" "PUSH_FAIL" "PUSH_SUCCESS" "PULL_FAIL"

    REFRESH_CONFIG | PUSH_FAIL | PULL_FAIL | PUSH_SUCCESS

    notify_message_stage
    string or null (Notify Message Stage)
    Enum: "PITSTOP" "SOURCE"

    PITSTOP | SOURCE

    request_id
    string or null (Request Id)

    Original request from source or pitstop from which the request is originated

    error_code
    number or null (Error Code)

    Internal error code from DEX Pitstop

    error_message
    string or null (Error Mesage)

    Internal error message from DEX Pitstop

    (Source System Error (string or null)) or (Source System Error (object or null)) (Source System Error)

    This field captures and relays the exact error message returned by the API consumer system. No additional processing or classification is performed on this field, ensuring that the error information is relayed exactly as received from the API consumer system.

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "timestamp": "2021-05-11T03:35:38.464Z",
    • "notify_message": "PUSH_FAIL",
    • "request_id": "d4002d09-f0d7-4258-8428-0032fd8d2f52",
    • "error_code": 500,
    • "error_message": "Consumer source API error",
    • "source_system_error": { }
    }

    Response samples

    Content type
    application/json
    {
    • "timestamp": "string"
    }

    RECEIVE DATA

    Add/Update Document (Data Element) to an existing process.

    path Parameters
    dataElementId
    required
    string
    Enum: "lift_datahub" "piling_installation_record" "ultimate_load_test" "working_load_test" "concrete_cube_test_contractor" "concrete_cube_test_laboratory" "steel_element_test" "steel_rebar_test" "site_progress" "qualified_person_site_supervisor_attendance" "manpower_utilization" "manpower_distribution" "erss_approval" "monitoring_of_building_settlement" "notification_to_commissioner_of_building_control" "project_document"

    ID of the data element to be sent

    Request Body schema: application/json
    required
    Array of Lift Datahub (object) or Piling Installation Record (object) or Ultimate Load Test (object) or Working Load Test (object) or Concrete Cube Test (Contractor) (object) or Concrete Cube Test (Laboratory) (object) or Steel Element Test (object) or Steel Rebar Test (object) or Site Progress (object) or Qualified Person and Site Supervisor Attendance (object) or Manpower Utilization (object) or Manpower Distribution (object) or ERSS Approval (object) or Monitoring of Building Settlement (object) or Notification to Commissioner of Building Control (object) or Project Document (object) (Data Element JSON)

    JSON payload of data element documents.
    Must be one of the defined dataElementId types as per below.
    See the examples.
    Note currently only supports 1 payload in the array

    requestId
    string

    Optional field. Include if you know the requestId for your resource.
    requestId - Unique ID generated for the request

    sourceSystemId
    string (Source System Id)

    Optional field. Own Source System's Id for Notification. Participant can ignore it when flow is anything other than PUSH or PULL.

    required
    Array of objects (participantFrom)
    Array of objects

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "participants": [
      ],
    • "payload": [
      ],
    • "requestId": "string",
    • "on_behalf_of": [
      ],
    • "sourceSystemId": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "timestamp": "2019-08-24T14:15:22Z",
    • "data": {
      }
    }