API Reference

Welcome to the TranscriMed API Reference! This comprehensive documentation covers all available endpoints, request/response formats, and authentication methods.

Quick Links

API Testing Guide

Test APIs directly from your browser

Postman Collection

Download pre-configured API collection

Base URL

All API requests should be made to:

https://api.transcrimed.com.br

Test Mode

For testing and development, use test credentials with the same production endpoint:

Use client IDs starting with test_tc_ to activate test mode automatically
Test mode returns mock data without consuming production credits
No separate staging URL needed - the API automatically detects test credentials

Example test credentials:

client_id: test_tc_abc123...
client_secret: test_tcs_xyz789...

Authentication

All API endpoints require authentication using OAuth2 access tokens. Include your access token in the Authorization header:

Authorization: Bearer your_access_token_here

Learn more about authentication in our Authentication Guide.

Interactive API Documentation

Explore our APIs with interactive documentation powered by OpenAPI specifications:

Authentication API

Handles OAuth2 authentication flow for secure partner integrations.

Key endpoints:

GET /api/oauth/authorize - Start OAuth2 authorization
POST /api/oauth/token - Exchange code for tokens
POST /api/oauth/revoke - Revoke access tokens

Scopes:

medical_records:read - Read medical records
medical_records:write - Create and update medical records
medical_records:delete - Delete medical records
jobs:read - Read job status and results
jobs:write - Create, cancel and manage jobs
worklists:write - Send worklist items
worklists:manage - Manage worklist item status
worklists:read - Read worklist items

Worklist API 🏥

PRIMARY INTEGRATION FOR HEALTHCARE PARTNERS

Bidirectional integration with RIS/PACS systems for medical worklist management. This is our most commonly used API for healthcare system integrations.

Key endpoints:

POST /api/v1/worklists/ingest - Receive worklist items from external systems
PATCH /api/v1/worklists/items/\{id\} - Update worklist item status

Core Features:

✅ Receive worklists from external RIS/PACS systems
✅ Process and normalize DICOM-based exam data
✅ Automatically send processed medical documents back to source systems
✅ Snake_case field mapping for REST API compatibility
✅ Idempotency support for reliable ingestion
✅ Deduplication based on accession_number or study_uid
✅ Webhook notifications for completed documents

Integration Flow:

Ingest: External RIS/PACS system sends worklist via API
Select: Doctors view and select exams in TranscriMed dashboard
Process: Medical professionals record audio for selected exams
Generate: TranscriMed creates structured medical documents
Deliver: Completed documents are automatically sent back to source system

Why Choose Worklist Integration?

Seamless Workflow: Integrates directly into existing RIS/PACS workflows
Automated Delivery: No manual document transfer needed
DICOM Compatible: Uses familiar medical imaging standards
Bidirectional: Both send worklists AND receive completed documents
Enterprise Ready: Built for high-volume healthcare environments

Worklist API - Complete Reference

Quick Start

Get started with worklist integration in 5 minutes:

# 1. Get your access token (see Authentication section)
export ACCESS_TOKEN="your_access_token_here"

# 2. Send a simple worklist item
curl -X POST https://api.transcrimed.com.br/api/v1/worklists/ingest \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "accession_number": "2024-001234",
    "patient_id": "PAT-456789", 
    "patient_name": "John Smith",
    "modality": "CR",
    "exam_datetime": "2024-01-15T10:30:00Z",
    "exam_description": "Chest X-Ray PA/Lateral"
  }'

# 3. Set up webhook endpoint to receive completed documents
# (Configure webhook URL in Developer Portal)

POST /api/v1/worklists/ingest

Ingest worklist items from your RIS/PACS system into TranscriMed.

Request Headers

Header	Type	Required	Description
`Authorization`	string	✅	Bearer token with `worklists:write` scope
`Content-Type`	string	✅	Must be `application/json`
`Idempotency-Key`	string	⚠️	UUID to prevent duplicate processing
`X-Source-System`	string	❌	Identifier for your RIS/PACS system

Request Body Options

You can send worklist items in three formats:

Single Item:

{
  "accession_number": "2024-001234",
  "patient_id": "PAT-456789",
  "patient_name": "John Smith",
  "patient_sex": "M",
  "patient_birth_date": "1980-05-15",
  "modality": "CR",
  "exam_datetime": "2024-01-15T10:30:00Z",
  "exam_room": "Room 1",
  "exam_description": "Chest X-Ray PA/Lateral",
  "study_uid": "1.2.826.0.1.3680043.6.15372.14625.20240115103000",
  "referring_physician": "Dr. Maria Garcia",
  "hospital_name": "Central Hospital",
  "location": "Radiology Department",
  "metadata": {
    "urgency": "routine",
    "contrast": false,
    "patient_weight": "70kg"
  }
}

Array of Items:

[
  {
    "accession_number": "2024-001234",
    "patient_id": "PAT-456789",
    "patient_name": "John Smith",
    "modality": "CR",
    "exam_datetime": "2024-01-15T10:30:00Z",
    "exam_description": "Chest X-Ray PA/Lateral"
  },
  {
    "accession_number": "2024-001235", 
    "patient_id": "PAT-456790",
    "patient_name": "Jane Doe",
    "modality": "CT",
    "exam_datetime": "2024-01-15T11:00:00Z",
    "exam_description": "CT Head without Contrast"
  }
]

Wrapped Array (for legacy systems):

{
  "items": [
    {
      "accession_number": "2024-001234",
      "patient_id": "PAT-456789",
      "patient_name": "John Smith",
      "modality": "CR",
      "exam_datetime": "2024-01-15T10:30:00Z",
      "exam_description": "Chest X-Ray PA/Lateral"
    }
  ]
}

Field Reference

Required Fields

At least one of these identifiers must be provided:

Field	Type	Description	Example
`accession_number`	string	Unique exam identifier	"2024-001234"
`study_uid`	string	DICOM Study Instance UID	"1.2.826.0.1..."

Core Fields

Field	Type	Required	Description	Example
`patient_id`	string	⚠️	Patient identifier	"PAT-456789"
`patient_name`	string	⚠️	Patient full name	"John Smith"
`modality`	string	⚠️	Medical imaging modality	"CR", "CT", "MR"
`exam_datetime`	string	⚠️	Exam date/time (ISO 8601)	"2024-01-15T10:30:00Z"
`exam_description`	string	⚠️	Procedure description	"Chest X-Ray PA/Lateral"

Optional Fields

Field	Type	Description	Validation
`patient_sex`	string	Patient gender	"M", "F", "O", "U"
`patient_birth_date`	string	Birth date (ISO 8601)	"1980-05-15"
`patient_age`	string	Age in free format	"42y", "6months"
`exam_room`	string	Room where exam performed	"Room 1", "CT Suite B"
`referring_physician`	string	Requesting physician	"Dr. Maria Garcia"
`hospital_name`	string	Institution name	"Central Hospital"
`location`	string	Department/location	"Radiology Dept"
`procedure_id`	string	Procedure identifier	"PROC-123"
`series_count`	integer	Number of image series	2
`images_count`	integer	Total number of images	150
`metadata`	object	Additional custom data	`{"urgency": "stat"}`

Response Formats

✅ Success Response (200 OK)

{
  "success": true,
  "data": {
    "batch_id": "batch_20240115_103045_abc123",
    "processed": 3,
    "inserted": 2,
    "updated": 1,
    "deduped": 0,
    "errors": [],
    "items": [
      {
        "id": "worklist_item_uuid_1",
        "accession_number": "2024-001234",
        "status": "inserted",
        "message": "Successfully ingested new exam"
      },
      {
        "id": "worklist_item_uuid_2", 
        "accession_number": "2024-001235",
        "status": "updated",
        "message": "Updated existing exam with new information"
      }
    ]
  },
  "meta": {
    "request_id": "req_20240115_103045",
    "timestamp": "2024-01-15T10:30:45Z",
    "processing_time_ms": 234
  }
}

⚠️ Partial Success Response (200 OK)

{
  "success": true,
  "data": {
    "batch_id": "batch_20240115_103045_def456",
    "processed": 3,
    "inserted": 1,
    "updated": 0,
    "deduped": 1,
    "errors": [
      {
        "index": 2,
        "accession_number": "2024-001236",
        "error": "INVALID_MODALITY",
        "message": "Modality 'XR' is not valid. Use 'CR' for Computed Radiography",
        "field": "modality"
      }
    ],
    "items": [
      {
        "id": "worklist_item_uuid_1",
        "accession_number": "2024-001234", 
        "status": "inserted"
      },
      {
        "accession_number": "2024-001235",
        "status": "deduped",
        "message": "Item already exists with same accession_number"
      }
    ]
  },
  "meta": {
    "request_id": "req_20240115_103045",
    "timestamp": "2024-01-15T10:30:45Z"
  }
}

❌ Error Responses

Validation Error (400 Bad Request)

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request validation failed",
    "details": {
      "errors": [
        {
          "field": "patient_name",
          "message": "Patient name is required",
          "code": "FIELD_REQUIRED"
        },
        {
          "field": "exam_datetime",
          "message": "Date must be in ISO 8601 format",
          "code": "INVALID_FORMAT"
        }
      ]
    }
  },
  "meta": {
    "request_id": "req_20240115_103045",
    "timestamp": "2024-01-15T10:30:45Z"
  }
}

Authentication Error (401 Unauthorized)

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired access token",
    "details": {
      "hint": "Refresh your access token and try again"
    }
  },
  "meta": {
    "request_id": "req_20240115_103045", 
    "timestamp": "2024-01-15T10:30:45Z"
  }
}

Rate Limit Error (429 Too Many Requests)

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": {
      "limit": 100,
      "window": "1 minute",
      "retry_after": 45
    }
  },
  "meta": {
    "request_id": "req_20240115_103045",
    "timestamp": "2024-01-15T10:30:45Z"
  }
}

PATCH /api/v1/worklists/items/{id}

Update the status of a specific worklist item.

Request Example

curl -X PATCH https://api.transcrimed.com.br/api/v1/worklists/items/worklist_item_uuid_1 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress",
    "reason": "Exam started in Room 1",
    "metadata": {
      "technician": "Tech Smith",
      "started_at": "2024-01-15T10:35:00Z"
    }
  }'

Request Body Schema

{
  "status": "string",     // Required: new, in_progress, completed, cancelled
  "reason": "string",     // Optional: reason for status change
  "metadata": "object"    // Optional: additional data
}

Response Example

{
  "success": true,
  "data": {
    "id": "worklist_item_uuid_1",
    "accession_number": "2024-001234",
    "status": "in_progress",
    "previous_status": "new",
    "updated_at": "2024-01-15T10:35:00Z",
    "reason": "Exam started in Room 1"
  },
  "meta": {
    "request_id": "req_20240115_103500",

Quick Links​

API Testing Guide

Postman Collection

Base URL​

Test Mode​

Authentication​

Interactive API Documentation​

Authentication API​

Worklist API 🏥​

Worklist API - Complete Reference​

Quick Start​

POST /api/v1/worklists/ingest​

Request Headers​

Request Body Options​

Field Reference​

Required Fields​

Core Fields​

Optional Fields​

Response Formats​

PATCH /api/v1/worklists/items/{id}​

Request Example​

Request Body Schema​

Response Example​