Skip to content
Probatix API Documentation

Create or update inbound shipment tracking for a diagnostic test

POST
/v1/diagnostic_tests/{id}/shipment_tracking
curl --request POST \
  --url 'http://api.probatix.localhost/v1/diagnostic_tests/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/shipment_tracking?XDEBUG_SESSION=PHPSTORM' \
  --header 'Content-Type: application/json' \
  --header 'X-API-TOKEN: <X-API-TOKEN>' \
  --header 'accept-language: de' \
  --data '{ "provider": "DHL", "trackingCode": "TRACK-123456", "url": "https://www.dhl.de/en/privatkunden/dhl-sendungsverfolgung.html?piececode=TRACK-123456", "shipmentStatus": "confirmed" }'

Creates or updates shipment tracking for the Customer -> Lab shipment of the DiagnosticTest.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string format: uuid

ShipmentTrackingInput identifier

Header Parameters

Section titled “Header Parameters”
accept-language
string
Allowed values: de en fr

Language for Errors and Translatable properties

Example
de

Query Parameters

Section titled “Query Parameters”
XDEBUG_SESSION
string
default: PHPSTORM

Xdebug session for debugging

Example
?XDEBUG_SESSION=PHPSTORM

Request Bodyrequired

Section titled “Request Bodyrequired”

The new ShipmentTrackingInput resource

object
id
string format: uuid
provider
required

Shipment provider responsible for the parcel.

string
Allowed values: DHL Swiss Post OTHER
Example
DHL
trackingCode

Optional carrier tracking code for the shipment.

string | null
<= 255 characters
Example
TRACK-123456
url

Optional tracking URL. If omitted, the system generates one for supported providers when a tracking code is provided.

More information

string format: url
Example
https://www.dhl.de/en/privatkunden/dhl-sendungsverfolgung.html?piececode=TRACK-123456
shipmentStatus

Optional shipment status to expose together with the tracking data.

string | null
Allowed values: confirmed in_transit out_for_delivery delivered failure undeliverable returned_to_sender available_for_collection
Example
in_transit

Responses

Section titled “Responses”

200

Section titled “200”

ShipmentTrackingInput resource created

object
id
required
string format: uuid
diagnosticOrder
required

IRI of the parent diagnostic order.

string format: iri-reference
diagnosticProduct
required

IRI of the DiagnosticProduct that was ordered for this test.

string format: iri-reference
testResults

IRIs of linked test results, sorted by createdAt. In most patient-facing use cases, the most recent test result is the relevant one. Older results are included for transparency and historical records.

Array<string>
patient
Any of:
object
email
string format: email
firstName
string | null
lastName
string | null
gender
string
default: X
Allowed values: M F D X
dateOfBirth
string format: date
healthInsuranceDetails
Any of:
object
countryCode
string | null
provider
string | null
healthInsuranceTypeDE
string | null
Allowed values: GKV PKV
subscriberIdentifier

The insurer assigned ID for the Subscriber.

string | null
specimens
Array<object>
object
specimenCode
required

Laboratory specimen code or sample identifier.

string
createdAt
required

Timestamp when the specimen record was created.

string format: date-time
collectionDate

Date when the specimen was collected.

string format: date
collectionTime

Time of day when the specimen was collected.

string
/^\d{2}:\d{2}:\d{2}$/
menstrualPhaseAtCollection

Menstrual phase reported at collection time, when applicable.

string | null
Allowed values: follikel ovulation luteal menopause
shipmentTracking
Any of:
object
provider
required
string
Allowed values: DHL Swiss Post OTHER
createdAt
required

Timestamp when the shipment was created.

string format: date-time
updatedAt
required

Timestamp when the shipment was last updated.

string format: date-time
trackingCode
string | null
url
string format: url
shipmentStatus

Normalized shipment status for informational purposes only.

string | null
Allowed values: confirmed in_transit out_for_delivery delivered failure undeliverable returned_to_sender available_for_collection
providerStatus

Shipment status from the provider please note some Providers are not 100% reliable and will occasionally deliver shipments without status updates.

string | null
activatedAt

Timestamp when the patient activated the TestKit.

string | null format: date-time
labIntakeAt

Timestamp when the specimen arrived in the laboratory.

string | null format: date-time
createdAt
required

Timestamp when the DiagnosticTest was created.

string format: date-time
Example
{
  "diagnosticOrder": "/v1/diagnostic_orders/00112233-4455-6677-8899-aabbccddeeff",
  "diagnosticProduct": "/v1/diagnostic_products/00112233-4455-6677-8899-aabbccddeeff",
  "testResults": [
    "/v1/test_results/00112233-4455-6677-8899-aabbccddeeff"
  ],
  "patient": {
    "email": "meron.nagy@probatix.de",
    "firstName": "Jane",
    "lastName": "Doe",
    "gender": "M",
    "dateOfBirth": "1994-01-15",
    "healthInsuranceDetails": {
      "countryCode": "DE",
      "provider": "Example Insurance",
      "healthInsuranceTypeDE": "GKV"
    }
  },
  "specimens": [
    {
      "specimenCode": "ABC-123456",
      "collectionDate": "2026-05-04",
      "collectionTime": "13:50:00",
      "menstrualPhaseAtCollection": "follikel"
    }
  ],
  "shipmentTracking": {
    "provider": "DHL",
    "trackingCode": "123",
    "url": "https://www.dhl.de/en/privatkunden/dhl-sendungsverfolgung.html?piececode=123",
    "shipmentStatus": "confirmed",
    "providerStatus": {
      "terminalStatus": true,
      "name": "DELIVERED",
      "value": "delivered"
    }
  },
  "activatedAt": "2026-05-04T10:30:00+00:00",
  "labIntakeAt": "2026-05-06T07:45:00+00:00"
}

400

Section titled “400”

Invalid input

A representation of common errors.

object
@context
One of:
string
@id
required
string
@type
required
string
title

A short, human-readable summary of the problem.

string | null
detail

A human-readable explanation specific to this occurrence of the problem.

string | null
status
integer | null
default: 400
instance

A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

string | null
type

A URI reference that identifies the problem type

string
description
string | null
Example
{
  "@context": {
    "hydra": "http://www.w3.org/ns/hydra/core#"
  },
  "status": 400
}

401

Section titled “401”

Unauthorized

A representation of common errors.

object
@context
One of:
string
@id
required
string
@type
required
string
title

A short, human-readable summary of the problem.

string | null
detail

A human-readable explanation specific to this occurrence of the problem.

string | null
status
integer | null
default: 400
instance

A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

string | null
type

A URI reference that identifies the problem type

string
description
string | null
Example
{
  "@context": {
    "hydra": "http://www.w3.org/ns/hydra/core#"
  },
  "status": 400
}

403

Section titled “403”

Forbidden

A representation of common errors.

object
@context
One of:
string
@id
required
string
@type
required
string
title

A short, human-readable summary of the problem.

string | null
detail

A human-readable explanation specific to this occurrence of the problem.

string | null
status
integer | null
default: 400
instance

A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

string | null
type

A URI reference that identifies the problem type

string
description
string | null
Example
{
  "@context": {
    "hydra": "http://www.w3.org/ns/hydra/core#"
  },
  "status": 400
}

422

Section titled “422”

An error occurred

Unprocessable entity

object
@context
One of:
string
@id
required
string
@type
required
string
status
integer
default: 422
violations
Array<object>
object
propertyPath
required

The property path of the violation

string
message
required

The message associated with the violation

string
code

The code of the violation

string
hint

An extra hint to understand the violation

string
payload

The serialized payload of the violation

object
key
additional properties
any
detail
string
description
string
type
string
title
string | null
instance
string | null
Example
{
  "@context": {
    "hydra": "http://www.w3.org/ns/hydra/core#"
  },
  "status": 422
}