Procedures

A procedure represents a store, retrieval, or LN2 refill operation performed by users on a storage solution. It is executed by an authorized device and tracked through its full lifecycle — from creation to completion.

The initial state depends on how the procedure was created:

• Created via API — starts as PENDING. A facility staff member must progress it before the device can execute it: for retrievals, by reviewing and accepting it; for storage, by associating RFID tags with the containers.
• Created via web app — starts as CREATED and is queued for device execution immediately.
• Refill procedures — initiated by a user through the device interface as a maintenance task. B2B integrations can track them but cannot create them.

Procedure states

State	Description
PENDING	Created via API, awaiting web app user action
CREATED	Created via web app, ready for device execution
IN_PROGRESS	Procedure is being executed
COMPLETED	Procedure finished successfully
CANCELLED	Procedure was cancelled
FAILED	Procedure encountered an error and could not complete

Storage procedure flow

Create a storage procedure

curl -X POST https://api.crinsutrack.com/api/v1/external/procedures \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "STORE",
    "facilityId": 1,
    "subjectCode": "SUBJ-2024-001",
    "sampleContainers": [
      { "name": "VL-001", "description": "Vial 1 - Tissue sample" },
      { "name": "VL-002", "description": "Vial 2 - Tissue sample" }
    ]
  }'

Example Response:

{
  "id": 1234,
  "type": "STORE",
  "status": "PENDING",
  "facility": { "id": 1, "name": "Main Facility" },
  "subject": { "id": 123, "code": "SUBJ-2024-001" },
  "sampleContainers": [
    { "id": 456, "name": "VL-001", "description": "Vial 1 - Tissue sample" },
    { "id": 457, "name": "VL-002", "description": "Vial 2 - Tissue sample" }
  ],
  "createdAt": "2024-01-15T10:00:00Z"
}

Retrieval procedure flow

Create a retrieval procedure

First, find the sample containers for the subject:

curl "https://api.crinsutrack.com/api/v1/external/sample-containers?subjectCode=SUBJ-2024-001" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response:

[
  {
    "id": 456,
    "name": "VL-001",
    "subject": { "id": 123, "code": "SUBJ-2024-001" },
    "description": "Vial 1 - Tissue sample",
    "storedAt": "2024-01-15T10:30:00Z"
  },
  {
    "id": 457,
    "name": "VL-002",
    "subject": { "id": 123, "code": "SUBJ-2024-001" },
    "description": "Vial 2 - Tissue sample",
    "storedAt": "2024-01-15T10:31:00Z"
  }
]

Then create the retrieval procedure:

curl -X POST https://api.crinsutrack.com/api/v1/external/procedures \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "RETRIEVAL",
    "facilityId": 1,
    "subjectCode": "SUBJ-2024-001",
    "sampleContainerIds": [456, 457]
  }'

Example Response:

{
  "id": 5678,
  "type": "RETRIEVAL",
  "status": "PENDING",
  "facility": { "id": 1, "name": "Main Facility" },
  "subject": { "id": 123, "code": "SUBJ-2024-001" },
  "sampleContainers": [
    { "id": 456, "name": "VL-001", "description": "Vial 1 - Tissue sample" },
    { "id": 457, "name": "VL-002", "description": "Vial 2 - Tissue sample" }
  ],
  "createdAt": "2024-01-15T11:00:00Z"
}

LN2 refill procedure flow

Refill procedures are initiated by a user through the device interface as a maintenance task and go directly to execution — no web app acceptance is required. B2B integrations cannot create them, only track their status. Unlike storage and retrieval, a refill is not tied to a subject.

Track a refill procedure

Refill procedures appear in the standard procedure list and can be retrieved by ID:

curl "https://api.crinsutrack.com/api/v1/external/procedures?facilityId=1&type=REFILL" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response:

[
  {
    "id": 9012,
    "type": "REFILL",
    "status": "COMPLETED",
    "facility": { "id": 1, "name": "Main Facility" },
    "createdAt": "2024-01-20T09:00:00Z",
    "completedAt": "2024-01-20T09:15:00Z"
  }
]

Get procedure status

curl https://api.crinsutrack.com/api/v1/external/procedures/1234 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response:

{
  "id": 1234,
  "type": "STORE",
  "status": "PENDING",
  "facility": { "id": 1, "name": "Main Facility" },
  "subject": { "id": 123, "code": "SUBJ-2024-001" },
  "sampleContainers": [
    { "id": 456, "name": "VL-001", "description": "Vial 1 - Tissue sample" },
    { "id": 457, "name": "VL-002", "description": "Vial 2 - Tissue sample" }
  ],
  "createdAt": "2024-01-15T10:00:00Z"
}

List procedures

curl "https://api.crinsutrack.com/api/v1/external/procedures?facilityId=1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response:

[
  {
    "id": 1234,
    "type": "STORE",
    "status": "COMPLETED",
    "facility": { "id": 1, "name": "Main Facility" },
    "subject": { "id": 123, "code": "SUBJ-2024-001" },
    "createdAt": "2024-01-15T10:00:00Z",
    "completedAt": "2024-01-15T10:45:00Z"
  },
  {
    "id": 5678,
    "type": "RETRIEVAL",
    "status": "PENDING",
    "facility": { "id": 1, "name": "Main Facility" },
    "subject": { "id": 123, "code": "SUBJ-2024-001" },
    "createdAt": "2024-01-15T11:00:00Z"
  }
]