Create a New Order

This API is used to create a new order either in draft or distributed mode using specimens sourced from either:

Explicit list of specimens specified in the request.
Specimens cart
Specimens reserved for the DP.

We will cover each of these in below examples:

Distribute specimens specified in the request

URL /openspecimen/rest/ng/distribution-orders

Method POST

Body

{
  "name": "Test Order",
  "distributionProtocol": {
    "shortTitle": "Test DP"
  },
  "requester": { /* either one of the following needs to be specified */
    "id": 3,
    "loginName": "johnd",
    "emailAddress": "johnd@openspecimen.org"
  },
  "siteName": "North Hospital Labs",
  "distributor": {
    "id": 4,
    "loginName": "jannied",
    "emailAddress": "jannied@openspecimen.org"
  },
  "trackingUrl": "https://bluedart.com/openspecimen-orders/1/status",
  "comments": "Free text allowing users to add order notes",
  "status": "EXECUTED",
  "executionDate": 1526267841368,
  "orderItems": [
    {
      "specimen": { /* Specify either ID or (cpShortTitle, label) combination */
        "id": 701,
        "cpShortTitle": "Lung Cancer",
        "label": "LC-0001-V1-P1"
      },
      "quantity": 2,
      "cost": 2.5,
      "status": "DISTRIBUTED_AND_CLOSED"
    },

    /* Other specimens in the order */
  ]  
}

Distribute all specimens of the cart

URL /openspecimen/rest/ng/distribution-orders

Method POST

Body

{
  "name": "Test Order",
  "distributionProtocol": {
    "shortTitle": "Test DP"
  },
  "requester": { /* either one of the following needs to be specified */
    "id": 3,
    "loginName": "johnd",
    "emailAddress": "johnd@openspecimen.org"
  },
  "siteName": "North Hospital Labs",
  "distributor": {
    "id": 4,
    "loginName": "jannied",
    "emailAddress": "jannied@openspecimen.org"
  },
  "trackingUrl": "https://bluedart.com/openspecimen-orders/2/status",
  "comments": "Free text allowing users to add order notes",
  "status": "EXECUTED",
  "executionDate": 1526267841368,
  "specimenList": { /* ID of the cart containing specimens to be distributed */
    "id": 6
  }
}

Distribute all specimens reserved for the DP

URL /openspecimen/rest/ng/distribution-orders

Method POST

Body

{
  "name": "Test Order",
  "distributionProtocol": {
    "shortTitle": "Test DP"
  },
  "requester": { /* either one of the following needs to be specified */
    "id": 3,
    "loginName": "johnd",
    "emailAddress": "johnd@openspecimen.org"
  },
  "siteName": "North Hospital Labs",
  "distributor": {
    "id": 4,
    "loginName": "jannied",
    "emailAddress": "jannied@openspecimen.org"
  },
  "trackingUrl": "https://bluedart.com/openspecimen-orders/3/status",
  "comments": "Free text allowing users to add order notes",
  "status": "EXECUTED",
  "executionDate": 1526267841368,
  "allReservedSpmns": true
}

Response

HTTP Status Code	Description
200	The order is created and is assigned a unique ID. The response body contains the order details along with the unique ID. This unique ID can be used later to update or retrieve the order details.
400	Something incorrect with the request. The response body contains the error code and the human readable error message.
500	Something wrong with the server. Please contact support along with the request payload and exception stack trace.

Request Parameters

Parameter	Description
name	Order name. It should be unique in the system. The order name can be later used to retrieve order details or update the order.
distributionProtocol	ID or short title of the distribution protocol which identifies the project or study to which the specimens are being distributed.
requester	User who requested for the specimens to be distributed. Either ID, login name or email address can be used to uniquely identify the requester.
siteName	An optional attribute identifying the site that will receive the distributed specimens.
distributor	User who is responsible for processing the order. Either ID, login name or email address can be used to uniquely identify the distributor.
trackingUrl	An optional attribute specifying the courier service's tracking URL.
comments	An optional attribute to record additional order notes.
status	Specifies whether the order is in pending mode or distributed. Valid values are PENDING and DISTRIBUTED.
specimenList	If specified, all specimens contained in the cart are distributed. The distributed quantity will be same as specimen available quantity. The cost of specimen will be picked from the DP requirements.
allReservedSpmns	If set to true and specimen cart is not specified then all specimens reserved for the DP are distributed. The distributed quantity will be same as specimen available quantity. The cost of specimen will be picked from the DP requirements
orderItems	When specimenList and allReservedSpmns are not specified, orderItems specifies the list of the specimens to distribute along with their quantities and associated cost. specimen: identifies the specimen to be distributed. User can specify either specimen ID or (cp, label) combination. quantity: quantity of specimen to be distributed cost: cost of distributed specimen status: specifies whether the specimen should be closed on distribution. valid values are DISTRIBUTED, DISTRIBUTED_AND_CLOSED.