{ "openapi": "3.1.1", "info": { "title": "Cadmus API", "description": "## Introduction\n\nCadmus is an intra-oral scan inbox API that gives dental labs and clinics\na single place to retrieve normalised case orders and download scan files.\n\n| Environment | Base URL |\n|-------------|----------|\n| Staging | `https://api.staging.cadmuslabs.nl` |\n| Production | `https://api.cadmuslabs.nl` |\n\nSee [/getting-started](/getting-started) for a full curl walkthrough.\n\n## Authentication\n\nAll API endpoints (except `POST /auth/login`) require a **JWT Bearer token**\nwith an 8-hour lifetime.\n\n**Request:**\n```json\nPOST /auth/login\n{\n \"email\": \"user@example.com\",\n \"password\": \"your-password\"\n}\n```\n\n**Response:**\n```json\n{\n \"token\": \"\",\n \"expiresAt\": \"2026-03-09T12:00:00Z\"\n}\n```\n\nPass the token on every subsequent request:\n```\nAuthorization: Bearer \n```\n\n## Quickstart\n\n1. `POST /auth/login` — authenticate and save the returned token\n2. `GET /unified-cases` — list all orders for your organisation\n3. `GET /unified-cases/{id}` — retrieve a single order\n4. `GET /unified-cases/{id}/files/{filename}?fileType=stl` — get a 15-minute signed download URL for a scan file", "version": "v1" }, "servers": [ { "url": "https://api.cadmuslabs.nl", "description": "Production" }, { "url": "https://api.staging.cadmuslabs.nl", "description": "Staging" } ], "paths": { "/auth/login": { "post": { "tags": [ "authentication" ], "summary": "Authenticate with email and password, returns a JWT", "operationId": "Login", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ] } }, "/me": { "get": { "tags": [ "authentication" ], "summary": "Get the authenticated user's account information", "operationId": "GetMe", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ] } }, "/unified-cases": { "get": { "tags": [ "orders" ], "summary": "Get all unified cases (paginated)", "operationId": "GetUnifiedCases", "parameters": [ { "name": "page", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 20 } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagedResultOfUnifiedCase" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ] } }, "/unified-cases/{id}": { "get": { "tags": [ "orders" ], "summary": "Get a unified case by ID", "operationId": "GetUnifiedCaseById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedCase" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ] } }, "/unified-cases/{id}/files/{filename}": { "get": { "tags": [ "files" ], "summary": "Get a signed download URL for a scan file", "operationId": "GetUnifiedCaseScanFileUrl", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": "integer", "format": "int32" } }, { "name": "filename", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fileType", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ] } }, "/unified-cases/{id}/order-form": { "get": { "tags": [ "files" ], "summary": "Get a signed download URL for the order form PDF", "operationId": "GetUnifiedCaseOrderFormUrl", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ] } }, "/portals/ios": { "get": { "tags": [ "portals" ], "summary": "List all active IOS portals", "operationId": "GetIosPortals", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IosPortal" } } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ] } }, "/portals/configured": { "get": { "tags": [ "portals" ], "summary": "List configured portals for the authenticated organisation", "operationId": "GetConfiguredPortals", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConfiguredPortal" } } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "Bearer": [ ] } ] } } }, "components": { "schemas": { "ConfiguredPortal": { "required": [ "id", "displayName", "username", "lastFetch", "portalName" ], "type": "object", "properties": { "id": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "displayName": { "type": [ "null", "string" ] }, "username": { "type": [ "null", "string" ] }, "lastFetch": { "type": [ "null", "string" ], "format": "date-time" }, "portalName": { "type": [ "null", "string" ] } } }, "IosPortal": { "required": [ "id", "name", "className", "url", "axisMapping", "quantizationBits" ], "type": "object", "properties": { "id": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "name": { "type": [ "null", "string" ] }, "className": { "type": [ "null", "string" ] }, "url": { "type": [ "null", "string" ] }, "axisMapping": { "type": [ "null", "string" ] }, "quantizationBits": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" } } }, "LoginRequest": { "required": [ "email", "password" ], "type": "object", "properties": { "email": { "type": "string" }, "password": { "type": "string" } } }, "MeResponse": { "required": [ "id", "email", "name", "role", "organizations", "portals" ], "type": "object", "properties": { "id": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "email": { "type": "string" }, "name": { "type": [ "null", "string" ] }, "role": { "type": [ "null", "string" ] }, "organizations": { "type": "array", "items": { "$ref": "#/components/schemas/Organization" } }, "portals": { "type": "array", "items": { "$ref": "#/components/schemas/ConfiguredPortal" } } } }, "Organization": { "required": [ "id", "name", "shortname", "cultureInfo", "type", "isOrtho", "parentId", "cluster" ], "type": "object", "properties": { "id": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "name": { "type": "string" }, "shortname": { "type": [ "null", "string" ] }, "cultureInfo": { "type": [ "null", "string" ] }, "type": { "type": "string" }, "isOrtho": { "type": "boolean" }, "parentId": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "cluster": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" } } }, "PagedResultOfUnifiedCase": { "required": [ "items", "page", "pageSize", "total" ], "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UnifiedCase" } }, "page": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "pageSize": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "total": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": [ "null", "string" ] }, "title": { "type": [ "null", "string" ] }, "status": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "detail": { "type": [ "null", "string" ] }, "instance": { "type": [ "null", "string" ] } } }, "UnifiedAdministrative": { "required": [ "dentistOrderNr", "priority", "dueDate", "dueTime", "remake", "patientName", "patientFirstName", "patientLastName", "patientBirthdate", "patientReference", "additionalInfo", "contactRequired", "dentist", "dentistFirstName", "dentistLastName", "labContactPerson", "deliveryNotes" ], "type": "object", "properties": { "dentistOrderNr": { "type": [ "null", "string" ] }, "priority": { "type": "boolean" }, "dueDate": { "type": [ "null", "string" ] }, "dueTime": { "type": [ "null", "string" ] }, "remake": { "type": "boolean" }, "patientName": { "type": [ "null", "string" ] }, "patientFirstName": { "type": [ "null", "string" ] }, "patientLastName": { "type": [ "null", "string" ] }, "patientBirthdate": { "type": [ "null", "string" ] }, "patientReference": { "type": [ "null", "string" ] }, "additionalInfo": { "type": "boolean" }, "contactRequired": { "type": "boolean" }, "dentist": { "type": [ "null", "string" ] }, "dentistFirstName": { "type": [ "null", "string" ] }, "dentistLastName": { "type": [ "null", "string" ] }, "labContactPerson": { "type": [ "null", "string" ] }, "deliveryNotes": { "type": [ "null", "string" ] } } }, "UnifiedCase": { "required": [ "id", "organizationId", "portalId", "configuredPortalId", "caseId", "guid", "acceptedData", "createdAt", "patientFullname", "status", "completenessStatus", "infoRequestStatus" ], "type": "object", "properties": { "id": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "organizationId": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "portalId": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "configuredPortalId": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "caseId": { "type": [ "null", "string" ] }, "guid": { "type": [ "null", "string" ] }, "acceptedData": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UnifiedData" } ] }, "createdAt": { "type": [ "null", "string" ], "format": "date-time" }, "patientFullname": { "type": [ "null", "string" ] }, "status": { "type": [ "null", "string" ] }, "completenessStatus": { "type": [ "null", "string" ] }, "infoRequestStatus": { "type": [ "null", "string" ] } } }, "UnifiedClinic": { "required": [ "externalId", "name", "fullAddress" ], "type": "object", "properties": { "externalId": { "type": [ "null", "string" ] }, "name": { "type": [ "null", "string" ] }, "fullAddress": { "type": [ "null", "string" ] } } }, "UnifiedCustomer": { "required": [ "clinic", "dentist" ], "type": "object", "properties": { "clinic": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UnifiedClinic" } ] }, "dentist": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UnifiedDentist" } ] } } }, "UnifiedData": { "required": [ "uid", "organizationId", "organizationType", "source", "externalId", "originalCreationDate", "originalReceivedDate", "receivedDate", "deliveryDate", "deliveryTime", "sentTo", "customer", "patient", "remark", "isOrtho", "restorations", "scanFiles", "orderForm", "worktypes", "administrative" ], "type": "object", "properties": { "uid": { "type": [ "null", "string" ] }, "organizationId": { "type": [ "null", "string" ] }, "organizationType": { "type": [ "null", "string" ] }, "source": { "type": [ "null", "string" ] }, "externalId": { "type": [ "null", "string" ] }, "originalCreationDate": { "type": [ "null", "string" ], "format": "date-time" }, "originalReceivedDate": { "type": [ "null", "string" ], "format": "date-time" }, "receivedDate": { "type": [ "null", "string" ], "format": "date-time" }, "deliveryDate": { "type": [ "null", "string" ] }, "deliveryTime": { "type": [ "null", "string" ] }, "sentTo": { "type": [ "null", "string" ] }, "customer": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UnifiedCustomer" } ] }, "patient": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UnifiedPatient" } ] }, "remark": { "type": [ "null", "string" ] }, "isOrtho": { "type": "boolean" }, "restorations": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/UnifiedRestoration" } }, "scanFiles": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/UnifiedScanFile" } }, "orderForm": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UnifiedOrderForm" } ] }, "worktypes": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/UnifiedWorktype" } }, "administrative": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UnifiedAdministrative" } ] } } }, "UnifiedDentist": { "required": [ "externalId", "firstName", "lastName", "fullName" ], "type": "object", "properties": { "externalId": { "type": [ "null", "string" ] }, "firstName": { "type": [ "null", "string" ] }, "lastName": { "type": [ "null", "string" ] }, "fullName": { "type": [ "null", "string" ] } } }, "UnifiedOrderForm": { "required": [ "filename", "fileLink", "creationDateTime" ], "type": "object", "properties": { "filename": { "type": [ "null", "string" ] }, "fileLink": { "type": [ "null", "string" ] }, "creationDateTime": { "type": [ "null", "string" ], "format": "date-time" } } }, "UnifiedPatient": { "required": [ "externalId", "gender", "firstName", "lastName", "fullName", "referenceNo", "dateOfBirth" ], "type": "object", "properties": { "externalId": { "type": [ "null", "string" ] }, "gender": { "type": [ "null", "string" ] }, "firstName": { "type": [ "null", "string" ] }, "lastName": { "type": [ "null", "string" ] }, "fullName": { "type": [ "null", "string" ] }, "referenceNo": { "type": [ "null", "string" ] }, "dateOfBirth": { "type": [ "null", "string" ] } } }, "UnifiedRestoration": { "required": [ "codeType", "type", "scoreType", "codeSubType", "subType", "scoreSubType" ], "type": "object", "properties": { "codeType": { "type": [ "null", "string" ] }, "type": { "type": [ "null", "string" ] }, "scoreType": { "type": [ "null", "string" ] }, "codeSubType": { "type": [ "null", "string" ] }, "subType": { "type": [ "null", "string" ] }, "scoreSubType": { "type": [ "null", "string" ] } } }, "UnifiedScanFile": { "required": [ "type", "filename", "creationDateTime", "fileLink", "jaw", "fileType" ], "type": "object", "properties": { "type": { "type": [ "null", "string" ] }, "filename": { "type": [ "null", "string" ] }, "creationDateTime": { "type": [ "null", "string" ], "format": "date-time" }, "fileLink": { "type": [ "null", "string" ] }, "jaw": { "type": [ "null", "string" ] }, "fileType": { "type": [ "null", "string" ] } } }, "UnifiedTag": { "required": [ "type", "value" ], "type": "object", "properties": { "type": { "type": [ "null", "string" ] }, "value": { "type": [ "null", "string" ] } } }, "UnifiedWorktype": { "required": [ "categoryId", "restorationTypeId", "restorationDetailId", "materialId", "settingId", "fdi", "shade", "jaw", "tags" ], "type": "object", "properties": { "categoryId": { "type": [ "null", "string" ] }, "restorationTypeId": { "type": [ "null", "string" ] }, "restorationDetailId": { "type": [ "null", "string" ] }, "materialId": { "type": [ "null", "string" ] }, "settingId": { "type": [ "null", "string" ] }, "fdi": { "type": [ "null", "string" ] }, "shade": { "type": [ "null", "string" ] }, "jaw": { "type": [ "null", "string" ] }, "tags": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/UnifiedTag" } } } } }, "securitySchemes": { "Bearer": { "type": "http", "description": "Enter your JWT Bearer token", "scheme": "bearer", "bearerFormat": "JWT" } } }, "tags": [ { "name": "authentication", "description": "Obtain and manage JWT tokens.", "x-displayName": "Authentication" }, { "name": "orders", "description": "Retrieve normalised case orders.", "x-displayName": "Orders" }, { "name": "portals", "description": "Look up IOS portals and configured portals.", "x-displayName": "Portals" }, { "name": "files", "description": "Obtain pre-authenticated download URLs for scan files.", "x-displayName": "Files" } ], "x-tagGroups": [ { "name": "Authentication", "tags": ["authentication"] }, { "name": "API Reference", "tags": ["orders", "portals", "files"] } ] }