Create an organization record with FHIR

Last updated: May 29, 2025

IMPLEMENTATION

Who can use this how-to

Existing customers using Network Onramps to connect to the Carequality Interoperability Framework
Existing customers with a direct connection to Carequality (i.e., without Redox)

An organization record (i.e., OID within the Redox organization or your own OID) is the unique identifier for your organization within the Carequality Interoperability Framework. The organization OID is how you identify yourself when searching for patients—and how other Carequality participants can find you and your patients.

You should plan to register at least one Carequality organization record per unique master patient index (MPI) or physical location. Learn more about OIDs and identity to understand why you may want to register more than one organization.

Data model option

Did you know you can also do this workflow with Redox data models? Learn how to create an organization record with the Redox Data Model API.

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:

Canada URL

If you’re operating in Canada, you have to tweak the Redox hostname slightly. Add ca in the URL like this: https://api.ca.redoxengine.com.

Destination slugs

You must populate any test queries with the appropriate FHIR® destination slug for the specific type of request:

Query purpose	Destination slug
Query for/create/update/delete an organization	`ceq-orgs`
Perform a patient search within a specific organization	`ceq-xcpd:{{org-oid-obtained-from-organization-query}}`
Search for a clinical summary/document	`ceq-xca:{{org-oid-obtained-from-organization-query}}`

Which OID to use

The {{org-oid-obtained-from-organization-query}} should be the OID of the Carequality participant you’re querying, not the OID of your Carequality organization.

Create your organization record

In your development environment, using Postman or curl, send an Organization create request to create your organization record in Carequality. The id property should match the OID provided in the identifier array and is required.

FHIR example: Create an organization record

bash

1
curl --request POST \
2
  --url https://api.redoxengine.com/fhir/R4/ceq-orgs/Development/Organization \
3
  --header 'Content-Type: application/json' \
4
  --data '{
5
  "resourceType": "Organization",
6
  "id": "2.16.840.1.113883.3.6147.458.2",
7
  "identifier": [
8
    {
9
      "use": "official",
10
      "system": "http://www.hl7.org/oid/",
11
      "value": "2.16.840.1.113883.3.6147.458.2"
12
    }
13
  ],
14
  "active": true,
15
  "type": [
16
    {
17
      "coding": [
18
        {
19
          "system": "http://hl7.org/fhir/organization-type",
20
          "code": "Connection"
21
        }
22
      ]
23
    }
24
  ],
25
  "name": "Redox Gateway",
26
  "alias": [
27
    ""
28
  ],
29
  "address": [
30
    {
31
      "use": "work",
32
      "type": "both",
33
      "line": [
34
        "25 West Main Street, Suite 500"
35
      ],
36
      "city": "Madison",
37
      "state": "WI",
38
      "postalCode": "53703",
39
      "country": "USA"
40
    }
41
  ],
42
  "partOf": {
43
    "identifier": {
44
      "use": "official",
45
      "system": "http://www.hl7.org/oid/",
46
      "type": {
47
        "text": "HCID"
48
      },
49
      "value": "2.16.840.1.113883.3.6147.458"
50
    }
51
  },
52
  "contact": [
53
    {
54
      "purpose": {
55
        "text": "Technical"
56
      },
57
      "name": {
58
        "use": "official",
59
        "text": "Redox, Carequality"
60
      },
61
      "telecom": [
62
        {
63
          "system": "email",
64
          "value": "carequality@redoxengine.com",
65
          "use": "work"
66
        },
67
        {
68
          "system": "phone",
69
          "value": "+16085359501",
70
          "use": "work"
71
        }
72
      ]
73
    },
74
    {
75
      "purpose": {
76
        "text": "Business"
77
      },
78
      "name": {
79
        "use": "official",
80
        "text": "Redox, Carequality"
81
      },
82
      "telecom": [
83
        {
84
          "system": "email",
85
          "value": "support@redoxengine.com",
86
          "use": "work"
87
        },
88
        {
89
          "system": "phone",
90
          "value": "+16085359501",
91
          "use": "work"
92
        }
93
      ]
94
    }
95
  ]
96
}

API reference

Review the Organization schema for more technical details.

If the request is successful, you receive a synchronous response indicating that your organization record was created.
FHIR Example: Successful response for creating an organization record
json
1
200 OK
Once you complete all of your testing, repeat these steps for your production environment.

If you don't receive the expected response, review common Carequality errors.

Maintain or delete your organization

Whenever there are changes to your organization details (e.g., address or contact information), follow these steps to keep your organization record up-to-date:

In your development environment, using Postman or curl, send an Organization update request with the updated or new organization details. Or, to delete an organization record, change the Active field to false instead.

What “deleting” means

Marking an organization as inactive doesn’t erase all of its information. In other words, a “deleted” facility is simply inactive.

FHIR example: Update an organization record

bash

1
curl --request PUT \
2
  --url https://api.redoxengine.com/fhir/R4/ceq-orgs/Development/Organization/2.16.840.1.113883.3.6147.458.2 \
3
  --header 'Content-Type: application/json' \
4
  --data '{
5
  "resourceType": "Organization",
6
  "id": "2.16.840.1.113883.3.6147.458.2",
7
  "identifier": [
8
    {
9
      "use": "official",
10
      "system": "http://www.hl7.org/oid/",
11
      "value": "2.16.840.1.113883.3.6147.458.2"
12
    }
13
  ],
14
  "active": true,
15
  "type": [
16
    {
17
      "coding": [
18
        {
19
          "system": "http://hl7.org/fhir/organization-type",
20
          "code": "Connection"
21
        }
22
      ]
23
    }
24
  ],
25
  "name": "Redox Gateway",
26
  "alias": [
27
    ""
28
  ],
29
  "address": [
30
    {
31
      "use": "work",
32
      "type": "both",
33
      "line": [
34
        "25 West Main Street, Suite 500"
35
      ],
36
      "city": "Madison",
37
      "state": "WI",
38
      "postalCode": "53703",
39
      "country": "USA"
40
    }
41
  ],
42
  "partOf": {
43
    "identifier": {
44
      "use": "official",
45
      "system": "http://www.hl7.org/oid/",
46
      "type": {
47
        "text": "HCID"
48
      },
49
      "value": "2.16.840.1.113883.3.6147.458"
50
    }
51
  },
52
  "contact": [
53
    {
54
      "purpose": {
55
        "text": "Technical"
56
      },
57
      "name": {
58
        "use": "official",
59
        "text": "Redox, Carequality"
60
      },
61
      "telecom": [
62
        {
63
          "system": "email",
64
          "value": "carequality@redoxengine.com",
65
          "use": "work"
66
        },
67
        {
68
          "system": "phone",
69
          "value": "+16085359501",
70
          "use": "work"
71
        }
72
      ]
73
    },
74
    {
75
      "purpose": {
76
        "text": "Business"
77
      },
78
      "name": {
79
        "use": "official",
80
        "text": "Redox, Carequality"
81
      },
82
      "telecom": [
83
        {
84
          "system": "email",
85
          "value": "support@redoxengine.com",
86
          "use": "work"
87
        },
88
        {
89
          "system": "phone",
90
          "value": "+16085359501",
91
          "use": "work"
92
        }
93
      ]
94
    }
95
  ]
96
}

API reference

Review the Organization update schema for more technical details.

If the request is successful, you receive a synchronous response indicating that your organization record was updated.
FHIR example: Successful response for organization update
json
1
200 OK

Next steps

Search for patient records with FHIR®

Resources for onramp to Carequality with FHIR

Basic information

What are Network Onramps?
Carequality identity and organization structure
Carequality FAQ
Carequality test patients (contains patient data to use when testing)

How-to

Troubleshooting

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