Getting the data out
Four shapes of the same terminology: paged JSON for a running integration, FHIR for a terminology client, and CSV or Excel for a human. Taught in Getting the data you need.
The same system, through the ordinary read
?view=fhir on the detail read serves exactly the representation /export/ does, with the same refusals and the same size bound — two doors onto one method, so they cannot drift apart.
Answers without a credential. What you see is what is published publicly, so an emptier list than you expected is scope rather than absence.
path Parameters
systemThe code system, addressed by its short code (recommended) or its numeric id.
Resolution is pk-first: a value that looks numeric is tried as an id, and falls through to the code column when no row matches, so an all-digits short code is still reachable. Codes are matched case-insensitively after an exact miss. The one ambiguity — a short code identical to some other row's id — resolves to the id.
Example: IDENTIFIER-TYPES.
query Parameters
viewfhir to receive the FHIR CodeSystem rather than the service's own shape.
The same system, through the ordinary read › Responses
Success.
One code system as FHIR, synchronously
The FHIR R4 CodeSystem resource, built and returned in the response. ?format=fhir selects the application/fhir+json media type; plain JSON is also available.
Bounded on purpose: this path holds every concept in memory before responding, so a system above the inline limit answers 413 and names the release job instead. ?_summary=true returns the header with content: "not-present" and costs the same at ten concepts or forty thousand.
A closed code system — a provider rate agreement — has no FHIR representation and answers 406.
Keep from the response: the CodeSystem resource
path Parameters
systemThe code system, addressed by its short code (recommended) or its numeric id.
Resolution is pk-first: a value that looks numeric is tried as an id, and falls through to the code column when no row matches, so an all-digits short code is still reachable. Codes are matched case-insensitively after an exact miss. The one ambiguity — a short code identical to some other row's id — resolves to the id.
Example: IDENTIFIER-TYPES.
query Parameters
versionWhich version of the artefact this read serves.
serving— the version the artefact currently resolves to: the author's or regulator'sMANUALpin if one is set, otherwise the newest released version effective today. This is what an integration should send.- a released version's
version_id(v1.0.0) or its numeric id — exactly that frozen release. Only released versions are honoured; an unknown or unreleased reference falls back to the working copy with a warning rather than failing. draft— the pending draft, for reviewers. Requires the reviewer permission.
Omitted, what you get depends on the artefact: the working copy including drafts while it is unpinned, or the pinned version if an owner has set one. That is what an authoring client wants and the opposite of what a consumer wants — the problem is not that it is always live, but that you cannot tell which you got.
One exception to serving meaning frozen, and it is silent: a code system release predating the content-versioning backfill carries no ordinal, so the read serves the live working copy at 200 with no signal in the body or headers. Detect it on the artefact instead — a released version whose ladder row has sequence: null has no frozen content to serve.
A pinned read is cacheable indefinitely (Cache-Control: immutable); an unversioned one is no-cache, because its content changes on release with no write to the rows it would be cached on.
_summarytrue returns the system's header without its codes. The call that stays cheap however large the system is.
formatfhir for application/fhir+json. Omitted, you get ordinary JSON.
One code system as FHIR, synchronously › Responses
Returns the CodeSystem resource.
Dry-run an export before you generate it
Takes the same body as the create below and answers with a dataset summary and sample rows, storing nothing. Use it to confirm a DELTA really contains what you expect before you queue the real job.
Keep from the response: row_count, sample rows
Dry-run an export before you generate it › Request Body
artifact_kindartifact_idversion_idmodebase_version_idformatDry-run an export before you generate it › Responses
Returns row_count, sample rows.
Generate a file
The one asynchronous export that hands you a file.
The one place a numeric id is unavoidable. artifact_id and version_id are both integers here, so resolve them first: GET /code-systems/<short code>/ gives you the artefact id, and GET /code-systems/<short code>/versions/ gives you the version ids with is_serving marking the one serving resolves to.
Four formats and three modes, and the combination is the whole decision:
- format —
FHIR(R4 JSON),CSV,XLSX, orCODESfor a bare list of codes. - mode —
FULLfor everything belonging to a version,SNAPSHOTfor membership as it stands now (withinclude_inactivedeciding whether withdrawn concepts come too), orDELTAfor only what changed againstbase_version_id.
DELTA is the one worth knowing about: it is how a local copy is updated incrementally rather than re-downloaded whole.
Keep from the response: id
Generate a file › Request Body
artifact_kindartifact_idversion_idmodeformatinclude_inactiveGenerate a file › Responses
Returns id.
idstatusPoll the job
Polling is public — no credential needed. Read status until it is COMPLETED. Do not store output_file_url: it is a presigned link regenerated on every poll, so the one you saved will not be the one that works.
Keep from the response: status, row_count
Answers without a credential. What you see is what is published publicly, so an emptier list than you expected is scope rather than absence.
path Parameters
idThe release job id.
Poll the job › Responses
Returns status, row_count.
idstatusrow_countDownload the file
Redirects to the current presigned URL, so it is always the live one. Unlike polling, this serves the artefact itself and keeps the full permission chain.
Keep from the response: the file
path Parameters
idThe release job id.
Download the file › Responses
Returns the file.
Fire-and-forget CSV export
Queues a CSV export and answers 202 with nothing but a confirmation — no job id, so there is nothing to poll and no link to follow. Prefer a release job whenever you need the file back.
path Parameters
systemThe code system, addressed by its short code (recommended) or its numeric id.
Resolution is pk-first: a value that looks numeric is tried as an id, and falls through to the code column when no row matches, so an all-digits short code is still reachable. Codes are matched case-insensitively after an exact miss. The one ambiguity — a short code identical to some other row's id — resolves to the id.
Example: IDENTIFIER-TYPES.
Fire-and-forget CSV export › Responses
Success.
detail