Receive DICOM deliveries

When a hospital sender transmits a DICOM study, Dicomly forwards each instance to your destination URL as a standard STOW-RS HTTP POST. Your application only needs a plain HTTPS endpoint — no DICOM library required on your side.

What the request looks like

Each DICOM instance arrives as a separate request:

POST https://your-app.io/dicom HTTP/1.1
Content-Type: multipart/related; type="application/dicom"; boundary=dicomly_boundary
X-Dicomly-Endpoint-Id: endpoint_01HXYZ
X-Dicomly-Cert-Id: cert_01J5ME
X-Dicomly-Request-Id: req_xyz789

The body is a DICOM STOW-RS multipart payload. Each part contains one DICOM instance in binary form.

Minimal receiver

Acknowledge immediately and hand off to a queue — the sender’s association stays open until your endpoint replies.

import express from 'express';

const app = express();

app.post('/dicom', express.raw({ type: '*/*', limit: '50mb' }), (req, res) => {
  const endpointId = req.headers['x-dicomly-endpoint-id'] as string;
  const certId     = req.headers['x-dicomly-cert-id'] as string;
  const requestId  = req.headers['x-dicomly-request-id'] as string;

  // Hand off to your processing pipeline — do not block here
  queue.push({ endpointId, certId, requestId, body: req.body });

  res.sendStatus(202);
});

How to respond

Status	What Dicomly tells the sender
`200` or `202`	C-STORE success — instance accepted
`5xx`	C-STORE failure — the sender may retry
`4xx`	C-STORE failure — the sender should not retry this instance

Respond as fast as possible. Dicomly holds the DICOM association open while it waits for your reply. A slow response stalls the sender’s modality, which often has a short timeout.

Using the headers

Header	Use
`X-Dicomly-Endpoint-Id`	Which of your endpoints received this instance
`X-Dicomly-Cert-Id`	Opaque ID of the sender’s client certificate — identifies the specific device or site. Maps to the `id` field in your certificate list.
`X-Dicomly-Request-Id`	Stable delivery ID for logging and deduplication

The cert ID is the most useful for routing: when multiple scanners share one endpoint, use it to tell them apart without parsing the DICOM payload.

Operational notes

Do not log the request body. It contains DICOM PHI. Log only the headers and byte count.
Dicomly does not retry on your behalf. A 5xx response propagates back as a DIMSE error; whether the sender retries depends on its own DICOM stack.
Use X-Dicomly-Request-Id to deduplicate if your downstream processing is not idempotent.
Size the body limit to your largest expected study. A single CT series can exceed 200 MB across many instances; each instance arrives as a separate request.