B2B Integration

Server-to-server integrations for external systems (EMR, LIS, etc.) that need to request storage and retrieval operations.

Prerequisites

OAuth 2.0 client credentials from your Crinsutrack administrator (see Authentication)
A tool for making HTTP requests (curl, Postman, or your preferred HTTP client)

Resources Overview

The Crinsutrack API is organized around these core resources:

Resource	Description
Organization	Top-level account representing a company or institution
Facility	Physical location (clinic, lab, storage site)
Subject	Individual whose samples are stored
Sample Container	Physical container (vial, straw) holding cryopreserved material
Container	Storage level within a storage solution (canister, cane, rack, box)
Storage Solution	Physical storage unit (tank, dewar) holding containers
Procedure Request	Request for storage/retrieval created by integrations, requires web app approval
Procedure	Tracked activity: register storage, storage, retrieval, transfer, refill

All resources are scoped by organization. B2B integrations can only access data within their authorized organization’s facilities.

Create Subjects

Create a Subject

curl -X POST https://api.crinsutrack.com/api/subjects \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "facilityId": 1,
    "code": "SUBJ-2024-001",
    "firstName": "Jane",
    "lastName": "Doe",
    "dateOfBirth": "1990-05-15"
  }'

Example Response:

{
  "id": 123,
  "facilityId": 1,
  "code": "SUBJ-2024-001",
  "firstName": "Jane",
  "lastName": "Doe",
  "dateOfBirth": "1990-05-15",
  "createdAt": "2024-01-15T10:00:00Z"
}

Request Procedures

Submit storage and retrieval requests. These requests are reviewed and approved by Crinsutrack web app users before becoming actual procedures that authorized devices (like SCARF) execute.

Request States

State	Description
`PENDING`	Request submitted, awaiting review
`ACCEPTED`	Request approved, procedure created
`REJECTED`	Request denied by web app user
`CANCELLED`	Request cancelled by requester

Create a Storage Request

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

Example Response:

{
  "id": 5678,
  "type": "STORE",
  "status": "PENDING",
  "facilityId": 1,
  "subjectCode": "SUBJ-2024-001",
  "sampleContainers": [
    { "sampleContainerId": "VL-001", "description": "Vial 1 - Tissue sample" },
    { "sampleContainerId": "VL-002", "description": "Vial 2 - Tissue sample" }
  ],
  "procedureId": null,
  "createdAt": "2024-01-15T10:00:00Z"
}

Create a Retrieval Request

First, find sample containers for the subject:

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

Then request retrieval:

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

Track Requests

Monitor request status and linked procedures.

Get Procedure Request Status

curl https://api.crinsutrack.com/api/procedure-requests/5678 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

When pending:

{
  "id": 5678,
  "type": "STORE",
  "status": "PENDING",
  "procedureId": null,
  "createdAt": "2024-01-15T10:00:00Z"
}

When accepted:

{
  "id": 5678,
  "type": "STORE",
  "status": "ACCEPTED",
  "procedureId": 1234,
  "acceptedAt": "2024-01-15T10:15:00Z",
  "acceptedBy": "Jane Doe"
}

List Procedure Requests

curl "https://api.crinsutrack.com/api/procedure-requests?status=PENDING" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Track Linked Procedure

Once a request is accepted, track the resulting procedure:

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

Example Response:

{
  "id": 1234,
  "type": "storage",
  "status": "COMPLETED",
  "facilityId": 1,
  "storageId": 78,
  "sampleContainerIds": [456, 457, 458],
  "requestId": 5678,
  "performedBy": "Jane Doe",
  "createdAt": "2024-01-15T10:30:00Z",
  "startedAt": "2024-01-15T10:30:05Z",
  "completedAt": "2024-01-15T10:31:00Z",
  "error": null
}

Procedure States

State	Description
`CREATED`	Procedure created and awaiting device execution
`IN_PROGRESS`	Procedure is currently being executed by a device
`COMPLETED`	Procedure finished successfully
`CANCELLED`	Procedure was cancelled before completion
`FAILED`	Procedure encountered an error and could not complete

View Data

Access subjects, sample containers, storage inventory, and procedures.

List Subjects

curl "https://api.crinsutrack.com/api/subjects?page=1&perPage=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Get a Specific Subject

curl https://api.crinsutrack.com/api/subjects/123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

List Sample Containers by Subject

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

Get Sample Container Location

curl https://api.crinsutrack.com/api/sample-containers/456/location \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response:

{
  "sampleContainerId": 456,
  "storageId": 78,
  "storageName": "Tank A-01",
  "position": "Canister 3, Cane 2, Slot 5",
  "storedAt": "2024-01-15T10:30:00Z"
}

List Storage Solutions

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

Get Storage Inventory

curl https://api.crinsutrack.com/api/storage/78/inventory \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

List Procedures

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

Get Procedure Details

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

Note: B2B integrations can view procedures but cannot create them directly or change their status. Use Request Procedures to request storage/retrieval operations. See Roles & Permissions for details.

Common Query Parameters

Most list endpoints support these query parameters:

Parameter	Description	Example
`page`	Page number (default: 1)	`?page=2`
`perPage`	Items per page (default: 10)	`?perPage=25`
`field=value`	Exact match filter	`?status=active`
`field_like=value`	Partial match (case-insensitive)	`?name_like=john`
`field_from=value`	Greater than or equal	`?createdAt_from=2024-01-01`
`field_to=value`	Less than or equal	`?createdAt_to=2024-12-31`

Next Steps

Review the Full API Reference for complete endpoint documentation
Understand your Roles & Permissions
Implement token refresh in your Authentication flow