Create and maintain an organization record

An organization record (i.e., OID in the Redox organization) 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 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.

You must populate any test requests with the appropriate destination ID in the Meta.Destinations array based on the environment and type of requests:

1. In your staging environment, using Postman or curl, send an Organization.New request to create your organization record in Carequality.

   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.

   Example: Create an organization record

   bash

   Copy

   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
       "DataModel": "Organization",
   8
       "EventType": "New",
   9
       "Destinations": [
   10
         {
   11
           "ID": "a07afe3b-d247-4415-827f-6837707e1b8b"
   12
         }
   13
       ]
   14
     },
   15
     "Directory": "Carequality", # Currently, only Carequality is supported
   16
     "Action": "Create",
   17
     "Organizations": [
   18
       {
   19
         "Name": "My Company",
   20
         // The destination ID should be your Redox destination UUID where you receive inbound traffic (you can use null for testing). 
   21
         "DestinationID": "5e3dc12b-3a04-438e-880d-a690639e629e",
   22
         "Aliases": ["My Company, LLC", "MY"],
   23
         "Active": true,
   24
         // OID is the only required identifier, but you can include your own identifiers as needed.
   25
         "Identifiers": [
   26
           {
   27
             "ID": "{{your-OID}}",
   28
             "IDType": "OID"
   29
           }
   30
         ],
   31
         // This references Redox as your top-level, and your other organizations for levels below.
   32
         "PartOf": {
   33
           "Identifier": {
   34
             // Your "PartOf" or parent should be Redox: 2.16.840.1.113883.3.6147.458.2
   35
             "Value": "{{your-base-OID}}"
   36
           }
   37
         },
   38
         // Replace this information with your contact information.
   39
         "Contacts": [
   40
           {
   41
             "Purpose": "Technical",
   42
             "Name": "Redox Carequality Support - Test",
   43
             "EmailAddresses": ["support@redoxengine.com"],
   44
             "PhoneNumber": {
   45
               "Work": "+16085359501",
   46
               "Mobile": "+16085359501"
   47
             }
   48
           }
   49
         ],
   50
         // Replace this information with your address information.
   51
         "Address": {
   52
           "StreetAddress": "2020 Eastwood Dr",
   53
           "City": "Madison",
   54
           "State": "WI",
   55
           "ZIP": "53704",
   56
           "County": "Dane",
   57
           "Country": "USA"
   58
         }
   59
       }
   60
     ]
   61
   }'

   API reference

   Review the Organization data model schema for more technical details.

2. If the request is successful, you receive a synchronous response indicating that your organization record was created.

   Example: Successful response for creating an organization record

   json

   Copy

   1
   {
   2
     "Meta": {
   3
       "DataModel": "Organization",
   4
       "EventType": "New",
   5
       "Message": {
   6
         "ID": 4606153124
   7
       },
   8
       "Source": {
   9
         "ID": "7f296bb4-83fd-498d-92f3-a76960648788",
   10
       },
   11
       "Destinations": [
   12
         {
   13
           "ID": "a07afe3b-d247-4415-827f-6837707e1b8b"
   14
         }
   15
       ],
   16
       "Extensions": {
   17
         "ResponseDetail": {
   18
           "string": "New organization was added successfully."
   19
         }
   20
       }
   21
     }
   22
   }

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

Once you complete all of your testing, you need to repeat these steps to create your organization record in production, too.

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:

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

   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.

   Example: Update an organization record

   bash

   Copy

   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
       "DataModel": "Organization",
   8
       // Everything can stay the same as New except here and the "Action" field below.
   9
       "EventType": "Update",
   10
       "Destinations": [
   11
         {
   12
           "ID": "a07afe3b-d247-4415-827f-6837707e1b8b"
   13
         }
   14
       ]
   15
     },
   16
     "Directory": "Carequality",
   17
     // This must change to "Update".
   18
     "Action": "Update",
   19
     "Organizations": [
   20
       {
   21
         "Name": "My Company Facility 1 Update",
   22
         "DestinationID": "5e3dc12b-3a04-438e-880d-a690639e629e",
   23
         // This effectively "deletes" the organization.
   24
         "Active": false,
   25
         "Identifiers": [
   26
           {
   27
             "ID": "[Your OID here].1",
   28
             "IDType": "OID"
   29
           }
   30
         ],
   31
         // This references the top-level Redox organization.
   32
         "PartOf": {
   33
           "Identifier": {
   34
             "Value": "[Your base OID here]"
   35
           }
   36
         },
   37
         "Contacts": [
   38
           {
   39
             "Purpose": "Technical",
   40
             "Name": "Redox Carequality Support - Test",
   41
             "EmailAddresses": ["support@redoxengine.com"],
   42
             "PhoneNumber": {
   43
               "Work": "+16085359501",
   44
               "Mobile": "+16085359501"
   45
             }
   46
           }
   47
         ],
   48
         "Address": {
   49
           "StreetAddress": "2020 Eastwood Dr",
   50
           "City": "Madison",
   51
           "State": "WI",
   52
           "ZIP": "53704",
   53
           "County": "Dane",
   54
           "Country": "USA"
   55
         }
   56
       }
   57
     ]
   58
   }'

   API reference

   Review the Organization data model schema for more technical details.

2. If the request is successful, you receive a synchronous response indicating that your organization record was updated.

   Example: Successful response for organization update

   json

   Copy

   1
   {
   2
     "Meta": {
   3
       "DataModel": "Organization",
   4
       "EventType": "Update",
   5
       "Message": {
   6
         "ID": 4606153124
   7
       },
   8
       "Source": {
   9
         "ID": "7f296bb4-83fd-498d-92f3-a76960648788"
   10
       },
   11
       "Destinations": [
   12
         {
   13
           "ID": "a07afe3b-d247-4415-827f-6837707e1b8b"
   14
         }
   15
       ],
   16
       "Extensions": {
   17
         "ResponseDetail": {
   18
           "string": "Organization with id:2.16.840.1.113883.3.6147.5 has been updated successfully."
   19
         }
   20
       }
   21
     }
   22
   }

• Search for patient records