In the box

Roster pull: match a patient list to the EHR.

Clinical Extract matches the list you already have against the EHR and grades every row, and you review only the uncertain matches. Rows you confirm become the study cohort, and Clinical Extract exports their records.

Request a demo Build a cohort instead

1 The grade

How a row gets its grade.

Roster pull tries the strongest identifier first. An MRN is looked up exactly. A name with a date of birth (and sex, when you have it) goes through the FHIR Patient/$match operation, and the EHR answers with its own certainty. What is left goes through a demographic search. Each row gets one of five grades: certain, probable, possible, multiple or none.

How a row gets its gradeA decision path for one pasted roster row, in three numbered branches tried in order. Branch 1, the row has an MRN, for example 0048152: Clinical Extract sends GET /Patient?identifier={mrn-system}|0048152, and a searchset Bundle with total 1 grades the row certain. Branch 2, the row has no MRN, so its name, date of birth and sex, for example Ortiz, M., 1972-11-19, F, go to POST /Patient/$match as a Parameters resource holding a Patient with name, birthDate and gender, with onlyCertainMatches false. This call is highlighted. Each returned entry carries a match-grade extension on Bundle.entry.search: match-grade certain grades the row certain, and match-grade possible grades it possible. Branch 3, when $match returns no entry, a demographic search runs, GET /Patient?family=Hale&given=Ruth&birthdate=1958-04-02&gender=female. A Bundle total of 1 grades the row probable, a total of 2 or more grades it multiple, and a total of 0 grades it none. The grades are ink tints from solid to open: certain, probable, possible, multiple, none. Certain, probable and possible rows join the cohort when you confirm them; multiple and none rows are held for your review.EACH PASTED ROWREQUEST TO YOUR EHRRESPONSEGRADENEXT1MRN givenMRN 0048152GET /Patient  ?identifier={mrn-system}|0048152total 1, exactcertainjoins when you confirmno MRN in the row2No MRNname, DOB, sexOrtiz, M. 1972-11-19 FPOST /Patient/$matchParameters  resource: Patient    name, birthDate, gender  onlyCertainMatches: falsematch-grade: an extension onBundle.entry.searchmatch-grade: certaincertainjoins when you confirmmatch-grade: possiblepossiblejoins when you confirmno entry returned3Fallbackdemographic searchHale, Ruth 1958-04-02 FGET /Patient?family=Hale  &given=Ruth  &birthdate=1958-04-02  &gender=femaletotal 1probablejoins when you confirmtotal 2 or moremultipleheld for your reviewtotal 0noneheld for your review
How a row gets its gradeA decision path for one pasted roster row, in three numbered branches tried in order. Branch 1, the row has an MRN, for example 0048152: Clinical Extract sends GET /Patient?identifier={mrn-system}|0048152, and a searchset Bundle with total 1 grades the row certain. Branch 2, the row has no MRN, so its name, date of birth and sex, for example Ortiz, M., 1972-11-19, F, go to POST /Patient/$match as a Parameters resource holding a Patient with name, birthDate and gender, with onlyCertainMatches false. This call is highlighted. Each returned entry carries a match-grade extension on Bundle.entry.search: match-grade certain grades the row certain, and match-grade possible grades it possible. Branch 3, when $match returns no entry, a demographic search runs, GET /Patient?family=Hale&given=Ruth&birthdate=1958-04-02&gender=female. A Bundle total of 1 grades the row probable, a total of 2 or more grades it multiple, and a total of 0 grades it none. The grades are ink tints from solid to open: certain, probable, possible, multiple, none. Certain, probable and possible rows join the cohort when you confirm them; multiple and none rows are held for your review.EACH PASTED ROW, IN ORDER1MRN givenMRN 0048152GET /Patient  ?identifier={mrn-system}|0048152total 1, exactcertainno MRN in the row2No MRNOrtiz, M. 1972-11-19 Fname, DOB, sexPOST /Patient/$matchParameters  resource: Patient    name, birthDate, gender  onlyCertainMatches: falsematch-grade: an extension onBundle.entry.searchmatch-grade: certaincertainmatch-grade: possiblepossibleno entry returned3FallbackHale, Ruth 1958-04-02 Fdemographic searchGET /Patient?family=Hale  &given=Ruth  &birthdate=1958-04-02  &gender=femaletotal 1probabletotal 2 or moremultipletotal 0nonecertain, probable and possible rows jointhe cohort when you confirm them; multipleand none rows are held for your review
Figure 1. How a row gets its grade. Roster pull tries the strongest identifier first: an exact MRN, then the FHIR Patient/$match operation on name, date of birth and sex, then a demographic search. The grade tells you which rows to look at: rows you confirm join the study cohort, and multiple and none rows are held for your review. The rows shown are synthetic.

2 What you paste

MRNs, or names with dates of birth, or a CSV.

MRNs
One per line. Each is looked up exactly and graded certain on a hit.
Last, First, YYYY-MM-DD
Name and date of birth per line. Add a sex column and $match answers with more certainty.
A CSV
Columns mrn, first, last, dob (and sex); the columns you have are used, the rest are ignored.
The source
Pick the EHR the list belongs to; a network runs the list against each source in turn.
Up to 500 rows a run
With live per-row progress, and batches for a longer list.
The result
One dataset with a grade per patient, opened in the same view the export uses.

3 The five grades

What each grade means, and what you do with it.

Certain
An exact MRN hit, or a $match answer graded certain. Joins the cohort when you confirm the batch.
Probable
A single hit from the demographic search. Worth a glance; a sex column raises it.
Possible
A $match answer the EHR marked possible. You look at the candidate before confirming.
Multiple
More than one candidate. Held for your review with every candidate shown.
None
No candidate. Held; you correct the row or drop it.

4 After the match

Confirmed rows become the study cohort.

The export then reads everything the source holds on each confirmed patient for the resource types the protocol names, and writes study.csv and its data dictionary. A registry runs its annual follow-back this way (the registry page shows the follow-up items); a chart review study starts from the same list (running a chart review study walks it end to end).

5 Questions

Questions about matching

What is FHIR $match?

The FHIR operation Patient/$match: you send a Patient resource with what you know (name, date of birth, sex, an identifier) and the EHR answers with the patients it believes are the same person, each with a certainty grade. Roster pull uses it for every row that has no exact MRN.

Is this probabilistic matching?

The grade is the EHR’s own judgment: an exact MRN is certain by definition, a $match answer carries the EHR’s certainty, and a demographic search is graded by how many patients it returns. Roster pull reports that grade for each row and computes no probability of its own, so what you review is what the EHR said.

What about matching across two sources?

Each source is matched on its own, with its own grade per row, and the rows that match in both sources carry both patient references. Linking them into one record is a rule you set in your analysis; roster pull keeps both references in the CSV.

What happens to a row that matches two patients?

It is graded multiple and held for your review, with both candidates shown. A row that matches nobody is graded none and held the same way. Neither joins the cohort until you confirm it.

How many rows can I paste?

Up to 500 a run, with live per-row progress. A larger list runs in batches, and a cohort defined by criteria rather than a list runs through the cohort builder instead.

Next

See Clinical Extract run on one of your studies.

Tell us which EHR you run and what the study or registry needs. We reply within one business day to set a meeting time.

Request a demo