Skip to main content

Introduction to the Data API

InterSystems Supply Chain Orchestrator™ provides an APIOpens in a new tab for creating, updating, deleting, and retrieving data. This page provides an introduction to this API.

API URL Patterns

All the API calls follow the same URL pattern:



  • The {{IRIS-SERVER}} part is the server information of the InterSystems IRIS® instance. In a locally deployed server, it may look like http://localhost:52773

  • The {{DATAMODEL-PATH}} part is the API base URL, such as /api/scdata/v1

  • The OBJECT_PATH part is simply the object name in lower case plural form, such as salesorders or customers. See the table below for all object values.

  • The first URL pattern gets data for an object, or searches for objects using a set of parameters. Any attributes of the object can be used in a search criterion.

  • The second URL pattern creates a new object record. The body of the request should include the JSON string for the new object.

  • The third URL pattern retrieves, updates, or deletes an object record by its uid (which is the external primary key).

Some examples:

  • Finding all sales orders with status Open or PartialShip:

    GET {{IRIS-SERVER}}/{{DATAMODEL-PATH}}/salesorders?orderStatus=Open,PartialShip 
  • Creating a new customer:

    POST {{IRIS-SERVER}}/{{DATAMODEL-PATH}}/customers 

    with the following JSON in the request body:

        "uid" : "CUST-TEST-101",
        "name" : "Google",
        "type" : "HighTech",
        "contact" : "Ming",
        "url" : ""
  • Retrieving a supply shipment record with uid value SUP-SHIP-1001:

    GET {{IRIS-SERVER}}/{{DATAMODEL-PATH}}/supplyshipments/SUP-SHIP-1001
  • Updating a location record:


    with new location JSON data in the request body.

Sorting of Results

When more than one record is returned by an API call, you can define the order of the response data by specifying the sorting parameter sortBy. The value of this parameter must be a comma-separated list of attribute names of the primary object returned.

For example, the following API call defines how a list of orders should be sorted in the response:

GET /salesorders?sortBy=customer,orderValue

which defines the sorting to be first by customer, and then by order value.

By default, sorting is done in ascending order. To change the order to descending, use the - sign before the attribute name, such as the following example, which first sorts by customer in ascending order, and then by orderValue in descending order:

GET  /salesorders?sortBy=customer,-orderValue

Default Sorting

If no sorting parameter is provided in the request URL, a default sorting is applied, based on the primary object returned. The following table lists the default sorting parameters for each object type:

Object URL path Default sorting attributes
Carrier carriers name
Customer customers name
Supplier suppliers name
Product products name
Location locations locationName
BillOfMaterial billofmaterials productId, parentItemId
InventoryThreshold inventorythresholds siteLocationId, productId
Milestone milestones ID
ProductInventory productinventories siteLocationId, productId
ProductSupplier productsuppliers productId
SupplyPlan supplyplans locationId, productId
DemandPlan demandplans locationId, productId
SalesOrder salesorders -orderPlacedDate
SalesOrderLine salesorderlines orderId, lineNumber
SalesShipment salesshipments -actualShipDate
SalesShipmentLine salesshipmentlines shipmentId, lineNumber
PurchaseOrder purchaseorders -orderPlacedDate
PurchaseOrderLine purchaseorderlines orderId, lineNumber
SupplyShipment supplyshipments -actualShipDate
SupplyShipmentLine supplyshipmentlines shipmentId, lineNumber
ManufacturingOrder manufacturingorders -orderEntryDate

Pagination of Results

By default, any API call that returns multiple records returns the first 100 records that match the given criteria. You use pagination parameters to obtain additional records or a larger set of records. The pagination parameters give you the control needed to, for example, populate a table in a web UI, without excess resource consumption (memory, network bandwidth, and so on) or performance issues.

The pagination parameters are as follows:

  • pageSize. This parameter defines the maximum number of record returned in the API call. The actual number of records returned can be less or equal to this value. The default value is 100, and the maximum allowed value is 1000.

  • pageIndex. This parameter specified the page index (starting from 0), to be returned in the response. The default is 0.

For example, the following API call skips the first 200 orders and returns the next 100 orders, sorted by order value:

GET  /salesorders?sortBy=orderValue&pageSize=100&pageIndex=2

When a response returns only partial records using pagination, the following HTTP header parameters are populated in the response. Use these values to control the pagination logic in the UI.

  • pageSize. The same value if specified in the request path parameter. Returns the default value if not explicitly specified in the request.

  • pageIndex. The same value if specified in the request path parameter. Returns the default value if not explicitly specified in the request.

  • returnCount. Number of records returned in the current response. This value is less than or equal to pageSize

Date and Date/Time Formats

For any date or date/time attribute, you must specify the value in ISO 8601 format, whether you provide this in the message JSON body or in the HTTP parameter.

Here are some examples. For date attributes:


For date/time attributes (the following two values are equivalent):


If the time zone information is missing, the UTC time is assumed. For example, 2021-05-24T08:30:00 is treated the same as 2021-05-24T08:30:00Z

See Also

FeedbackOpens in a new tab