Schedule

Server

Schedule a specimen pickup.

POST

https://specimen-service.services.{domain}

/schedule

Submit a specimen pickup schedule request.

Before fulfilling the request, this service validates local required fields, authorizes the account for the caller, and checks that the request is inside the location's same-day routine cutoff window:

Require accountNumber, locationId, pickUpType, nested submitter.firstName / submitter.lastName, sendingFacility, and sendingApplication in the JSON body.
Match trimmed sendingFacility + sendingApplication (case-sensitive) to a unique ACTIVE client config on this request's service subscription. No match returns 403. More than one ACTIVE match returns 500 subscription-config-ambiguous. Incomplete client configuration returns 500 subscription-config-incomplete.
Authorize the request accountNumber for that client config before cutoff checks or scheduling. Authorization failures return partner-not-owner / not-found / data-incomplete / opaque 5xx.
Allow only pickUpType REGULAR (Routine) in v1; matching is case-insensitive (for example Regular, regular).
Look up the location for accountNumber, selecting the matching location by the request's locationId. A locationId with no match is rejected.
Require routinePickUpAllowedToday and a local wall-clock time inside [routineStartTime, routineCutOffTime) using timeZoneInfo.utcOffset.

The cutoff gate uses the location's wall-clock window and utcOffset only.

The body includes both accountNumber (partner account) and locationId (a pickup location identifier from the locations response). These are separate properties. This service validates the documented request fields; other body properties are forwarded upstream unchanged and are unsupported.

STAT orders are not supported. Schedule routine pickups only (pickUpType REGULAR, case-insensitive); do not send STAT-specific fields such as statInformation or statId.

Successful (2xx) JSON is returned unchanged.

Schedule a specimen pickup. › Request Body

Schedule request body. This service validates the documented fields: `accountNumber`, `locationId`, `pickUpType` (`REGULAR` only in v1, case-insensitive), nested `submitter.firstName` / `submitter.lastName`, `sendingFacility`, and `sendingApplication`. Other body properties are forwarded upstream unchanged and are unsupported. `accountNumber` and `locationId` are separate properties.

SchedulePickUpRequest

accountNumber

string · pattern: ^\d+$ · required

Partner account number for the pickup.

sendingFacility

string · required

The sending facility identifier. Must match the partner's active service subscription configuration.

sendingApplication

string · required

The sending application identifier (mnemonic). Must match the partner's active service subscription configuration.

locationId

string · required

Pickup location identifier from the locations response (locationId). Distinct from the accountNumber path parameter on GET /locations/{accountNumber}.

pickUpType

string · required

Pickup type. v1 accepts only REGULAR (Routine), matched case-insensitively (for example Regular, regular). STAT and other values are rejected.

ScheduleSubmitter · required

Partner-facing submitter identity for schedule requests. Unknown nested properties are ignored.

specialInstructions

string

Optional free-text instructions for the courier at pickup.

callerName

string

Optional name of the person placing the schedule request.

Schedule a specimen pickup. › Responses

The pickup was scheduled.

Response returned on a successful schedule request.

SchedulePickUpResponse

confirmationOrderNumber

string

accountNumber

string

accountName

string

sessionId

string

regionId

string

routeDate

string · date

locationType

string

requestedDateTime

string · date-time

specialInstructions

string

standardInstructions

string

pickUpType

string

Pickup type for the scheduled request. STAT orders are not supported.

firstCallDate

string · date-time

finalCallDate

string · date-time

callerName

string

UserInfo

isSelfService

boolean

trackingId

string

isAssigned

boolean

assignedToFirstName

string

assignedToLastName

string

assignedTo

string

assignedDateTime

string · date-time

tatHours

number · double

courierName

string

dispatcherUser

string

lastUpdatedTimestamp

string

closedTimestamp

string · date-time

POST/schedule

curl 'https://specimen-service.services.{domain}/schedule' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "locationId": "loc-1001",
  "pickUpType": "REGULAR",
  "accountNumber": "01818355",
  "sendingFacility": "TE033133",
  "sendingApplication": "APRTRAPI",
  "callerName": "Jane Doe",
  "specialInstructions": "Ring rear doorbell",
  "submitter": {
    "firstName": "Jane",
    "lastName": "Doe"
  }
}'

Example Request Body

{
  "locationId": "loc-1001",
  "pickUpType": "REGULAR",
  "accountNumber": "01818355",
  "sendingFacility": "TE033133",
  "sendingApplication": "APRTRAPI",
  "callerName": "Jane Doe",
  "specialInstructions": "Ring rear doorbell",
  "submitter": {
    "firstName": "Jane",
    "lastName": "Doe"
  }
}

json

application/json

Example Responses

{
  "confirmationOrderNumber": "CONF-98765",
  "accountName": "Example Clinic",
  "routeDate": "2026-08-15",
  "pickUpType": "REGULAR",
  "trackingId": "TRK-555",
  "isAssigned": false
}

json

application/json

Locations