Jump to

• Request
• Response
• Examples

Retrieve Clinical Specimen for Specimen Identifiers

get

/ohfapi/cg/v3.3/{apiContext}/clinicalspecimens

This endpoint supports the retrieval of a Paginated List of Clinical Specimens for none or multiple Clinical Specimen row IDs. It returns Clinical Specimens information like Clinical Specimen Status, Type, Subtype, Number, Accession Identifier or Specimen Number, Specimen Vendor Number, Collection details including Collection date/time, Collection method, Collection anatomical site and Collection quantity, Clinical Specimen Size, Weight, Cut Thickness and some other Clinical Specimen associated information.

Request

Supported Media Types

• application/json
• application/xml

Path Parameters

• apiContext: string
  Pattern: subjectapi|patientapi

  Patient/Subject API context

Query Parameters

• id(optional): array
  Collection Format: multi

  Patient/Subject Clinical Specimen Row IDs

  • [0]: integer(int64)

  {
      "name":"id",
      "in":"query",
      "description":"Patient/Subject Clinical Specimen Row IDs",
      "required":false,
      "type":"array",
      "items":{
          "type":"integer",
          "format":"int64"
      },
      "collectionFormat":"multi"
  }

• limit(optional): integer(int32)
  Pagination query params: ?limit=2&offset=0
• offset(optional): integer(int32)
  Pagination query params: ?limit=2&offset=0

Security

• basicAuth: basic
  Type: basic

Back to Top

Response

Supported Media Types

• application/json
• application/xml

200 Response

successful operation

Body ()

Root Schema : PageableCollectionClinicalSpecimen

Type: object

Model for paginated collections of data.

Show Source

• count(optional): integer(int64)
  Number of objects in the 'items' collection.
• hasMore(optional): boolean
  A boolean indicating if more pages are available.
• items(optional): array items
  A collection of paged items.
• links(optional): array links
  A collection of links containing hrefs to the current, next, and previous pages as applicable.
• resourceType(optional): string
  Identify the resource type

{
    "type":"object",
    "properties":{
        "resourceType":{
            "type":"string",
            "description":"Identify the resource type"
        },
        "items":{
            "type":"array",
            "xml":{
                "wrapped":true
            },
            "description":"A collection of paged items.",
            "items":{
                "$ref":"#/definitions/ClinicalSpecimen"
            }
        },
        "count":{
            "type":"integer",
            "format":"int64",
            "description":"Number of objects in the 'items' collection."
        },
        "hasMore":{
            "type":"boolean",
            "description":"A boolean indicating if more pages are available."
        },
        "links":{
            "type":"array",
            "example":"{rel: 'next',href: '/patientapi/patients?limit=100&offset=300'}",
            "xml":{
                "wrapped":true
            },
            "description":"A collection of links containing hrefs to the current, next, and previous pages as applicable.",
            "items":{
                "type":"string"
            }
        }
    },
    "description":"Model for paginated collections of data."
}

Nested Schema : items

Type: array

A collection of paged items.

Show Source

• Array of: object ClinicalSpecimen
  Model for a Clinical Specimen object in CDM.

{
    "type":"array",
    "xml":{
        "wrapped":true
    },
    "description":"A collection of paged items.",
    "items":{
        "$ref":"#/definitions/ClinicalSpecimen"
    }
}

Nested Schema : links

Type: array

A collection of links containing hrefs to the current, next, and previous pages as applicable.

Show Source

• Array of: string

{
    "type":"array",
    "example":"{rel: 'next',href: '/patientapi/patients?limit=100&offset=300'}",
    "xml":{
        "wrapped":true
    },
    "description":"A collection of links containing hrefs to the current, next, and previous pages as applicable.",
    "items":{
        "type":"string"
    }
}

Example:

{rel: 'next',href: '/patientapi/patients?limit=100&offset=300'}

Nested Schema : ClinicalSpecimen

Type: object

Model for a Clinical Specimen object in CDM.

Show Source

• accessionIdentifier(optional): string
  The Clinical Specimen identifier.
• biospecimenIdentifier(optional): string
  Biospecimen Identifier.
• collection(optional): object Collection
  Model for a Clinical Specimen Collection details object in CDM.
• cutThicknessUnitOfMeasure(optional): object Coding
  Model for a reference to a code defined by a terminology system.
• expirationDate(optional): string(date-time)
  The Clinical Specimen expiration date and time.
• identifier(optional): object Identifier
  Identifier assigned by a given system
• maximumCutThickness(optional): string
  The Clinical Specimen maximum Cut Thickness.
• mininumCutThickness(optional): string
  The Clinical Specimen mininum Cut Thickness.
• obtainedQuantityUnitOfMeasure(optional): object Coding
  Model for a reference to a code defined by a terminology system.
• patient(optional): object LinkedReference
• patientconditions(optional): object LinkedReference
• patientprocedure(optional): string
  Reference link to the procedure
• patientprocedures(optional): object LinkedReference
• receivedDate(optional): string(date-time)
  The Clinical Specimen received date and time.
• resourceType(optional): string
  API resource type. it's included if Response is not paginated.
• sentDate(optional): string(date-time)
  The Clinical Specimen sent date and time.
• sizeUnitOfMeasure(optional): object Coding
  Model for a reference to a code defined by a terminology system.
• specCollectionProcId(optional): string
  Clinical Specimen Collection Procedure Identifier.
• specimenFinalWeight(optional): string
  The Clinical Specimen Final Weight.
• specimenHeight(optional): string
  The Clinical Specimen Height.
• specimenInitialWeight(optional): string
  The Clinical Specimen Initial Weight.
• specimenIntermediateWeight(optional): string
  The Clinical Specimen Intermediate Weight.
• specimenLength(optional): string
  The Clinical Specimen Length.
• specimenObtainedQuantity(optional): string
  The Clinical Specimen Obtained Quantity.
• specimenPrepType(optional): object CodeableConcept
  Model that represents a value as a reference to one or more terminologies or ontologies or defined by the provision of text.
• specimenReportIdentifier(optional): string
  Clinical Specimen Report Identifier.
• specimenStorageStatus(optional): object CodeableConcept
  Model that represents a value as a reference to one or more terminologies or ontologies or defined by the provision of text.
• specimenVendorNumber(optional): string
  The Clinical Specimen Vendor identifier.
• specimenWidth(optional): string
  The Clinical Specimen Width.
• status(optional): object Coding
  Model for a reference to a code defined by a terminology system.
• subject(optional): object LinkedReference
• subtype(optional): object CodeableConcept
  Model that represents a value as a reference to one or more terminologies or ontologies or defined by the provision of text.
• type(optional): object CodeableConcept
  Model that represents a value as a reference to one or more terminologies or ontologies or defined by the provision of text.
• weightUnitOfMeasure(optional): object Coding
  Model for a reference to a code defined by a terminology system.

{
    "type":"object",
    "properties":{
        "resourceType":{
            "type":"string",
            "description":"API resource type. it's included if Response is not paginated."
        },
        "identifier":{
            "description":"Clinical Specimen Row ID.",
            "$ref":"#/definitions/Identifier"
        },
        "status":{
            "description":"The Clinical Specimen status details, i.e. status code, name, description etc.",
            "$ref":"#/definitions/Coding"
        },
        "type":{
            "description":"The Clinical Specimen type details, i.e. type code, name, description etc.",
            "$ref":"#/definitions/CodeableConcept"
        },
        "subtype":{
            "description":"The Clinical Specimen subtype details, i.e. subtype code, name, description etc.",
            "$ref":"#/definitions/CodeableConcept"
        },
        "accessionIdentifier":{
            "type":"string",
            "description":"The Clinical Specimen identifier."
        },
        "specimenVendorNumber":{
            "type":"string",
            "description":"The Clinical Specimen Vendor identifier."
        },
        "sentDate":{
            "type":"string",
            "format":"date-time",
            "description":"The Clinical Specimen sent date and time."
        },
        "receivedDate":{
            "type":"string",
            "format":"date-time",
            "description":"The Clinical Specimen received date and time."
        },
        "expirationDate":{
            "type":"string",
            "format":"date-time",
            "description":"The Clinical Specimen expiration date and time."
        },
        "collection":{
            "description":"The Clinical Specimen Collection details, i.e. collection date and time, method, body site, and quantity.",
            "$ref":"#/definitions/Collection"
        },
        "specimenLength":{
            "type":"string",
            "description":"The Clinical Specimen Length."
        },
        "specimenWidth":{
            "type":"string",
            "description":"The Clinical Specimen Width."
        },
        "specimenHeight":{
            "type":"string",
            "description":"The Clinical Specimen Height."
        },
        "sizeUnitOfMeasure":{
            "description":"The Clinical Specimen Size unit of measure (UOM) details, i.e. UOM code, name, description etc.",
            "$ref":"#/definitions/Coding"
        },
        "mininumCutThickness":{
            "type":"string",
            "description":"The Clinical Specimen mininum Cut Thickness."
        },
        "maximumCutThickness":{
            "type":"string",
            "description":"The Clinical Specimen maximum Cut Thickness."
        },
        "cutThicknessUnitOfMeasure":{
            "description":"The Clinical Specimen Cut Thickness unit of measure (UOM) details, i.e. UOM code, name, description etc.",
            "$ref":"#/definitions/Coding"
        },
        "specimenInitialWeight":{
            "type":"string",
            "description":"The Clinical Specimen Initial Weight."
        },
        "specimenIntermediateWeight":{
            "type":"string",
            "description":"The Clinical Specimen Intermediate Weight."
        },
        "specimenFinalWeight":{
            "type":"string",
            "description":"The Clinical Specimen Final Weight."
        },
        "weightUnitOfMeasure":{
            "description":"The Clinical Specimen Weight unit of measure (UOM) details, i.e. UOM code, name, description etc.",
            "$ref":"#/definitions/Coding"
        },
        "specimenObtainedQuantity":{
            "type":"string",
            "description":"The Clinical Specimen Obtained Quantity."
        },
        "obtainedQuantityUnitOfMeasure":{
            "description":"The Clinical Specimen Obtained Quantity unit of measure (UOM) details, i.e. UOM code, name, description etc..",
            "$ref":"#/definitions/Coding"
        },
        "biospecimenIdentifier":{
            "type":"string",
            "description":"Biospecimen Identifier."
        },
        "specimenReportIdentifier":{
            "type":"string",
            "description":"Clinical Specimen Report Identifier."
        },
        "specCollectionProcId":{
            "type":"string",
            "description":"Clinical Specimen Collection Procedure Identifier."
        },
        "specimenPrepType":{
            "description":"Clinical Specimen Preparation Type.",
            "$ref":"#/definitions/CodeableConcept"
        },
        "specimenStorageStatus":{
            "description":"Clinical Specimen Storage Status.",
            "$ref":"#/definitions/CodeableConcept"
        },
        "patientprocedure":{
            "type":"string",
            "description":"Reference link to the procedure"
        },
        "subject":{
            "description":"Reference link to the subject",
            "$ref":"#/definitions/LinkedReference"
        },
        "patient":{
            "description":"Reference link to the patient",
            "$ref":"#/definitions/LinkedReference"
        },
        "patientconditions":{
            "description":"Reference link to the conditions",
            "$ref":"#/definitions/LinkedReference"
        },
        "patientprocedures":{
            "description":"Reference link to the procedures",
            "$ref":"#/definitions/LinkedReference"
        }
    },
    "description":"Model for a Clinical Specimen object in CDM."
}

Nested Schema : Collection

Type: object

Model for a Clinical Specimen Collection details object in CDM.

Show Source

• bodySite(optional): object CodeableConcept
  Model that represents a value as a reference to one or more terminologies or ontologies or defined by the provision of text.
• collectedDateTime(optional): string(date-time)
  The Clinical Specimen collection date and time.
• method(optional): object Coding
  Model for a reference to a code defined by a terminology system.
• quantity(optional): object Quantity
  Model for a Quantity object in CDM.

{
    "type":"object",
    "properties":{
        "collectedDateTime":{
            "type":"string",
            "format":"date-time",
            "description":"The Clinical Specimen collection date and time."
        },
        "method":{
            "description":"Technique used to perform collection, i.e. collection method code, name , description, etc.",
            "$ref":"#/definitions/Coding"
        },
        "bodySite":{
            "description":"Anatomical collection site details, i.e. anatomical collection site code, name, description, etc.",
            "$ref":"#/definitions/CodeableConcept"
        },
        "quantity":{
            "description":"The quantity of specimen collected, i.e. collection quantity value, units name, code, description, etc.",
            "$ref":"#/definitions/Quantity"
        }
    },
    "description":"Model for a Clinical Specimen Collection details object in CDM."
}

Nested Schema : Coding

Type: object

Model for a reference to a code defined by a terminology system.

Show Source

• code(optional): string
  Symbol in syntax defined by the system.
• description(optional): string
  Description defined by the system.
• display(optional): string
  Representation defined by the system.
• srvcProviderId(optional): string
  Service Provider Id of Specimen Alias .
• srvcProviderName(optional): string
  Service Provider Name of Specimen Alias .
• sysId(optional): string
  Identity of the terminology system.
• sysName(optional): string
  Name of the terminology system.
• sysVersion(optional): string
  Version of the system - if relevant.

{
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"Symbol in syntax defined by the system."
        },
        "display":{
            "type":"string",
            "description":"Representation defined by the system."
        },
        "description":{
            "type":"string",
            "description":"Description defined by the system."
        },
        "sysId":{
            "type":"string",
            "description":"Identity of the terminology system."
        },
        "sysName":{
            "type":"string",
            "description":"Name of the terminology system."
        },
        "sysVersion":{
            "type":"string",
            "description":"Version of the system - if relevant."
        },
        "srvcProviderId":{
            "type":"string",
            "description":"Service Provider Id of Specimen Alias ."
        },
        "srvcProviderName":{
            "type":"string",
            "description":"Service Provider Name of Specimen Alias ."
        }
    },
    "description":"Model for a reference to a code defined by a terminology system."
}

Nested Schema : Identifier

Type: object

Identifier assigned by a given system

Show Source

• system(optional): string
  System which assigned this identifier
• value(optional): string
  Identifier value

{
    "type":"object",
    "properties":{
        "system":{
            "type":"string",
            "description":"System which assigned this identifier"
        },
        "value":{
            "type":"string",
            "description":"Identifier value"
        }
    },
    "description":"Identifier assigned by a given system"
}

Nested Schema : LinkedReference

Type: object

Show Source

• display(optional): string
• reference(optional): string

{
    "type":"object",
    "properties":{
        "reference":{
            "type":"string"
        },
        "display":{
            "type":"string"
        }
    }
}

Nested Schema : CodeableConcept

Type: object

Model that represents a value as a reference to one or more terminologies or ontologies or defined by the provision of text.

Show Source

• coding(optional): array coding
  Read Only: true

  Code(s) defined by a terminology system.
• text(optional): string
  Plain text representation of the concept.

{
    "type":"object",
    "properties":{
        "text":{
            "type":"string",
            "description":"Plain text representation of the concept."
        },
        "coding":{
            "type":"array",
            "description":"Code(s) defined by a terminology system.",
            "readOnly":true,
            "items":{
                "xml":{
                    "name":"coding"
                },
                "$ref":"#/definitions/Coding"
            }
        }
    },
    "description":"Model that represents a value as a reference to one or more terminologies or ontologies or defined by the provision of text."
}

Nested Schema : Quantity

Type: object

Model for a Quantity object in CDM.

Show Source

• code(optional): string
  The quantity units symbol in syntax defined by the system.
• description(optional): string
  The quantity units description.
• sysId(optional): string
  The quantity units terminology system identifier.
• sysName(optional): string
  The quantity units terminology system name.
• sysVersion(optional): string
  The quantity units terminology system version.
• units(optional): string
  The quantity units displayable name.
• value(optional): string
  The numerical value of the quantity.

{
    "type":"object",
    "properties":{
        "value":{
            "type":"string",
            "description":"The numerical value of the quantity."
        },
        "units":{
            "type":"string",
            "description":"The quantity units displayable name."
        },
        "code":{
            "type":"string",
            "description":"The quantity units symbol in syntax defined by the system."
        },
        "description":{
            "type":"string",
            "description":"The quantity units description."
        },
        "sysId":{
            "type":"string",
            "description":"The quantity units terminology system identifier."
        },
        "sysName":{
            "type":"string",
            "description":"The quantity units terminology system name."
        },
        "sysVersion":{
            "type":"string",
            "description":"The quantity units terminology system version."
        }
    },
    "description":"Model for a Quantity object in CDM."
}

Nested Schema : coding

Type: array

Read Only: true

Code(s) defined by a terminology system.

Show Source

• Array of: object Coding
  Model for a reference to a code defined by a terminology system.

{
    "type":"array",
    "description":"Code(s) defined by a terminology system.",
    "readOnly":true,
    "items":{
        "xml":{
            "name":"coding"
        },
        "$ref":"#/definitions/Coding"
    }
}

400 Response

Invalid parameters supplied

404 Response

Specimen(s) not found

Back to Top

Examples

The following example submits a GET request.

API URL ??? Subject Context

http://localhost:7010/ohfapi/cg/v3.3/subjectapi/clinicalspecimens?id=1&id=2

Example of Response Body

The following example shows the response returned in JSON format.

{
  "resourceType": "Specimen",
  "items": [
    {
      "identifier": {
        "system": "CDM",
        "value": "1"
      },
      "status": {
        "code": "1",
        "display": "N/A1"
      },
      "type": {
        "coding": [
          {
            "code": "1",
            "display": "SP1",
            "description": "SP1Name",
            "sysId": "EHA_CUSTOM_CD_SYS",
            "sysName": "EHA Custom Code System",
            "sysVersion": "1"
          }
        ]
      },
      "subtype": {
        "coding": [
          {
            "code": "1",
            "display": "N/A1"
          }
        ]
      },
      "accessionIdentifier": "HG000_1",
      "specimenVendorNumber": "vendor2",
      "collection": {
        "collectedDateTime": "01/01/1998",
        "method": {
          "code": "1",
          "display": "N/A1"
        },
        "bodySite": {
          "coding": [
            {
              "code": "ANA_SITE_CD_CODE1",
              "display": "ANA_SITE_CD_CODE1name",
              "description": "ANA_SITE_CD_CODE1Desc",
              "sysId": "EHA_CUSTOM_CD_SYS",
              "sysName": "EHA Custom Code System",
              "sysVersion": "1"
            }
          ]
        },
        "quantity": {
          "value": "50",
          "units": "cm",
          "code": "1",
          "description": "centi meter",
          "sysId": "1",
          "sysName": "UOM code",
          "sysVersion": "UOM version"
        }
      },
      "specimenLength": "0.2",
      "specimenWidth": "0.1",
      "specimenHeight": "0.05",
      "sizeUnitOfMeasure": {
        "code": "1",
        "display": "cm",
        "description": "centi meter",
        "sysId": "1",
        "sysName": "UOM code",
        "sysVersion": "UOM version"
      },
      "mininumCutThickness": "0.0005",
      "maximumCutThickness": "0.0008",
      "cutThicknessUnitOfMeasure": {
        "code": "1",
        "display": "cm",
        "description": "centi meter",
        "sysId": "1",
        "sysName": "UOM code",
        "sysVersion": "UOM version"
      },
      "specimenInitialWeight": "0.005",
      "specimenIntermediateWeight": "0.003",
      "specimenFinalWeight": "0.001",
      "weightUnitOfMeasure": {
        "code": "1",
        "display": "cm",
        "description": "centi meter",
        "sysId": "1",
        "sysName": "UOM code",
        "sysVersion": "UOM version"
      },
      "subject": {
        "reference": "/ohfapi/cg/v3.3/subjectapi/subjects/1"
      }
    },
    {
      "identifier": {
        "system": "CDM",
        "value": "2"
      },
      "status": {
        "code": "1",
        "display": "N/A1"
      },
      "type": {
        "coding": [
          {
            "code": "2",
            "display": "SP2",
            "description": "SP2Name",
            "sysId": "EHA_CUSTOM_CD_SYS",
            "sysName": "EHA Custom Code System",
            "sysVersion": "1"
          }
        ]
      },
      "subtype": {
        "coding": [
          {
            "code": "1",
            "display": "N/A1"
          }
        ]
      },
      "accessionIdentifier": "HG000_2",
      "specimenVendorNumber": "vendor2",
      "collection": {
        "collectedDateTime": "01/01/1998",
        "method": {
          "code": "1",
          "display": "N/A1"
        },
        "bodySite": {
          "coding": [
            {
              "code": "ANA_SITE_CD_CODE1",
              "display": "ANA_SITE_CD_CODE1name",
              "description": "ANA_SITE_CD_CODE1Desc",
              "sysId": "EHA_CUSTOM_CD_SYS",
              "sysName": "EHA Custom Code System",
              "sysVersion": "1"
            }
          ]
        },
        "quantity": {
          "value": "50",
          "units": "cm",
          "code": "1",
          "description": "centi meter",
          "sysId": "1",
          "sysName": "UOM code",
          "sysVersion": "UOM version"
        }
      },
      "specimenLength": "0.07",
      "specimenWidth": "0.05",
      "specimenHeight": "0.03",
      "sizeUnitOfMeasure": {
        "code": "1",
        "display": "cm",
        "description": "centi meter",
        "sysId": "1",
        "sysName": "UOM code",
        "sysVersion": "UOM version"
      },
      "mininumCutThickness": "0.00005",
      "maximumCutThickness": "0.00008",
      "cutThicknessUnitOfMeasure": {
        "code": "1",
        "display": "cm",
        "description": "centi meter",
        "sysId": "1",
        "sysName": "UOM code",
        "sysVersion": "UOM version"
      },
      "specimenInitialWeight": "1.008",
      "specimenIntermediateWeight": "1.003",
      "specimenFinalWeight": "1",
      "weightUnitOfMeasure": {
        "code": "1",
        "display": "cm",
        "description": "centi meter",
        "sysId": "1",
        "sysName": "UOM code",
        "sysVersion": "UOM version"
      },
      "subject": {
        "reference": "/ohfapi/cg/v3.3/subjectapi/subjects/1"
      }
    }
  ],
  "count": 2,
  "hasMore": false,
  "links": [
    {
      "rel": "self",
      "href": "/ohfapi/cg/v3.3/subjectapi/clinicalspecimens?id=1&id=2"
    }
  ]
}

Back to Top