Create and maintain an organization record

Last updated: Feb 18, 2025
IMPLEMENTATION

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.

Destination IDs

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

Request purposeDevelopment IDProduction ID
Perform a broad patient searchadf917b5-1496-4241-87e2-ed20434b1fdb97f2dc1d-c71b-43a7-a436-9b789d44c804
Perform a patient search within a specific organization1ca254a8-8d42-4593-abb4-b21399d9de576391b961-55ae-430b-a789-cf575f03fca0
Query for/create/update/delete an organizationa07afe3b-d247-4415-827f-6837707e1b8b5d0fd248-6c52-4ad9-b907-ae10bf2dcc39
Search for a clinical summary/documentec745338-8849-43ad-a7ce-4bc5bf1d8b89628cbf79-1156-4923-b9d0-285906160ed6
Save patient details and documents to your repositoryThis is specific to your org. Redox provides the correct ID.This is specific to your org. Redox provides the correct ID.

Create your organization record

  1. In your staging environment, using Postman or curl, send an Organization.New request to create your organization record in Carequality.
    Example: Create an organization record
    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
    "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
    }'
  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
    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.

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:

  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.
    Example: Update an organization record
    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
    "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
    }'
  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
    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
    }

Next steps