Specimen

Overview

The Specimen resource represents a sample taken from a biological entity for testing, examination, or analysis. This includes blood samples, tissue samples, urine samples, and other biological materials collected for diagnostic purposes within the Payer Patient Access API.

Supported Profiles:

• US Core Specimen Profile

Use Cases:

• Query for specimens collected from a specific patient
• Track specimen collection and processing information
• Link specimens to laboratory results and diagnostic reports
• Support claims processing and coverage decisions

Relationships:

• Patient: References the individual from whom the specimen was collected
• DiagnosticReport: Links to laboratory results based on the specimen
• Coverage: Associated insurance coverage for specimen collection

Resource Schema

Key Fields:

Field	Type	Description	Required
id	string	Unique identifier for the resource	Yes
status	code	Specimen status (available, unavailable, unsatisfactory, entered-in-error)	No
type	CodeableConcept	Kind of material that forms the specimen	No
subject	Reference(Patient)	Where the specimen came from	Yes
collection	BackboneElement	Collection details	No
collection.collectedDateTime	dateTime	Collection time	No
collection.collector	Reference(Practitioner/PractitionerRole)	Who collected the specimen	No
collection.method	CodeableConcept	Technique for collection	No
collection.bodySite	CodeableConcept	Anatomical collection site	No

JSON Example:

{
    "resourceType": "Specimen",
    "id": "example",
    "meta": {
        "lastUpdated": "2022-08-19T13:58:00.000+00:00"
    },
    "status": "available",
    "type": {
        "coding": [
            {
                "system": "http://snomed.info/sct",
                "code": "119297000",
                "display": "Blood specimen"
            }
        ]
    },
    "subject": {
        "reference": "Patient/example"
    },
    "collection": {
        "collectedDateTime": "2022-08-19T08:30:00.000Z",
        "collector": {
            "reference": "Practitioner/example"
        },
        "method": {
            "coding": [
                {
                    "system": "http://snomed.info/sct",
                    "code": "28520004",
                    "display": "Venipuncture"
                }
            ]
        },
        "bodySite": {
            "coding": [
                {
                    "system": "http://snomed.info/sct",
                    "code": "49852007",
                    "display": "Structure of median cubital vein"
                }
            ]
        }
    }
}

Operations

Read

Retrieve a specific specimen by ID.

Production

GET /Specimen/{id}

Example Request

curl -X GET https://fhir.netsmartcloud.com/payer/patient-access/v2/{tenant-id}/Specimen/specimen-123 \
    -H "Accept: application/fhir+json"

Preview

GET /Specimen/{id}

Example Request

curl -X GET https://fhirtest.netsmartcloud.com/payer/patient-access/v2/{tenant-id}/Specimen/specimen-123 \
    -H "Accept: application/fhir+json"

Search

Search for specimens using various criteria.

GET Method

Use GET for simple searches with parameters in the query string.

Production

GET /Specimen?parameter=value

Preview

GET /Specimen?parameter=value

POST Method

Use POST for complex searches with form-encoded parameters.

Production

POST /Specimen/_search

Preview

POST /Specimen/_search

Search Parameters

Patient-based Search:

Parameter	Type	Required	Description	Example
patient	reference	Yes	The patient the specimen comes from	patient=Patient/patient-123
_lastUpdated	date	No	Only return resources which were last updated as specified by the given range	_lastUpdated=ge2022-01-01

ID-based Search:

Parameter	Type	Required	Description	Example
_id	string	No	The ID of the resource	_id=specimen-123
_lastUpdated	date	No	Only return resources which were last updated as specified by the given range	_lastUpdated=ge2022-01-01

Common Search Patterns

Find specimens by patient:

GET /Specimen?patient=Patient/patient-123&_count=10

Search by specimen ID:

GET /Specimen?_id=specimen-123

Find recent specimens:

GET /Specimen?patient=Patient/patient-123&_lastUpdated=ge2022-01-01

Examples

Request Examples

Production

Search by patient

curl -X POST https://fhir.netsmartcloud.com/payer/patient-access/v2/{tenant-id}/Specimen/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "patient=Patient/patient-123&_count=10"

Search by ID

curl -X POST https://fhir.netsmartcloud.com/payer/patient-access/v2/{tenant-id}/Specimen/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "_id=specimen-123"

Preview

Search by patient

curl -X POST https://fhirtest.netsmartcloud.com/payer/patient-access/v2/{tenant-id}/Specimen/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "patient=Patient/patient-123&_count=10"

Search by ID

curl -X POST https://fhirtest.netsmartcloud.com/payer/patient-access/v2/{tenant-id}/Specimen/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "_id=specimen-123"

Response Examples

Successful Search Response

Specimen Search Bundle

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "resource": {
        "resourceType": "Specimen",
        "id": "specimen-123",
        "meta": {
          "lastUpdated": "2022-08-19T13:58:00.000+00:00"
        },
        "status": "available",
        "type": {
          "coding": [
            {
              "system": "http://snomed.info/sct",
              "code": "119297000",
              "display": "Blood specimen"
            }
          ]
        },
        "subject": {
          "reference": "Patient/patient-123"
        },
        "collection": {
          "collectedDateTime": "2022-08-19T08:30:00.000Z",
          "collector": {
            "reference": "Practitioner/practitioner-456"
          },
          "method": {
            "coding": [
              {
                "system": "http://snomed.info/sct",
                "code": "28520004",
                "display": "Venipuncture"
              }
            ]
          }
        }
      }
    }
  ]
}

Individual Specimen Response

Single Specimen Resource

{
  "resourceType": "Specimen",
  "id": "specimen-456",
  "meta": {
    "lastUpdated": "2022-09-15T10:30:00.000+00:00"
  },
  "status": "available",
  "type": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "122555007",
        "display": "Venous blood specimen"
      }
    ]
  },
  "subject": {
    "reference": "Patient/patient-789"
  },
  "collection": {
    "collectedDateTime": "2022-09-15T09:00:00.000Z",
    "collector": {
      "reference": "Practitioner/practitioner-123"
    },
    "method": {
      "coding": [
        {
          "system": "http://snomed.info/sct",
          "code": "28520004",
          "display": "Venipuncture"
        }
      ]
    },
    "bodySite": {
      "coding": [
        {
          "system": "http://snomed.info/sct",
          "code": "49852007",
          "display": "Structure of median cubital vein"
        }
      ]
    }
  }
}

Integration Patterns

Common Workflows

1. Patient Specimen Lookup

# Step 1: Search for specimens by patient
GET /Specimen?patient=Patient/patient-123

# Step 2: Get specific specimen details
GET /Specimen/specimen-123

# Step 3: Find related diagnostic reports
GET /DiagnosticReport?specimen=Specimen/specimen-123

2. Coverage and Claims Processing

# Step 1: Get patient specimens
GET /Specimen?patient=Patient/patient-123

# Step 2: Check coverage for specimen collection
GET /Coverage?patient=Patient/patient-123

# Step 3: Review related claims
GET /ExplanationOfBenefit?patient=Patient/patient-123

Related Resources

• Patient - Individual from whom the specimen was collected
• DiagnosticReport - Laboratory results based on the specimen
• Coverage - Insurance coverage for specimen collection
• ExplanationOfBenefit - Claims and coverage details

Error Handling

The Specimen resource follows standard FHIR error handling patterns. For detailed error responses and troubleshooting guidance, see the [Common Errors] page.

Specimen-Specific Error Scenarios

• 404 Not Found: Specimen ID doesn't exist or specimen record is inactive
• 400 Bad Request: Invalid search parameters or malformed date formats
• Empty Results: No specimens match the search criteria

Troubleshooting Tips

• No Results for Patient Search: Verify patient ID format and existence
• Date Format Issues: Ensure collection dates are in proper ISO format
• Performance Issues: Use _count parameter to limit result sets

Supported Profiles

• HL7 FHIR R4 Specimen
• US Core Specimen