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 B2B 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.
Initiated via device (refill only): starts as CREATED. No web app acceptance is required. B2B integrations cannot create refill procedures, only track their status.

Procedure types

Type	Description	Can be created via B2B API
`STORE`	Store cryopreserved sample containers into a storage solution	Yes
`RETRIEVAL`	Retrieve stored sample containers from a storage solution	Yes
`REFILL`	Replenish liquid nitrogen in a storage solution	No (device-initiated only)

Procedure states

State	Description
`PENDING`	Created via API, awaiting web app user action
`CREATED`	Ready for device execution (created via web app, or device-initiated refill)
`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://your-api-host/api/v1/external/procedures \
  -H "Authorization: Bearer YOUR_API_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,
  "code": "PROC-2024-001",
  "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"
}

Track a storage procedure

Poll the procedure endpoint until the status reaches a terminal state (COMPLETED, CANCELLED, or FAILED).

curl https://your-api-host/api/v1/external/procedures/1234 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

While the device is executing (IN_PROGRESS):

{
  "id": 1234,
  "code": "PROC-2024-001",
  "type": "STORE",
  "status": "IN_PROGRESS",
  "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"
}

When storage is complete (COMPLETED) - includes the storage location of each sample:

{
  "id": 1234,
  "code": "PROC-2024-001",
  "type": "STORE",
  "status": "COMPLETED",
  "facility": { "id": 1, "name": "Main Facility" },
  "subject": { "id": 123, "code": "SUBJ-2024-001" },
  "sampleContainers": [
    {
      "id": 456,
      "name": "VL-001",
      "description": "Vial 1 - Tissue sample",
      "location": {
        "storage": { "id": 78, "name": "Tank A" },
        "canister": "C1",
        "cane": "CN1"
      },
      "storedAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": 457,
      "name": "VL-002",
      "description": "Vial 2 - Tissue sample",
      "location": {
        "storage": { "id": 78, "name": "Tank A" },
        "canister": "C1",
        "cane": "CN1"
      },
      "storedAt": "2024-01-15T10:31:00Z"
    }
  ],
  "createdAt": "2024-01-15T10:00:00Z",
  "completedAt": "2024-01-15T10:45:00Z"
}

Webhook support for procedure status events is coming soon. Contact your Crinsutrack administrator for details.

Retrieval procedure flow

Create a retrieval procedure

First, find the sample containers for the subject:

curl "https://your-api-host/api/v1/external/sample-containers?subjectCode=SUBJ-2024-001" \
  -H "Authorization: Bearer YOUR_API_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. The subjectCode field is a required safety check: the request is rejected with VALIDATION_ERROR if any of the specified containers do not belong to that subject.

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

Example Response:

{
  "id": 5678,
  "code": "PROC-2024-002",
  "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"
}

Track a retrieval procedure

Poll the procedure endpoint until the status reaches a terminal state (COMPLETED, CANCELLED, or FAILED).

curl https://your-api-host/api/v1/external/procedures/5678 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

While the device is executing (IN_PROGRESS):

{
  "id": 5678,
  "code": "PROC-2024-002",
  "type": "RETRIEVAL",
  "status": "IN_PROGRESS",
  "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"
}

When retrieval is complete (COMPLETED):

{
  "id": 5678,
  "code": "PROC-2024-002",
  "type": "RETRIEVAL",
  "status": "COMPLETED",
  "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",
  "completedAt": "2024-01-15T11:30:00Z"
}

Polling for status

Procedures in PENDING state require a facility staff member to act before they advance. This may take minutes to hours depending on facility workload. Poll the procedure endpoint at a reasonable interval (every 60 seconds is a good starting point) and back off if you are polling frequently with no state change. Stop polling once the status reaches a terminal state: COMPLETED, CANCELLED, or FAILED.

Webhook support for procedure status events is coming soon. Contact your Crinsutrack administrator for details.

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://your-api-host/api/v1/external/procedures?facilityId=1&type=REFILL" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response:

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

Webhook support for procedure status events is coming soon. Contact your Crinsutrack administrator for details.

List procedures

curl "https://your-api-host/api/v1/external/procedures?facilityId=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response:

[
  {
    "id": 1234,
    "code": "PROC-2024-001",
    "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,
    "code": "PROC-2024-002",
    "type": "RETRIEVAL",
    "status": "PENDING",
    "facility": { "id": 1, "name": "Main Facility" },
    "subject": { "id": 123, "code": "SUBJ-2024-001" },
    "createdAt": "2024-01-15T11:00:00Z"
  }
]