As part of our product, we allow users to file documents as consultations into EMIS Web via the FileRecord API call. The document is added as an <Attachment> element inside the <ConsultationElement>. We recently added support for adding a SNOMED code to the <Attachment> element. Here’s what the XML looks like before we pass it into the FileRecord call:
<ConsultationElement>
<RefID>2</RefID>
<Header>
<Term>Document</Term>
</Header>
<Attachment>
<RefID>2</RefID>
<GUID>3b302a33-5f84-45be-b8e5-440d4cd915d1</GUID>
<AssignedDate>23/06/2026</AssignedDate>
<AuthorID>
<RefID>3797</RefID>
</AuthorID>
<OriginalAuthor>
<User>
<RefID>3797</RefID>
</User>
<SystemDate>23/06/2026</SystemDate>
</OriginalAuthor>
<DisplayTerm>Seen in gynaecology clinic</DisplayTerm>
<DescriptiveText>Kings Hospital - Seen In Gynaecology Clinic.pdf</DescriptiveText>
<PolicyID>-1</PolicyID>
<Code>
<Term>Seen in gynaecology clinic</Term>
<Value>185221008</Value>
<Scheme>SNOMED</Scheme>
</Code>
<TermID>
<Term>Seen in gynaecology clinic</Term>
<Value>185221008</Value>
<Scheme>SNOMED</Scheme>
</TermID>
<Title>Kings Hospital - Seen In Gynaecology Clinic.pdf</Title>
<Address>C:\Users\ashar\Documents\Faraz Projects\medprompt\medprompt-emis\logs\FileRecordAttachment_YzkxZjBhNmUtMjY5Ny00MmY0LTg3YjAtMTk4MjQzYzRmYjgz.pdf</Address>
<DDSIdentifier>299dd3e8-1673-4942-a6fb-878de68e926a</DDSIdentifier>
</Attachment>
</ConsultationElement>
Note that the <Code> and <TermID> elements are created with the appropriate <Term>, <Value> and <Scheme> attributes for this SNOMED code. This follows the advice from the previous discussion on creating SNOMED codes:
We’re following this rule, but when inspecting the XML after filing away (e.g. via the GetMedicalRecord call), the <Code> and <TermID> always turn into:
I’m guessing a little here but 185221008 is not a clinical document code (child code of 423876004), so EMIS have swapped to a local code for a document.
Would you be able to try a code from this list - NHS North West Genomics v2.1.0 and see if that works (I think this is a Scottish list of document codes and the one PRSB suggests using)
I tried (909921000000109) DNA (did not attend) letter and it encountered the same problem of regressing to that EMISATTACHMENT property. I’ve seen other products manage to successfully code general SNOMED codes so I don’t think EMIS is filtering here, but the problem is that we’re not giving it to EMIS properly.
Is there anyone you know who might be able to shed light on this @mayfield.g.kev ?
Just had a thought - could the GP practice’s EMIS Web system be overriding this property? Such as with a default document type field? Does EMIS Web allow users to do this?
I think description id is only something present in GP Connect. I’ve not seen it used outside of this (including secondary care)
I think it is the DDSIdentifier causing the problem, I don’t think this should be known at this point in the workflow. It will be present on the query interface but that is after this workflow.
“Seen in gynaecology clinic” is a “finding” about a patient that they have been seen in that clinic, and seems to be in the wrong sort of concept to describe the attachment itself.
As Kev says it would seem more appropriate to use a concept about the type of document was used, but you say you have tried (909921000000109) DNA (did not attend) letter without success.
So it would be interesting to see more detail of where you have “seen other products manage to successfully code general SNOMED codes” in this precise context.
I agree with Stuart’s comment that a SNOMED description ID in the would make more sense so might be worth trying one of these description IDs for the three valid terms for 909921000000109 in the slot
2339171000000110 DNA (did not attend) letter
2339181000000112 Did not attend letter
2339191000000114 Did not attend letter (record artifact)
But I feel this is a long shot on many grounds..
Is there no more API documentation?
NB one way to see description IDs is in the “Detail” tab of a concept in the NHS termbrowser but you need to switch on “Display Description IDs” via the settings cog towards top right.
In general Description IDs are to be avoided unless you really know what you are doing. The Concept ID is the key identifier in the vast majority of circumstances.
The other product we’ve seen succeed in doing this is Anima. I had a look at a document saved into a consultation for a GP practice, and it was clear that they could set the document’s SNOMED code to any SNOMED code of their choice, without regressing to EMISATTACHMENT.
Here’s the <Attachment> XML fetched from a patient record’s consultation on EMIS that was filed via Anima. This doesn’t encounter any issues with setting the document’s SNOMED code:
<ConsultationElement>
<FileStatus>0</FileStatus>
<DisplayOrder>3</DisplayOrder>
<ProblemSection>0</ProblemSection>
<Header>
<Term>Document</Term>
</Header>
<Attachment>
<DBID>4276610</DBID>
<RefID>4276610</RefID>
<GUID>{7537E8DA-423D-4AFB-9835-A81650EF4DD5}</GUID>
<FileStatus>0</FileStatus>
<AssignedDate>10/12/2025</AssignedDate>
<DatePart>0</DatePart>
<AssignedTime>00:00:00</AssignedTime>
<AuthorID>
<DBID>325026</DBID>
<RefID>325026</RefID>
<GUID>{7624F0AC-B1EB-49AD-B6C1-B3B47E952610}</GUID>
</AuthorID>
<OriginalAuthor>
<User>
<DBID>325026</DBID>
<RefID>325026</RefID>
<GUID>{7624F0AC-B1EB-49AD-B6C1-B3B47E952610}</GUID>
</User>
<SystemDate>10/12/2025 12:24:22</SystemDate>
</OriginalAuthor>
<DisplayTerm>Referral for further care</DisplayTerm>
<DescriptiveText>NMH - (GP) ECHO referral form - By email.docx</DescriptiveText>
<PolicyID>-1</PolicyID>
<Code>
<Value>8H...</Value>
<Scheme>READ2</Scheme>
<Term>Referral for further care</Term>
<MapCode>183444007</MapCode>
<MapScheme>SNOMED</MapScheme>
</Code>
<TermID>
<Value>8H</Value>
<Scheme>READ2</Scheme>
<Term>Referral for further care</Term>
<MapCode>183444007</MapCode>
<MapScheme>SNOMED</MapScheme>
</TermID>
<Title>Referral for further care.rtf</Title>
<Address>C:\Users\...\AppData\Local\Temp\EMISWebDocs23080\Referral for further care.rtf</Address>
<DDSIdentifier>{45801EA2-8A14-4867-9EFF-8ED6F568C09A}</DDSIdentifier>
<Provisional>false</Provisional>
<PfsVisible>true</PfsVisible>
</Attachment>
</ConsultationElement>
Do you think it’s possible they are sending the Description ID to set the document’s code, instead of my current strategy of <Term>, <Value> and <Scheme> ?
My knowledge of READ V2 (and the way EMIS handles SNOMED and READ) is limited but there still seems to be a strange mixture of Read Code (8H…), a mapped SNOMED concept ID (183444007) and then what looks a bit like it is meant to be a READ TERM code (8H) except that the READ Term code for “Referral for further care” is “00” as far as I can see, and reuse of “183444007” in the TermID bit then seems to add to the mess. But it also depends on how much the API checks the internal consistency of all the quoted codes here…
Is there no API documentation to help any further on this?
I was looking at this and would suggest the same., Looks like you need to writeback a READv2 code, and populate that in the value. it then uses it’s own mapping to cross map to SNOMED.
The documentation they provide should provide examples, but it might be that they only accept Read codes as inouts via the API you are using.
I’ve only used UK SNOMED CT with both EMIS and TPP with no issues.
It may be the wrong type of code (from an informatics perspective it should be a document code) but I’ve found both GP systems loose in what they accept.
I guess the assumption was that, for some consultation elements like <Attachment>, EMIS only accepts READ2 codes.
To test this, I tried out a few different READ2 codes, like 8H...(Referral for further care) from the Anima example, 93A.. (Discharge summary), built as follows:
<Code>
<Value>8H...</Value>
<Scheme>READ2</Scheme>
<Term>Referral for further care</Term>
</Code>
I also tried this style:
<Code>
<Value>8H...</Value>
<Scheme>READ2</Scheme>
<Term>Referral for further care</Term>
</Code>
<TermID>
<Value>8H</Value>
<Scheme>READ2</Scheme>
<Term>Referral for further care</Term>
</TermID>
Then, I also separately tried setting the <MapCode> and <MapScheme> properties to 373942005 and SNOMED respectively for each of the two trials above, even though EMIS is supposed to set them.
In every case, it regressed to EMISATTACHMENT. This is pretty annoying. I’m intrigued as to how Anima managed to make it work while we can’t. Could it be that this method is correct, but the EMIS test system I am using just doesn’t have the READ2 mappings and is therefore regressing to EMISATTACHMENT?
