Populate your patient repository for TEFCA-CommonWell

Last updated: Apr 30, 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.

The destination ID changes based on environment type:
- Development destination ID: 3122bfff-f1fb-4fdf-97de-294f24338229
- Production destination ID: 7fd005ac-d788-40c5-b4e8-b57bb8e310a9
For production queries, set the Test value to false.

Example: Create a new patient in TEFCA-CommonWell

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

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 in TEFCA-CommonWell

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

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 in TEFCA-CommonWell

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
                "string": "{{ORGANIZATION-OID}}"
11
            },
12
            "user-id": {
13
                "url": "https://api.redoxengine.com/extensions/user-id",
14
                "string": "{{SENDING-USER-NAME}}"
15
            },
16
            "user-role": {
17
                "url": "https://api.redoxengine.com/extensions/user-role",
18
                // The role of the user identified above. This must be a SNOMED CT code.
19
                "coding": {
20
                    "code": "112247003",
21
                    "display": "Medical Doctor"
22
                }
23
            },
24
            "purpose-of-use": {
25
                "url": "https://api.redoxengine.com/extensions/purpose-of-use",
26
                "coding": {
27
                    "code": "TREATMENT",
28
                    "display": "Treatment"
29
                }
30
            }
31
        },        
32
        "DataModel": "PatientAdmin",
33
        "EventType": "PatientMerge",
34
        "Test": true,
35
        "Destinations": [
36
            {
37
            // This is your development destination ID (and will change for production)
38
                "ID": "3122bfff-f1fb-4fdf-97de-294f24338229"
39
            }
40
        ]
41
    },
42
    "Patient": {
43
        "Identifiers": [
44
            {
45
                // This is the new ID for the patient.
46
                "ID": "1235",
47
                "IDType": "{{patient-oid}}"
48
            }
49
        ],
50
        // This will be the old ID that this patient had.
51
        "PreviousIdentifiers": [
52
            {
53
                "ID": "1234",
54
                "IDType": "{{patient-oid}}"
55
            }
56
        ],
57
        // Everything below should be set as appropriate for your organization. Review our API reference for supported patient demographics.
58
        "Demographics": {
59
            "FirstName": "Timothy",
60
            "MiddleName": "Paul",
61
            "LastName": "Bixby",
62
            "DOB": "2008-01-06",
63
            "SSN": "101-01-0001",
64
            "Sex": "Male",
65
            "Race": "White",
66
            "IsHispanic": null,
67
            "MaritalStatus": "Married",
68
            "IsDeceased": null,
69
            "DeathDateTime": null,
70
            "PhoneNumber": {
71
                "Home": "+18088675301",
72
                "Office": null,
73
                "Mobile": null
74
            },
75
            "EmailAddresses": [],
76
            "Language": "en",
77
            "Citizenship": [],
78
            "Address": {
79
                "StreetAddress": "4762 Hickory Street",
80
                "City": "Monroe",
81
                "State": "WI",
82
                "ZIP": "53566",
83
                "County": "Green",
84
                "Country": "US"
85
            }
86
        },
87
        "Notes": []
88
    }
89
}

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®.