Populate your patient repository for TEFCA-CommonWell

Last updated: Mar 18, 2026

DEVELOPER

HEALTH TECH VENDOR

Coming soon

This feature is coming soon, so you won’t see it live in a production environment just yet. Stay tuned for the release!

Who can use this how-to

Existing customers using Network Onramps

Before you start querying for data within TEFCA-CommonWell, you must establish a data on demand repository for your patients.

As you continue your patient care, you'll repeat these steps to keep your patient demographics up-to-date as well.

Use curl for technical validation

You can copy our code examples and send the test requests with curl (learn more about curl) instead of Postman. If you do, remember to:

Remove the comments from the code examples (starting with //).
Replace any variables (e.g., {{variable here}}).
Add the source-id if you have multiple sources. We don’t include {{source-id}} in the code examples, so you’ll have to add them yourself. Learn about including source details.
Make sure you have a full request for your own use since some of the code examples are abbreviated.

Check out these troubleshooting guides if you run into errors:

Populate and maintain your patient repository

Before you can start querying for data in TEFCA-CommonWell, you must first establish your patient repository. This is a critical first step in your TEFCA-CommonWell workflow.

Any time patient demographics are updated, however, you must repeat these steps. You must make sure that your patient records and documents stay current in your data on demand repository.

Required extension for PatientAdmin messages

The extensions in the code examples are all required for any PatientAdmin messages. Learn more about extensions.

To generate your organization OID for the sender-organization-id extension, refer to TEFCA identity and organization structure.

Establish new patients

Send a PatientAdmin.NewPatient request for each of your patients to create their patient record in TEFCA-CommonWell to associate your patient with the same patient in external organizations. You must use at least one patient identifier with the ID Type of the patient OID assigned to you.

Example: Create a new patient

bash

1
curl \
2
-X POST https://api.redoxengine.com/endpoint \
3
-H "Content-Type: application/json" \
4
-H "Authorization: Bearer $API_TOKEN" \
5
-d '{
6
    "Meta": {
7
        "Extensions": {
8
            "sender-organization-id": {
9
                "url": "https://api.redoxengine.com/extensions/sender-organization-id",
10
                // The OID representing your organization record within TEFCA-CommonWell.
11
                "string": "{{organization_oid}}"
12
            },
13
            "user-id": {
14
                "url": "https://api.redoxengine.com/extensions/user-id",
15
                // A human-readable name for the user initiating the request.
16
                "string": "{{user-name}}"
17
            },
18
            "user-role": {
19
                "url": "https://api.redoxengine.com/extensions/user-role",
20
                // The role of the user identified above. This must be a SNOMED CT code.
21
                "coding": {
22
                    "code": "{{user_role}}",
23
                    // Set to the default code (112247003), but change if needed.
24
                    "display": "Medical Doctor"
25
                }
26
            },
27
            "purpose-of-use": {
28
                "url": "https://api.redoxengine.com/extensions/purpose-of-use",
29
                 // The purpose of the TEFCA query, which is almost always TREATMENT. 
30
                "coding": {
31
                    "code": "TREATMENT",
32
                    "display": "Treatment"
33
                }
34
            }
35
        },
36
        "DataModel": "PatientAdmin",
37
        "EventType": "NewPatient",
38
        // remove in production
39
        "Test": true,
40
        "Destinations": [
41
            {
42
                // This is your development destination ID (and will change for production)
43
                "ID": "3122bfff-f1fb-4fdf-97de-294f24338229"
44
            }
45
        ]
46
    },
47
    "Patient": {
48
        "Identifiers": [
49
            {
50
                // This ID should be the MRN or primary ID of the patient in your system. 
51
                "ID": "1234",
52
                // The "IDType" should map from your ID type to the value Redox provides. Typically, this means mapping a value like "MR" to this OID. This OID is linked to the repository and required to associate the patient.
53
                "IDType": "{{patient_oid}}"
54
            }
55
        ],
56
        // Everything below should be set as appropriate for your organization. Review our API reference for supported patient demographics.
57
        "Demographics": {
58
            "FirstName": "Timothy",
59
            "MiddleName": "Paul",
60
            "LastName": "Bixby",
61
            "DOB": "2008-01-06",
62
            "SSN": "101-01-0001",
63
            "Sex": "Male",
64
            "Race": "White",
65
            "IsHispanic": null,
66
            "MaritalStatus": "Married",
67
            "IsDeceased": null,
68
            "DeathDateTime": null,
69
            "PhoneNumber": {
70
                "Home": "+18088675301",
71
                "Office": null,
72
                "Mobile": null
73
            },
74
            "EmailAddresses": [],
75
            "Language": "en",
76
            "Citizenship": [],
77
            "Address": {
78
                "StreetAddress": "4762 Hickory Street",
79
                "City": "Monroe",
80
                "State": "WI",
81
                "ZIP": "53566",
82
                "County": "Green",
83
                "Country": "US"
84
            }
85
        },
86
        "Notes": [],
87
        "Contacts": [
88
            {
89
                "FirstName": "Barbara",
90
                "MiddleName": null,
91
                "LastName": "Bixby",
92
                "Address": {
93
                    "StreetAddress": "4762 Hickory Street",
94
                    "City": "Monroe",
95
                    "State": "WI",
96
                    "ZIP": "53566",
97
                    "County": "Green",
98
                    "Country": "US"
99
                },
100
                "PhoneNumber": {
101
                    "Home": "+18088675303",
102
                    "Office": "+17077543758",
103
                    "Mobile": "+19189368865"
104
                },
105
                "RelationToPatient": "Mother",
106
                "EmailAddresses": [
107
                    "barb.bixby@test.net"
108
                ],
109
                "Roles": [
110
                    "Emergency Contact"
111
                ]
112
            }
113
        ],
114
        "Allergies": [
115
            {
116
                "Code": "7982",
117
                "Codeset": "RxNorm",
118
                "Name": "Penicillin",
119
                "Type": {
120
                    "Code": null,
121
                    "Codeset": null,
122
                    "Name": null
123
                },
124
                "OnsetDateTime": null,
125
                "Reaction": [
126
                    {
127
                        "Code": "28926001",
128
                        "Codeset": "SNOMED CT",
129
                        "Name": "Rash"
130
                    },
131
                    {
132
                        "Code": "247472004",
133
                        "Codeset": "SNOMED CT",
134
                        "Name": "Hives"
135
                    }
136
                ],
137
                "Severity": {
138
                    "Code": null,
139
                    "Codeset": null,
140
                    "Name": null
141
                },
142
                "Status": null
143
            }
144
        ],
145
        "PCP": {
146
            "NPI": "4356789876",
147
            "ID": "4356789876",
148
            "IDType": "NPI",
149
            "FirstName": "Pat",
150
            "LastName": "Granite",
151
            "Credentials": [
152
                "MD"
153
            ],
154
            "Address": {
155
                "StreetAddress": "123 Main St.",
156
                "City": "Madison",
157
                "State": "WI",
158
                "ZIP": "53703",
159
                "County": "Dane",
160
                "Country": "USA"
161
            },
162
            "EmailAddresses": [],
163
            "PhoneNumber": {
164
                "Office": "+16085551234"
165
            },
166
            "Location": {
167
                "Type": null,
168
                "Facility": null,
169
                "Department": null,
170
                "Room": null
171
            }
172
        },
173
        "Guarantor": {
174
            "Number": "10001910",
175
            "FirstName": "Kent",
176
            "MiddleName": null,
177
            "LastName": "Bixby",
178
            "SSN": null,
179
            "DOB": null,
180
            "Sex": null,
181
            "Spouse": {
182
                "FirstName": "Barbara",
183
                "LastName": "Bixby"
184
            },
185
            "Address": {
186
                "StreetAddress": "4762 Hickory Street",
187
                "City": "Monroe",
188
                "State": "WI",
189
                "ZIP": "53566",
190
                "County": "Green",
191
                "Country": "USA"
192
            },
193
            "PhoneNumber": {
194
                "Home": null,
195
                "Business": null,
196
                "Mobile": null
197
            },
198
            "EmailAddresses": [],
199
            "Type": null,
200
            "RelationToPatient": "Father",
201
            "Employer": {
202
                "Name": "Accelerator Labs",
203
                "Address": {
204
                    "StreetAddress": "1456 Old Sauk Road",
205
                    "City": "Madison",
206
                    "State": "WI",
207
                    "ZIP": "53719",
208
                    "County": "Dane",
209
                    "Country": "USA"
210
                },
211
                "PhoneNumber": "+18083451121"
212
            }
213
        },
214
        "Insurances": [
215
            {
216
                "Plan": {
217
                    "ID": "31572",
218
                    "IDType": "Payor ID",
219
                    "Name": "HMO Deductable Plan",
220
                    "Type": null
221
                },
222
                "MemberNumber": null,
223
                "Company": {
224
                    "ID": "60054",
225
                    "IDType": null,
226
                    "Name": "aetna (60054 0131)",
227
                    "Address": {
228
                        "StreetAddress": "PO Box 14080",
229
                        "City": "Lexington",
230
                        "State": "KY",
231
                        "ZIP": "40512-4079",
232
                        "County": "Fayette",
233
                        "Country": "US"
234
                    },
235
                    "PhoneNumber": "+18089541123"
236
                },
237
                "GroupNumber": "847025-024-0009",
238
                "GroupName": "Accelerator Labs",
239
                "EffectiveDate": "2015-01-01",
240
                "ExpirationDate": "2020-12-31",
241
                "PolicyNumber": "9140860055",
242
                "AgreementType": null,
243
                "CoverageType": null,
244
                "Insured": {
245
                    "Identifiers": [],
246
                    "LastName": null,
247
                    "MiddleName": null,
248
                    "FirstName": null,
249
                    "SSN": null,
250
                    "Relationship": null,
251
                    "DOB": null,
252
                    "Sex": null,
253
                    "Address": {
254
                        "StreetAddress": null,
255
                        "City": null,
256
                        "State": null,
257
                        "ZIP": null,
258
                        "County": null,
259
                        "Country": null
260
                    }
261
                }
262
            }
263
        ]
264
    }
265
}

API reference

Review the PatientAdmin data model schema for more technical details.

Update existing patient demographics

If demographics or contact information changes for existing patients, send a PatientAdmin.PatientUpdate request with the updated details before querying for data.

Example: Update an existing patient

bash

1
curl \
2
-X POST https://api.redoxengine.com/endpoint \
3
-H "Content-Type: application/json" \
4
-H "Authorization: Bearer $API_TOKEN" \
5
-d '{
6
    "Meta": {
7
        "Extensions": {
8
            "sender-organization-id": {
9
                "url": "https://api.redoxengine.com/extensions/sender-organization-id",
10
                // The OID representing your organization record within TEFCA-CommonWell.
11
                "string": "{{organization_oid}}"
12
            },
13
            "user-id": {
14
                "url": "https://api.redoxengine.com/extensions/user-id",
15
                // A human-readable name for the user initiating the request.
16
                "string": "{{user-name}}"
17
            },
18
            "user-role": {
19
                "url": "https://api.redoxengine.com/extensions/user-role",
20
                // The role of the user identified above. This must be a SNOMED CT code.
21
                "coding": {
22
                    "code": "{{user_role}}",
23
                    // Set to the default code (112247003), but change if needed.
24
                    "display": "Medical Doctor"
25
                }
26
            },
27
            "purpose-of-use": {
28
                "url": "https://api.redoxengine.com/extensions/purpose-of-use",
29
                 // The purpose of the TEFCA query, which is almost always TREATMENT. 
30
                "coding": {
31
                    "code": "TREATMENT",
32
                    "display": "Treatment"
33
                }
34
            }
35
        },
36
        "DataModel": "PatientAdmin",
37
        "EventType": "PatientUpdate",
38
        // Remove in production
39
        "Test": true,
40
        "Destinations": [
41
            {
42
                // This is your development destination ID (and will change for production)
43
                "ID": "3122bfff-f1fb-4fdf-97de-294f24338229"
44
            }
45
        ]
46
    },
47
    "Patient": {
48
        "Identifiers": [
49
            {
50
                // This ID should be the MRN or primary ID of the patient in your system.
51
                "ID": "1234",
52
                // The IDType should map from your ID type to the value Redox provides. Typically this is mapping some value like "MR" to this OID. This OID is linked to the repository and required to associate the patient.
53
                "IDType": "{{patient-oid}}"
54
            }
55
        ],
56
        // Everything below should be set as appropriate for your organization. Review our API reference for supported patient demographics.
57
        "Demographics": {
58
            "FirstName": "Timothy",
59
            "MiddleName": "Paul",
60
            "LastName": "Bixby",
61
            "DOB": "2008-01-06",
62
            "SSN": "101-01-0001",
63
            "Sex": "Male",
64
            "Race": "White",
65
            "IsHispanic": null,
66
            "MaritalStatus": "Married",
67
            "IsDeceased": null,
68
            "DeathDateTime": null,
69
            "PhoneNumber": {
70
                "Home": "+18088675301",
71
                "Office": null,
72
                "Mobile": null
73
            },
74
            "EmailAddresses": [],
75
            "Language": "en",
76
            "Citizenship": [],
77
            "Address": {
78
                "StreetAddress": "4435 Victoria Ln",
79
                "City": "Madison",
80
                "State": "WI",
81
                "ZIP": "53719",
82
                "County": "Dane",
83
                "Country": "US"
84
            }
85
        },
86
        "Notes": [],
87
        "Contacts": [
88
            {
89
                "FirstName": "Barbara",
90
                "MiddleName": null,
91
                "LastName": "Bixby",
92
                "Address": {
93
                    "StreetAddress": "4762 Hickory Street",
94
                    "City": "Monroe",
95
                    "State": "WI",
96
                    "ZIP": "53566",
97
                    "County": "Green",
98
                    "Country": "US"
99
                },
100
                "PhoneNumber": {
101
                    "Home": "+18088675303",
102
                    "Office": "+17077543758",
103
                    "Mobile": "+19189368865"
104
                },
105
                "RelationToPatient": "Mother",
106
                "EmailAddresses": [
107
                    "barb.bixby@test.net"
108
                ],
109
                "Roles": [
110
                    "Emergency Contact"
111
                ]
112
            }
113
        ],
114
        "Diagnoses": [
115
            {
116
                "Code": "R07.0",
117
                "Codeset": "ICD-10",
118
                "Name": "Pain in throat",
119
                "Type": null,
120
                "DocumentedDateTime": null
121
            }
122
        ],
123
        "Allergies": [
124
            {
125
                "Code": "7982",
126
                "Codeset": "RxNorm",
127
                "Name": "Penicillin",
128
                "Type": {
129
                    "Code": null,
130
                    "Codeset": null,
131
                    "Name": null
132
                },
133
                "OnsetDateTime": null,
134
                "Reaction": [
135
                    {
136
                        "Code": "28926001",
137
                        "Codeset": "SNOMED CT",
138
                        "Name": "Rash"
139
                    },
140
                    {
141
                        "Code": "247472004",
142
                        "Codeset": "SNOMED CT",
143
                        "Name": "Hives"
144
                    }
145
                ],
146
                "Severity": {
147
                    "Code": null,
148
                    "Codeset": null,
149
                    "Name": null
150
                },
151
                "Status": null
152
            }
153
        ],
154
        "PCP": {
155
            "NPI": "4356789876",
156
            "ID": "4356789876",
157
            "IDType": "NPI",
158
            "FirstName": "Pat",
159
            "LastName": "Granite",
160
            "Credentials": [
161
                "MD"
162
            ],
163
            "Address": {
164
                "StreetAddress": "123 Main St.",
165
                "City": "Madison",
166
                "State": "WI",
167
                "ZIP": "53703",
168
                "County": "Dane",
169
                "Country": "USA"
170
            },
171
            "EmailAddresses": [],
172
            "PhoneNumber": {
173
                "Office": "+16085551234"
174
            },
175
            "Location": {
176
                "Type": null,
177
                "Facility": null,
178
                "Department": null,
179
                "Room": null
180
            }
181
        },
182
        "Insurances": [
183
            {
184
                "Plan": {
185
                    "ID": "31572",
186
                    "IDType": "Payor ID",
187
                    "Name": "HMO Deductable Plan",
188
                    "Type": null
189
                },
190
                "MemberNumber": null,
191
                "Company": {
192
                    "ID": "60054",
193
                    "IDType": null,
194
                    "Name": "aetna (60054 0131)",
195
                    "Address": {
196
                        "StreetAddress": "PO Box 14080",
197
                        "City": "Lexington",
198
                        "State": "KY",
199
                        "ZIP": "40512-4079",
200
                        "County": "Fayette",
201
                        "Country": "US"
202
                    },
203
                    "PhoneNumber": "+18089541123"
204
                },
205
                "GroupNumber": "847025-024-0009",
206
                "GroupName": "Accelerator Labs",
207
                "EffectiveDate": "2015-01-01",
208
                "ExpirationDate": "2020-12-31",
209
                "PolicyNumber": "9140860055",
210
                "AgreementType": null,
211
                "CoverageType": null,
212
                "Insured": {
213
                    "Identifiers": [],
214
                    "LastName": null,
215
                    "MiddleName": null,
216
                    "FirstName": null,
217
                    "SSN": null,
218
                    "Relationship": null,
219
                    "DOB": null,
220
                    "Sex": null,
221
                    "Address": {
222
                        "StreetAddress": null,
223
                        "City": null,
224
                        "State": null,
225
                        "ZIP": null,
226
                        "County": null,
227
                        "Country": null
228
                    }
229
                }
230
            }
231
        ],
232
        "Guarantor": {
233
            "Number": "10001910",
234
            "FirstName": "Kent",
235
            "MiddleName": null,
236
            "LastName": "Bixby",
237
            "SSN": null,
238
            "DOB": null,
239
            "Sex": null,
240
            "Spouse": {
241
                "FirstName": "Barbara",
242
                "LastName": "Bixby"
243
            },
244
            "Address": {
245
                "StreetAddress": "4762 Hickory Street",
246
                "City": "Monroe",
247
                "State": "WI",
248
                "ZIP": "53566",
249
                "County": "Green",
250
                "Country": "USA"
251
            },
252
            "PhoneNumber": {
253
                "Home": null,
254
                "Business": null,
255
                "Mobile": null
256
            },
257
            "EmailAddresses": [],
258
            "Type": null,
259
            "RelationToPatient": "Father",
260
            "Employer": {
261
                "Name": "Accelerator Labs",
262
                "Address": {
263
                    "StreetAddress": "1456 Old Sauk Road",
264
                    "City": "Madison",
265
                    "State": "WI",
266
                    "ZIP": "53719",
267
                    "County": "Dane",
268
                    "Country": "USA"
269
                },
270
                "PhoneNumber": "+18083451121"
271
            }
272
        }
273
    }
274
}

Combine duplicate patient records

To combine duplicate records for one patient, send a PatientAdmin.PatientMerge request to merge the patient records and replace the previous identifiers with the new one before querying for data.

Example: Merge patient records

bash

1
curl \
2
-X POST https://api.redoxengine.com/endpoint \
3
-H "Content-Type: application/json" \
4
-H "Authorization: Bearer $API_TOKEN" \
5
-d '{
6
    "Meta": {
7
        "Extensions": {
8
            "sender-organization-id": {
9
                "url": "https://api.redoxengine.com/extensions/sender-organization-id",
10
                // The OID representing your organization record within TEFCA-CommonWell.
11
                "string": "{{organization_oid}}"
12
            },
13
            "user-id": {
14
                "url": "https://api.redoxengine.com/extensions/user-id",
15
                // A human-readable name for the user initiating the request.
16
                "string": "{{user-name}}"
17
            },
18
            "user-role": {
19
                "url": "https://api.redoxengine.com/extensions/user-role",
20
                // The role of the user identified above. This must be a SNOMED CT code.
21
                "coding": {
22
                    "code": "{{user_role}}",
23
                    // Set to the default code (112247003), but change if needed.
24
                    "display": "Medical Doctor"
25
                }
26
            },
27
            "purpose-of-use": {
28
                "url": "https://api.redoxengine.com/extensions/purpose-of-use",
29
                 // The purpose of the TEFCA query, which is almost always TREATMENT. 
30
                "coding": {
31
                    "code": "TREATMENT",
32
                    "display": "Treatment"
33
                }
34
            }
35
        },        
36
        "DataModel": "PatientAdmin",
37
        "EventType": "PatientMerge",
38
        // Remove in production
39
        "Test": true,
40
        "Destinations": [
41
            {
42
            // This is your development destination ID (and will change for production)
43
                "ID": "3122bfff-f1fb-4fdf-97de-294f24338229"
44
            }
45
        ]
46
    },
47
    "Patient": {
48
        "Identifiers": [
49
            {
50
                // This is the new ID for the patient.
51
                "ID": "1235",
52
                "IDType": "{{patient-oid}}"
53
            }
54
        ],
55
        // This will be the old ID that this patient had.
56
        "PreviousIdentifiers": [
57
            {
58
                "ID": "1234",
59
                "IDType": "{{patient-oid}}"
60
            }
61
        ],
62
        // Everything below should be set as appropriate for your organization. Review our API reference for supported patient demographics.
63
        "Demographics": {
64
            "FirstName": "Timothy",
65
            "MiddleName": "Paul",
66
            "LastName": "Bixby",
67
            "DOB": "2008-01-06",
68
            "SSN": "101-01-0001",
69
            "Sex": "Male",
70
            "Race": "White",
71
            "IsHispanic": null,
72
            "MaritalStatus": "Married",
73
            "IsDeceased": null,
74
            "DeathDateTime": null,
75
            "PhoneNumber": {
76
                "Home": "+18088675301",
77
                "Office": null,
78
                "Mobile": null
79
            },
80
            "EmailAddresses": [],
81
            "Language": "en",
82
            "Citizenship": [],
83
            "Address": {
84
                "StreetAddress": "4762 Hickory Street",
85
                "City": "Monroe",
86
                "State": "WI",
87
                "ZIP": "53566",
88
                "County": "Green",
89
                "Country": "US"
90
            }
91
        },
92
        "Notes": []
93
    }
94
}

Onramp to TEFCA resources

Basic information

How-to

Troubleshooting

Common TEFCA errors

FHIR® is a registered trademark of Health Level Seven International (HL7) and is used with the permission of HL7. Use of this trademark does not constitute an endorsement of products/services by HL7®.