Create Primary Specimen Requirement

This API is used to create a new primary specimen requirement for an anticipated visit of the CP.

URL /openspecimen/rest/ng/specimen-requirements

Method POST

Body

{
  "name": "WB for RBCs",
  "code": "WB-R",
  "specimenClass": "Fluid",
  "type": "Whole Blood",
  "anatomicSite": "Not Specified",
  "laterality": "Not Specified",
  "pathology": "Not Specified",
  "initialQty": 10,
  "concentration": 1.1,
  "collector": {
    "id": 2,
    "emailAddress": "johnd@sample-labs.com"
  },
  "collectionProcedure": "Not Specified",
  "collectionContainer": "EDTA Vacutainer",
  "receiver": {
    "id": 3,
    "emailAddress": "jannied@sample-labs.com"
  },
  "labelFmt": null,
  "cpShortTitle": "TCP",
  "eventLabel": "Baseline"
}

Response

HTTP Status Code	Description
200	The primary specimen requirement is created and is assigned a unique ID. The response body contains the requirement details along with the unique ID. This unique ID can be used later to update, retrieve or create derivatives/aliquots.
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	A logical name assigned by the CP admin to identify the specimens in a collection of identical specimens of the visit. Example - Whole Blood (for RBCs), Whole Blood (for Plasma and Serum)
code	Unique code assigned to the specimen within the event/visit. Useful in generation of specimen labels, generating collection reports, and bulk importing planned specimen records. For this, CP coding setting needs to be enabled.
specimenClass	Specimen class. Fluid, Cell, Molecular, Tissue.
type	Specifies the type of specimen. Example: Whole Blood, Fresh Tissue etc. The value should be one of the allowed values configured in the PV list for specimen type.
anatomicSite	The part of the body from which the specimen was retrieved. Example Cerebrum, Liver etc
laterality	The side of the part from which the specimen was retrieved. Example - Left, Right etc
pathology	Indicates whether the specimen is cancerous. Example - Malignant, Non-Malignant etc
initialQty	Quantity of specimen to be collected. Example: 10 ml of Whole Blood
concentration	Mostly relevant for molecular specimens like DNA, RNA to determine the purity of samples.
collector	User (Nurse) responsible for collecting the specimen from the patient.
collectionProcedure	Procedure adopted to retrieve the specimen from the patient. Example - Lavage, Surgical Resection etc
collectionContainer	Tube/container used for collecting the specimen. Example EDTA Vacutainer, Heparin Vacutainer etc
receiver	User (Technician) responsible for receiving the specimen in lab and processing it into derivatives and aliquots.
cpShortTitle	Collection protocol under which the primary specimen requirement needs to be created
eventLabel	Anticipated visit for which the primary specimen requirement needs to be created.