# Create a TEFCA-CommonWell organization record

> **Who can use this how-to**
>
> - Existing customers using Network Onramps to connect to TEFCA via CommonWell

An <u>**organization record**</u> (i.e., OID in the Redox organization) is the unique identifier for your organization within the CommonWell Health Alliance. The organization OID is how you identify yourself when searching for patients—and how other TEFCA-CommonWell 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](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/tefca-identity-and-organization-structure) to understand why you may want to register more than one organization. 

## Prerequisites

- You must have qualified for TEFCA and set up your credentials and OIDs. [Learn more about setting up your onramp to TEFCA](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/set-up-your-onramp-to-tefca-commonwell).
- Be familiar with the following terms and concepts to send requests to TEFCA-CommonWell:


<details>
<summary>TEFCA-CommonWell terms to know</summary>

| **Term** | **Description** |
| --- | --- |
| Organization or object ID (OID) | Identifies a particular healthcare organization within the TEFCA-CommonWell network. When you create a new organization record within TEFCA, the returned OID becomes the sender organization ID for your later queries. |
| Patient Identity Assigning Authority (PIAA) | The entity that assigns patient identifiers in the healthcare system. This value becomes the ID type in the metadata of TEFCA-CommonWell queries for documents. |

</details>




<details>
<summary>Metadata for TEFCA-CommonWell requests</summary>

This table contains the metadata fields for Redox data models if you’re querying or sending requests to TEFCA-CommonWell via the Redox Data Model API.

| **Field** | **Description** | **Notes** |
| --- | --- | --- |
| `Meta.Destinations.ID` | A universally unique identifier (UUID) for the destination you wish to search.  This ID is different for staging and production environments. Check out the destination ID table for specifics. | For patient searches, this is a CommonWell EMPI destination.  For document searches, this is a CommonWell XCA destination.  For responding with information about your patients, this is your own document repository. |
| `Meta.FacilityCode` | Set to your organization OID or `null`. | This is required for document searches. A less common workflow might include directly querying to an external organization within the network. In that case, use their organization OID. |
| `Meta.Extensions.organization-name` | The name of the organization running the query. | Generally, this is the name of your organization or the covered entity that you’re providing services for. |
| `Meta.Extensions.sender-organization-id` | The organizational OID to identify your organization as the one sending the request. | This field is used for audit purposes and for search logic. To generate your organization OID for the `sender-organization-id` extension, [refer to TEFCA identity and organization structure](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/tefca-identity-and-organization-structure). |
| `Meta.Extensions.user-id` | Either the name of the user sending the request or the relevant provider.  This should be a human-readable identifier and is required for audit purposes. | The provider’s name should still be populated when an automated process runs the query. For example, a provider may have an automated process triggered after completing a patient visit. In that case, the query runs in the background on the provider’s behalf. |
| `Meta.Extensions.user-role` | The role of the user sending the request. | You must use a SNOMED value for this field. [See SNOMED codes](https://www.hl7.org/fhir/valueset-practitioner-role.html). |
| `Meta.Extensions.purpose-of-use` | The purpose of use for this request (e.g., Treatment). | You must qualify for a "Treatment" purpose of use when using Network Onramps. |

</details>




<details>
<summary>Destination IDs for TEFCA-CommonWell</summary>

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

| **Query purpose** | **Development ID** | **Production ID** |
| --- | --- | --- |
| Perform a patient search (`PatientSearch.LocationQuery`) | `3122bfff-f1fb-4fdf-97de-294f24338229` | `7fd005ac-d788-40c5-b4e8-b57bb8e310a9` |
| Create or update an organization (`Organization.New`, `Organization.Update`) | `3122bfff-f1fb-4fdf-97de-294f24338229` | `7fd005ac-d788-40c5-b4e8-b57bb8e310a9` |
| Search for a clinical summary/document (`ClinicalSummary.DocumentQuery`, `ClinicalSummary.DocumentGet`) | `cf1dca0e-98de-432b-8c9a-dd039816df0e` | `79981c00-b9c4-40a9-9844-01980e6e524e` |
| Save patient details to your repository (`PatientAdmin.NewPatient`, `PatientAdmin.PatientUpdate`, `PatientAdmin.PatientMerge`) | `3122bfff-f1fb-4fdf-97de-294f24338229` | `7fd005ac-d788-40c5-b4e8-b57bb8e310a9` |
| Save documents to your repository (`ClinicalSummary.VisitQuery`, `ClinicalSummary.VisitPush`) | This is specific to your organization. Redox provides the correct ID. | This is specific to your organization. Redox provides the correct ID. |

## 

</details>



> **Use curl for technical validation**
>
> You can copy our code examples and send the test requests with `curl` ([learn more about curl](https://curl.haxx.se/docs/manpage.html)) instead of Postman. If you do, remember to:
>
> - Remove any comments from the code examples (starting with `//`).
> - Replace any variables (e.g., `{{YOUR-VARIABLE}}`). 
> - 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](/basics/data-exchange-with-redox/Managing-source-details-in-outgoing-requests).
> - 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:
>
> - [Troubleshoot TEFCA-CommonWell errors](/troubleshooting/troubleshoot-tefca-commonwell-errors)
> - [Troubleshoot OAuth API key errors](/troubleshooting/troubleshoot-oauth-api-key-errors)

## Create your organization record

When testing, create an organization record in your development environment, then in your production environment once you’ve finished testing. 

1. Using Postman or `curl`, send an `Organization.New` request to create your organization record in TEFCA-CommonWell.
   - The `PIAA` ID is your patient identifier assigning authority, which has its own ID. Your IDs will be scoped under this and show up as an `IDType` in any patient or document queries.
   - For other IDs, TEFCA requires at least one of the following ID types to be assigned to each organization: `TIN`, `NPI Type 1`, `NPI Type 2`. Include all ID types that are applicable to your organization.
   - The `PartOf` identifier refers to the parent organization, which is Redox. Use the Redox ID value. 
   - For `Contacts`, replace our example data with your organization’s contact information.
 

**Example: Create a TEFCA-CommonWell organization record**

```bash
curl \
-X POST https://api.redoxengine.com/endpoint \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_TOKEN" \
-d '{
  "Meta": {
    "DataModel": "Organization",
    "EventType": "New",
    "Destinations": [
      {
        "ID": "3122bfff-f1fb-4fdf-97de-294f24338229",
        "Name": "CommonWell EMPI [Integration]"
     }
    ]
  },
  "Directory": "CommonWell",
  "Action": "Create",
  "Organizations": [
    {
      "Name": "My Company",
      "Aliases": ["My Company, LLC", "MY"],
      "Active": true,

      "Identifiers": [
        {
          "ID": "{{YOUR-ORGANIZATION-OID}}",
          "IDType": "OID"
        },
       {
          "ID": "{{YOUR-PIAA-ID}}",
          "IDType": "PIAA"
        },
        {
        "ID": "{{YOUR-NPI-TYPE-1-ID}}",
        "IDType": "NPI Type 1"
        },
        {
        "ID": "{{YOUR-NPI-TYPE-2-ID}}",
        "IDType": "NPI Type 2"
        },
        {
        "ID": "{{YOUR-TIN-ID}}",
        "IDType": "Tax Identification Number"
        },
      ],
      "PartOf": {
        "Identifier": {
          "Value": "2.16.840.1.113883.3.6147.458.2"
        }
      },
      "Contacts": [
        {
          "Purpose": "Technical",
          "Name": "Redox CommonWell Support - Test",
          "EmailAddresses": ["support@redoxengine.com"],
          "PhoneNumber": {
            "Work": "+16085359501",
            "Mobile": "+16085359501"
          }
        }
      ],
      "Address": {
        "StreetAddress": "2020 Eastwood Dr",
        "City": "Madison",
        "State": "WI",
        "ZIP": "53704",
        "County": "Dane",
        "Country": "USA"
      }
    }
  ]
}'
```




> **API reference**
>
> [Review the Organization data model](https://docs.redoxengine.com/permalink/organization-new) 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 new TEFCA-CommonWell organization record**

```json
{
  "Meta": {
    "DataModel": "Organization",
    "EventType": "New",
    "Message": {
      "ID": 4606153124
    },
    "Source": {
      "ID": "7f296bb4-83fd-498d-92f3-a76960648788",
    },
    "Destinations": [
      {
        "ID": "a07afe3b-d247-4415-827f-6837707e1b8b"
      }
    ],
    "Extensions": {
      "ResponseDetail": {
        "string": "New organization was added successfully."
      }
    }
  }
}
```




> **Redoxer must set up DNPR first**
>
> Every organization record created in CommonWell-TEFCA must have an associated Data Network Participant Repository (DNPR) set up within Redox. Only a Redoxer can manage your DNPR. If you don’t receive the expected response, [submit a Help Center request](http://redoxengine.zendesk.com) to get help. In the ticket, include your organization OID, your destination ID for document responding, and your supported purpose(s) of use. 
>
> For help with errors, [review common TEFCA-CommonWell errors](/troubleshooting/troubleshoot-tefca-commonwell-errors). 


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

## Maintain your organization record

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.


**Example: Update a TEFCA-CommonWell organization record**

```bash
curl \
-X POST https://api.redoxengine.com/endpoint \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_TOKEN" \
-d '{  
  "Meta": {
    "DataModel": "Organization",
    "EventType": "Update",
    "Destinations": [
      {
        "ID": "3122bfff-f1fb-4fdf-97de-294f24338229",
        "Name": "CommonWell EMPI [Integration]"
     }
    ]
  },
  "Directory": "CommonWell",
  "Action": "Update",
  "Organizations": [
    {
      "Name": "My Company",
      "Aliases": ["My Company, LLC", "MY"],
      "Active": true,

      "Identifiers": [
        {
          "ID": "{{YOUR-ORGANIZATION-OID}}",
          "IDType": "OID"
        },
       {
          "ID": "{{YOUR-PIAA-ID}}",
          "IDType": "PIAA"
        },
        {
        "ID": "{{YOUR-NPI-TYPE-1-ID}}",
        "IDType": "NPI Type 1"
        },
        {
        "ID": "{{YOUR-NPI-TYPE-2-ID}}",
        "IDType": "NPI Type 2"
        },
        {
        "ID": "{{YOUR-TIN-ID}}",
        "IDType": "Tax Identification Number"
        },
      ],
      "PartOf": {
        "Identifier": {
          "Value": "2.16.840.1.113883.3.6147.458.2"
        }
      },
      "Contacts": [
        {
          "Purpose": "Technical",
          "Name": "Redox CommonWell Support - Test",
          "EmailAddresses": ["support@redoxengine.com"],
          "PhoneNumber": {
            "Work": "+16085359501",
            "Mobile": "+16085359501"
          }
        }
      ],
      "Address": {
        "StreetAddress": "2020 Eastwood Dr",
        "City": "Madison",
        "State": "WI",
        "ZIP": "53704",
        "County": "Dane",
        "Country": "USA"
      }
    }
  ]
}'
```




> **API reference**
>
> [Review the Organization data model](https://docs.redoxengine.com/permalink/organization-new) schema for more technical details.


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

## Next steps

- [Populate your patient repository](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/populate-your-patient-repository-for-tefca-commonwell)

> **Onramp to TEFCA resources**
>
> **Basic information**
>
> - [Interact with clinical networks](/how-to-use-redox/interact-with-clinical-networks)
> - [TEFCA identity and organization structure](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/tefca-identity-and-organization-structure)
>
> **How-to**
>
> - [Set up your onramp to TEFCA-CommonWell](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/set-up-your-onramp-to-tefca-commonwell)
> - [Test sandbox for onramp to TEFCA-CommonWell](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/test-sandbox-for-onramp-to-tefca-commonwell)
> - [Populate your patient repository for TEFCA-CommonWell](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/populate-your-patient-repository-for-tefca-commonwell)
> - [Create a TEFCA-CommonWell organization record](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/create-a-tefca-commonwell-organization-record)
> - [Search TEFCA-CommonWell for patient records](/how-to-use-redox/interact-with-clinical-networks/onramp-to-carequality/search-for-patient-records)
> - [Request patient documents from TEFCA-CommonWell](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/request-patient-documents-from-tefca-commonwell)
> - [Maintain your Redox repository](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell/maintain-your-redox-repository-for-tefca-commonwell)
>
> **Troubleshooting**
>
> - [Common TEFCA errors](/troubleshooting/troubleshoot-tefca-commonwell-errors)