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 must tweak the Redox hostname slightly. All you need to do is add a ca in that 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 [access 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
   21
         # will receive inbound traffic (you can use null for testing)
   22
         "DestinationID": "5e3dc12b-3a04-438e-880d-a690639e629e",
   23
         "Aliases": ["My Company, LLC", "MY"],
   24
         "Active": true,
   25
         # OID is the only required identifier, but you can include your own identifiers as needed
   26
         "Identifiers": [
   27
           {
   28
             "ID": "[Your OID here]",
   29
             "IDType": "OID"
   30
           }
   31
         ],
   32
         # This references Redox for your top-level, and your other Organizations for levels below
   33
         "PartOf": {
   34
           "Identifier": {
   35
             # Your "PartOf" or parent should be Redox: 2.16.840.1.113883.3.6147.458.2
   36
             "Value": "[Your base OID here]"
   37
           }
   38
         },
   39
         # This section should be replaced with your contact information
   40
         "Contacts": [
   41
           {
   42
             "Purpose": "Technical",
   43
             "Name": "Redox Carequality Support - Test",
   44
             "EmailAddresses": ["support@redoxengine.com"],
   45
             "PhoneNumber": {
   46
               "Work": "+16085359501",
   47
               "Mobile": "+16085359501"
   48
             }
   49
           }
   50
         ],
   51
         # This section should be replaced with your address information
   52
         "Address": {
   53
           "StreetAddress": "2020 Eastwood Dr",
   54
           "City": "Madison",
   55
           "State": "WI",
   56
           "ZIP": "53704",
   57
           "County": "Dane",
   58
           "Country": "USA"
   59
         }
   60
       }
   61
     ]
   62
   }'

   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.

   Deleting an organization record

   Keep in mind that marking an organization as inactive doesn't fully remove all information. In other words, a "deleted" facility is merely inactive.

   Canada URL

   If you're operating in Canada, you must tweak the Redox hostname slightly. All you need to do is add a ca in that 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 [access 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 also 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 will effectively "delete" 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