logo
API docs by Redocly

DEX APIs (1.0.1 DRAFT)

Download OpenAPI specification:

APIs for external integrators to call SGTraDex for creation of data packages and data exchange.

Introduction

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

The APIs are divided into the following categories:

  • Utilities
  • Folder & Package
  • Data Exchange
  • Simulation APIs (For Test/UAT Environments only)

Utilities

SGTraDex provides the following utility APIs:

Ingress Utility APIs

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

Egress Utility APIs

  • Health Check
  • Notify

Data Package & Folders

In addition to document/data element exchange, SGTraDex provides the capability for you to organize your data using folders, packages, and nodes (milestones and activities).

Folders & Packages

Currently SGTraDex has 2 levels of nodes:

  1. Milestone
  2. Activity
  • Each Folder can contain multiple packages
  • Each Package can contain multiple nodes
  • Each Milestone can contain multiple activities
  • Documents / Data Elements can exist in any level (Package/Milestone/Activity)

The relevant APIs for the Folder, Package, and Node are available in the API specifications in later sections. Folder and Package APIs are available as both ingress and egress calls.

Note: you only need to implement these APIs if you intend to use the folders and package functionality.

Data Exchange

Data Exchange in SGTraDex 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 SGTraDex.
  2. SGTraDex 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. SGTraDex 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 SGTraDex with a PUSH call containing the data payload.
  2. SGTraDex 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.

Simulation APIs

In addition to the above APIs, SGTraDex provides APIs to allow for simulation of data exchange events typically requiring an additional party; e.g. another particiapnt to pull your data or pushing data to you.

As such, there are 2 simulation APIs provided so you can conduct self-service testing without needing a 3rd party:

  • Simulate Provide (system will pull data from your pitstop)
  • Simulate Receive (system will push data to your pitstop)

Note: These Simulation APIs are only available in the TEST and UAT environments, and not available in the Live Production environment.

Ingress & Egress APIs

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

  • Ingress APIs: APIs that your system will call SGTraDex
  • Egress APIs: APIs that SGTraDex 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 SGTraDex, 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 /data/pull/{dataElementId} Request to pull data from provider
PUSH /data/push/{dataElementId} Push data to pitstop
STORE /data/store/{dataElementId} Store data element in pitstop for subsequent use
FORWARD /data/forward/{dataElementId} Forward data existing in pitstop to another participant
SUBSCRIBE /data/subscribe/{dataElementId} Subscribe to data from provider

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 SCHEMAS 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 SGTraDex system.

API uri Description
HEALTH /health Health check to see if pitstop is healthy. Will return 200 if pitstop is healthy.
CONFIG /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 /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 /files/{file_id} Downloads the binary file with the corresponding ID from the pitstop.

Simulation APIs

Ingress Simulation APIs are additional utility APIs provided by SGTraDex system to facilitate self-service testing.
Note: only in TEST and UAT environments

API uri Description
SIMULATE PROVIDE /simulate/provide/{dataElementId} Tells the mock server to initiate a pull of the data element ID with the correct parameters.
SIMULATE RECEIVE /simulate/receive/{dataElementId} Tells the mock server to initiate a push of the data element ID with the correct parameters.

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 SCHEMAS 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.

Egress APIs

Egress APIs are APIs which SGTraDex 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 SCHEMAS 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 SGTraDex 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 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

SGTraDex'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

1.0.1 (DRAFT 23 August 2023)

  • updated status,statusList and milestones as optional fields in folder & data package APIs(INGRESS & EGRESS)

1.0.1 (DRAFT 17 May 2023)

  • added parent node id and type to receive call
  • Fix: on_behalf_of in requestBody should be an object with id and name instead of string.
  • Fix: response for receive calls should include only requestId in the data.
  • Corrected text and examples for requestBody for data/push to state we currently only support 1 payload in array

1.0.1 (DRAFT 27 Apr 2023)

  • tagged /notify as EGRESS Data Exchange category in addition to EGRESS Utility
  • updated diagrams to improve clarity

1.0.1 (DRAFT 20 Apr 2023)

  • added Ingress APIs: /data/pull, /data/store, /data/forward
  • added Egress API: /data/provide
  • added Simulation APIs: /simulate/provide, /simulate/receive
  • added appropriate error responses for each of the data exchange APIs
  • fixed typo updateByName -> updatedByName and updateById -> updatedById

1.0.1 (DRAFT 19 Apr 2023)

  • In /folder and /data-package: updated folder and dataPackage response schemas to align with the request schemas
  • added utility APIs: /health, /notify, /files, /files/{file_id}

1.0.1 (DRAFT 12 Apr 2023)

  • fixed typo for endAfterOccurrences and numberOccurrences
  • fixed incorrect nodeId to correct id in activities and milestones
  • added referenceNumber to milestone and activity levels

1.0.1 (DRAFT 24 Mar 2023)

  • added config API (Ingress Utilities)
  • added sourceSystems in identity, produces, consumes of the config API to provide additional configuration for source systems

1.0.1 (DRAFT 17 Mar 2023)

  • added modified timestamp for node status API
  • removed the response bodies for EGRESS folder and package APIs

1.0.1 (DRAFT 16 Mar 2023)

  • Updated refreshed look for SGTraDex API specifications
  • Combined Ingress and Egress API specifications
  • Includes enhancements to support Veridapt system integrations
  • Reorganized API specifications to separate main APIs from the data element schemas
  • Includes added documentation on Data Packages

1.0.0-release (20 Jun 2022)

  • initial official release of SGTraDex API specifications

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

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

    INGRESS Folder & Package

    Folder & Package related APIs

    Create Folder

    Create a new Folder (aka Deal).
    Response sent will include the newly created folder object with the unique node id.
    The ids can then be used in subsequent calls to update the status or comments of that folder.

    Request Body schema: application/json
    id
    string

    unique id of the folder (Deal) where this data package will reside. Optional for initial creation.

    name
    required
    string

    name of the folder (Deal) where this data package will reside.

    status
    string

    status of the folder (Deal)

    statusList
    Array of strings

    list of possible statuses for this folder (Deal)

    required
    Array of objects (participant)

    an array of the DEX defined ids of the participants involved in this folder (Deal).

    owners
    required
    Array of strings

    an array of the DEX defined organization ids of the participants who are the owners (aka deal leads).
    owners must be included in the list of participants above.

    Responses

    Request samples

    Content type
    application/json
    {
    • "name": "name of the folder (Deal)",
    • "status": "Started",
    • "statusList": [
      ],
    • "participants": [
      ],
    • "owners": [
      ]
    }

    Response samples

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

    Create Data Package

    Create a new Data Package.
    Response sent will include the newly created data package object with the unique ids for each of the nodes (process/milestone/activity).
    The ids can then be used as parent_node_id in subsequent /data/push/ calls to specifty which level the data element should be in.

    Request Body schema: application/json
    id
    string

    unique id of the package (process). Optional for initial creation.

    referenceNumber
    string or null

    reference number that can be used in a data package for referencing business transaction / deal

    name
    required
    string

    Descriptive name of the package (process).

    status
    string

    status of the data package (process)

    statusList
    Array of strings

    list of possible statuses for this data package (process)

    required
    Array of objects (participant)

    an array of the DEX defined ids of the participants involved in this process.

    owners
    required
    Array of strings

    an array of the DEX defined organization ids of the participants who are the owners (aka deal leads) of this process.
    owners must be included in the list of participants above.

    folderId
    required
    string

    the unique identifier for the folder (deal) which the package (process) will reside in.

    Array of objects (dataElement)
    Array of objects (milestone)
    Array of startDate (object) or processDuration (object) or recurrence (object) or variations (object)

    additional information required by Veridapt (passthrough)

    Responses

    Request samples

    Content type
    application/json
    {
    • "referenceNumber": "My transaction/deal reference id",
    • "folderId": "<FOLDER_ID>",
    • "name": "Process Name",
    • "status": "Started",
    • "statusList": [
      ],
    • "participants": [
      ],
    • "owners": [
      ],
    • "dataElements": [
      ],
    • "milestones": [
      ],
    • "additionalInfo": [
      ]
    }

    Response samples

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

    Update Data Package

    Update an existing Data Package.
    Response sent will include the updated data package object with the unique ids for each of the nodes (process/milestone/activity).
    The ids can then be used as parent_node_id in subsequent /data/push/ calls to specifty which level the data element should be in.
    Note that any updates that result in deletion of a mileston/activity will be rejected with error.

    Request Body schema: application/json
    id
    string

    unique id of the package (process). Optional for initial creation.

    referenceNumber
    string or null

    reference number that can be used in a data package for referencing business transaction / deal

    name
    required
    string

    Descriptive name of the package (process).

    status
    string

    status of the data package (process)

    statusList
    Array of strings

    list of possible statuses for this data package (process)

    required
    Array of objects (participant)

    an array of the DEX defined ids of the participants involved in this process.

    owners
    required
    Array of strings

    an array of the DEX defined organization ids of the participants who are the owners (aka deal leads) of this process.
    owners must be included in the list of participants above.

    folderId
    required
    string

    the unique identifier for the folder (deal) which the package (process) will reside in.

    Array of objects (dataElement)
    Array of objects (milestone)
    Array of startDate (object) or processDuration (object) or recurrence (object) or variations (object)

    additional information required by Veridapt (passthrough)

    Responses

    Request samples

    Content type
    application/json
    {
    • "referenceNumber": "My transaction/deal reference id",
    • "folderId": "<FOLDER_ID>",
    • "name": "Process Name",
    • "status": "Started",
    • "statusList": [
      ],
    • "participants": [
      ],
    • "owners": [
      ],
    • "dataElements": [
      ],
    • "milestones": [
      ],
    • "additionalInfo": [
      ]
    }

    Response samples

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

    Update node comment/status

    Update comment or status of a Node (process, milestone or activity) based on the node id.
    Refer to the examples on how to update either status or comment.

    Request Body schema: application/json
    id
    required
    string

    unique identifier for the node (provided during creation time)

    type
    required
    string
    Enum: "FOLDER" "PACKAGE" "MILESTONE" "ACTIVITY"

    type of node. This can be one of the following

  • FOLDER aka Deal
  • PACKAGE aka Process
  • MILESTONE
  • ACTIVITY

    • status
    string

    status for this node. possible values are from the statusList provided during the hierarchy update

    updatedByName
    string

    name for the user requesting of the status

    updatedById
    string

    unique idenfier (email) for the user requsting update of the status

    modified
    string <date-time>

    timestamp for when this status was updated

    Array of objects (comment)

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "id": "<NODE_ID>",
    • "type": "MILESTONE",
    • "status": "Completed",
    • "updatedByName": "John Doe",
    • "updatedById": "user2@email.com"
    }

    Response samples

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

    INGRESS Data Exchange

    Data Exchange related APIs

    PUSH DATA

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

    path Parameters
    dataElementId
    required
    string

    Data Element ID of the data element to be sent

    Request Body schema: application/json
    parent_node_id
    string

    DEX specific identifier of the parent node (process / milestone / activity) for this document (data element).

    parent_node_type
    string
    Enum: "FOLDER" "PACKAGE" "MILESTONE" "ACTIVITY"

    type of node. This can be one of the following

  • FOLDER aka Deal
  • PACKAGE aka Process
  • MILESTONE
  • ACTIVITY

    • subscription_id
    string (Subscription Id)

    Optional field. Generated by system when a the data is received as result of subscription request is made, participant can ignore it when for normal receive

    payload
    required
    Array of objects (Data Element JSON)

    JSON payload of data element documents.
    For details on the payload schema, refer to SCHEMAS section.
    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
    {
    • "parent_node_id": "string",
    • "parent_node_type": "FOLDER",
    • "subscription_id": "string",
    • "payload": [
      ],
    • "requestId": "string",
    • "sourceSystemId": "string",
    • "participants": [
      ],
    • "on_behalf_of": [
      ]
    }

    Response samples

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

    PULL DATA

    Request (PULL) a data element from another participant.

    path Parameters
    dataElementId
    required
    string

    ID of the data element to be requested

    Request Body schema: application/json
    parameters
    required
    Array of objects

    JSON parameters of data element documents.
    For details on the parameter schema, refer to SCHEMAS section.
    Note there can be more than 1 document of the same data element type.

    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
    {
    • "parameters": [
      ],
    • "requestId": "string",
    • "sourceSystemId": "string",
    • "participants": [
      ],
    • "on_behalf_of": [
      ]
    }

    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

    ID of the data element to be stored

    Request Body schema: application/json
    payload
    required
    Array of objects (Data Element JSON)

    JSON payload of data element documents.
    For details on the payload schema, refer to SCHEMAS section.
    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
    {
    • "payload": [
      ],
    • "requestId": "string",
    • "sourceSystemId": "string",
    • "participants": [
      ],
    • "on_behalf_of": [
      ]
    }

    Response samples

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

    FORWARD DATA

    Forward the Data Element to participants

    Request Body schema: application/json
    parameters
    required
    Array of objects

    JSON parameters of data element documents.
    For details on the parameter schema, refer to SCHEMAS section.
    Note there can be more than 1 document of the same data element type.

    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
    {
    • "parameters": [
      ],
    • "requestId": "string",
    • "sourceSystemId": "string",
    • "participants": [
      ],
    • "on_behalf_of": [
      ]
    }

    Response samples

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

    SUBSCRIBE DATA

    Subscribe to a data element from another participant.

    path Parameters
    dataElementId
    required
    string

    ID of the data element to be subscribed to.

    Request Body schema: application/json
    parameters
    required
    Array of objects

    JSON parameters of data element documents.
    For details on the parameter schema, refer to SCHEMAS section.
    Note there can be more than 1 document of the same data element type.

    required
    object

    Detail of the subscription request.

    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
    {
    • "parameters": [
      ],
    • "subscription_detail": {
      },
    • "requestId": "string",
    • "sourceSystemId": "string",
    • "participants": [
      ],
    • "on_behalf_of": [
      ]
    }

    Response samples

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

    INGRESS Simulation

    Data Exchange related APIs for Simulated Self-Service Testing

    SIMULATE PROVIDE

    Tells the mock server to initiate a pull of the data element ID with the correct parameters

    path Parameters
    dataElementId
    required
    string

    ID of the data element to be simulated

    Request Body schema: application/json
    parameters
    required
    Array of objects

    JSON parameters of data element documents.
    For details on the parameter schema, refer to SCHEMAS section.
    Note there can be more than 1 document of the same data element type.

    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
    {
    • "parameters": [
      ],
    • "requestId": "string",
    • "sourceSystemId": "string",
    • "participants": [
      ],
    • "on_behalf_of": [
      ]
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "timestamp": "2022-01-01T12:00:00.000Z",
    • "version": { },
    • "error": {
      }
    }

    SIMULATE RECEIVE

    Tells the mock server to initiate a push of the data element ID with the correct parameters

    path Parameters
    dataElementId
    required
    string

    ID of the data element to be simulated

    Request Body schema: application/json
    Array of objects (participant)
    Array of objects

    Responses

    Request samples

    Content type
    application/json
    {
    • "participants": [
      ],
    • "on_behalf_of": [
      ]
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "timestamp": "2022-01-01T12:00:00.000Z",
    • "version": { },
    • "error": {
      }
    }

    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

    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 Folder & Package

    Folder & Package related APIs

    Create Folder

    Notification of the creation of a new Folder (aka Deal).
    Includes the newly created folder object with the unique node id.
    The ids can then be used in subsequent calls to update the status or comments of that folder.

    Request Body schema: application/json
    id
    string

    unique id of the folder (Deal) where this data package will reside. Optional for initial creation.

    name
    required
    string

    name of the folder (Deal) where this data package will reside.

    status
    string

    status of the folder (Deal)

    statusList
    Array of strings

    list of possible statuses for this folder (Deal)

    required
    Array of objects (participant)

    an array of the DEX defined ids of the participants involved in this folder (Deal).

    owners
    required
    Array of strings

    an array of the DEX defined organization ids of the participants who are the owners (aka deal leads).
    owners must be included in the list of participants above.

    Responses

    Request samples

    Content type
    application/json
    {
    • "id": "<DEX_FOLDER_ID>",
    • "name": "name of the folder (Deal)",
    • "status": "Started",
    • "statusList": [
      ],
    • "participants": [
      ],
    • "owners": [
      ]
    }

    Create Data Package

    Notification of the creation of a new Data Package.
    Includes the unique ids for each of the nodes (process/milestone/activity).
    The ids can then be used as parent_node_id in subsequent /data/push/ calls to specifty which level the data element should be in.

    Request Body schema: application/json
    id
    string

    unique id of the package (process). Optional for initial creation.

    referenceNumber
    string or null

    reference number that can be used in a data package for referencing business transaction / deal

    name
    required
    string

    Descriptive name of the package (process).

    status
    string

    status of the data package (process)

    statusList
    Array of strings

    list of possible statuses for this data package (process)

    required
    Array of objects (participant)

    an array of the DEX defined ids of the participants involved in this process.

    owners
    required
    Array of strings

    an array of the DEX defined organization ids of the participants who are the owners (aka deal leads) of this process.
    owners must be included in the list of participants above.

    folderId
    required
    string

    the unique identifier for the folder (deal) which the package (process) will reside in.

    Array of objects (dataElement)
    Array of objects (milestone)
    Array of startDate (object) or processDuration (object) or recurrence (object) or variations (object)

    additional information required by Veridapt (passthrough)

    Responses

    Request samples

    Content type
    application/json
    {
    • "referenceNumber": "My transaction/deal reference id",
    • "folderId": "<FOLDER_ID>",
    • "id": "<DEX_PACKAGE_ID>",
    • "name": "Process Name",
    • "status": "Started",
    • "statusList": [
      ],
    • "participants": [
      ],
    • "owners": [
      ],
    • "dataElements": [
      ],
    • "milestones": [
      ],
    • "additionalInfo": [
      ]
    }

    Update Data Package

    Update an existing Data Package.
    Response sent will include the updated data package object with the unique ids for each of the nodes (process/milestone/activity).
    The ids can then be used as parent_node_id in subsequent /data/push/ calls to specifty which level the data element should be in.
    Note that any updates that result in deletion of a mileston/activity will be rejected with error.

    Request Body schema: application/json
    id
    string

    unique id of the package (process). Optional for initial creation.

    referenceNumber
    string or null

    reference number that can be used in a data package for referencing business transaction / deal

    name
    required
    string

    Descriptive name of the package (process).

    status
    string

    status of the data package (process)

    statusList
    Array of strings

    list of possible statuses for this data package (process)

    required
    Array of objects (participant)

    an array of the DEX defined ids of the participants involved in this process.

    owners
    required
    Array of strings

    an array of the DEX defined organization ids of the participants who are the owners (aka deal leads) of this process.
    owners must be included in the list of participants above.

    folderId
    required
    string

    the unique identifier for the folder (deal) which the package (process) will reside in.

    Array of objects (dataElement)
    Array of objects (milestone)
    Array of startDate (object) or processDuration (object) or recurrence (object) or variations (object)

    additional information required by Veridapt (passthrough)

    Responses

    Request samples

    Content type
    application/json
    {
    • "referenceNumber": "My transaction/deal reference id",
    • "folderId": "<FOLDER_ID>",
    • "name": "Process Name",
    • "status": "Started",
    • "statusList": [
      ],
    • "participants": [
      ],
    • "owners": [
      ],
    • "dataElements": [
      ],
    • "milestones": [
      ],
    • "additionalInfo": [
      ]
    }

    Update node comment/status

    Update comment or status of a Node (process, milestone or activity) based on the node id.
    Refer to the examples on how to update either status or comment.

    Request Body schema: application/json
    id
    required
    string

    unique identifier for the node (provided during creation time)

    type
    required
    string
    Enum: "FOLDER" "PACKAGE" "MILESTONE" "ACTIVITY"

    type of node. This can be one of the following

  • FOLDER aka Deal
  • PACKAGE aka Process
  • MILESTONE
  • ACTIVITY

    • status
    string

    status for this node. possible values are from the statusList provided during the hierarchy update

    updatedByName
    string

    name for the user requesting of the status

    updatedById
    string

    unique idenfier (email) for the user requsting update of the status

    modified
    string <date-time>

    timestamp for when this status was updated

    Array of objects (comment)

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "id": "<NODE_ID>",
    • "type": "MILESTONE",
    • "status": "Completed",
    • "updatedByName": "John Doe",
    • "updatedById": "user2@email.com"
    }

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

    PROVIDE DATA

    Pitstop requesting Source System to Provide the Data Element to participants

    path Parameters
    dataElementId
    required
    string

    ID of the data element to be provided

    Request Body schema: application/json
    parameters
    required
    Array of objects

    JSON parameters of data element documents.
    For details on the parameter schema, refer to SCHEMAS section.
    Note there can be more than 1 document of the same data element type.

    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
    {
    • "parameters": [
      ],
    • "requestId": "string",
    • "sourceSystemId": "string",
    • "participants": [
      ],
    • "on_behalf_of": [
      ]
    }

    Response samples

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

    RECEIVE DATA

    Add/Update Document (Data Element) to an existing process.
    The parent_node_id is provided in the request body

    path Parameters
    dataElementId
    required
    string

    ID of the data element to be sent

    Request Body schema: application/json
    parent_node_id
    string

    DEX specific identifier of the parent node (process / milestone / activity) for this document (data element).

    parent_node_type
    string
    Enum: "FOLDER" "PACKAGE" "MILESTONE" "ACTIVITY"

    type of node. This can be one of the following

  • FOLDER aka Deal
  • PACKAGE aka Process
  • MILESTONE
  • ACTIVITY

    • subscription_id
    string (Subscription Id)

    Optional field. Generated by system when a the data is received as result of subscription request is made, participant can ignore it when for normal receive

    payload
    required
    Array of objects (Data Element JSON)

    JSON payload of data element documents.
    For details on the payload schema, refer to SCHEMAS section.
    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
    {
    • "parent_node_id": "string",
    • "parent_node_type": "FOLDER",
    • "subscription_id": "string",
    • "payload": [
      ],
    • "requestId": "string",
    • "sourceSystemId": "string",
    • "participants": [
      ],
    • "on_behalf_of": [
      ]
    }

    Response samples

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