Coding
Coding encodes clinical text into standardised medical coding systems. You send free text or point at a consultation, and get back the clinical entities found in it, each with its codes and its position in the source text.
It is a server-side product: one REST endpoint, authenticated with your API key. There is no SDK method and no widget for it.
Coding systems
| System | coding_systems value | Availability |
|---|---|---|
| SNOMED CT | snomed-ct | Generally available |
| ICD-10 | icd-10 | Early access, invite-only |
ICD-10 is in early access and is only enabled for invited accounts. Email integrations@squire.eu if you want access. See Support.
Encoding text
POST https://api.squire.eu/api/v1/external/medical-coding/
| Header | Required | Description |
|---|---|---|
X-Api-Key | Yes | Your Squire API key. See Authentication |
Content-Type | Yes | application/json |
| Field | Type | Description |
|---|---|---|
coding_systems | string[] | The systems to encode into. See Coding systems. |
text | string | Clinical free text, 1 to 50,000 characters. |
consultation_id | string | ID of a consultation whose active report text is encoded. |
Provide exactly one of text or consultation_id. Use text when the text lives in your own system, and consultation_id when you want to encode a report Squire already produced.
curl -X POST "https://api.squire.eu/api/v1/external/medical-coding/" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"coding_systems": ["snomed-ct"],
"text": "Patient presents with type 2 diabetes mellitus and hypertension."
}'Response
{
"coding_systems": ["snomed-ct"],
"text": "Patient presents with type 2 diabetes mellitus and hypertension.",
"entities": [
{
"entity_text": "type 2 diabetes mellitus",
"entity_start_char": 23,
"entity_end_char": 47,
"negated": false,
"relevance": "high",
"codes": [
{
"code": "44054006",
"code_name": "Type 2 diabetes mellitus (disorder)",
"coding_system": "snomed-ct"
}
]
},
{
"entity_text": "hypertension",
"entity_start_char": 52,
"entity_end_char": 64,
"negated": false,
"relevance": "high",
"codes": [
{
"code": "38341003",
"code_name": "Hypertensive disorder (disorder)",
"coding_system": "snomed-ct"
}
]
}
]
}text is echoed back, so the character offsets always refer to a string you have. Each entry in entities is one clinical concept found in it:
| Field | Type | Description |
|---|---|---|
entity_text | string | The span of source text this entity was read from. |
entity_start_char | number | Start offset of that span in text. |
entity_end_char | number | End offset of that span in text. |
negated | boolean | Whether the text states the concept is absent. |
relevance | string | How central the concept is to the text. |
codes | array | One entry per code found, with code, code_name and coding_system. |
Check negated before you store anything. “No history of hypertension” produces a hypertension entity with negated: true, and recording it as a diagnosis would be wrong.
An entity can carry more than one code, and asking for several coding systems puts all of their codes in the same codes array. Read coding_system on each code rather than relying on position.
The offsets let you highlight the source text in your interface, so a user can see what a code was derived from before accepting it.
Rate limits
250 requests per minute and 1,000 per hour, per API key. Encoding a long document in one request costs the same as a short one, so batch text together where you can rather than calling once per sentence.
Coding in a consultation summary
This endpoint is separate from the codes that come back with a consultation. A consultation summary can include a medical_coding field with ICD-10, ICPC-2 and IBUI codes per diagnosis, produced as part of generating the note. Use this endpoint when you want to encode text on demand, or text Squire did not produce; use the summary field when the codes for a consultation are all you need.