Adding Groups & Practices
How to add Groups & Practice locations, and associate them with each other and with providers
Overview
This guide walks through adding Group Profiles and Practice Locations to the Medallion Platform. We'll also demonstrate how to link them together and how to link existing Providers.
Let's get started!
Keep track of your IDs!
It's a good idea to store the IDs returned from the Medallion API whenever you create a new object (be it a Practice Location, a Group Profile, or an association between a Provider, a Practice Location, and/or a Group Profile.
However, if you ever lose track of an ID, you recover them via the
LISTendpoint for the appropriate object (e.g. GET Group Profiles or GET Practices).
Adding Group Profiles
A Group Profile can be added by sending a request to the POST a Group Profile endpoint with the Group Profile's data in the request body. Each Group Profile must have at least a name, an NPI number, a tax ID number, and an incorporation state, but see the API reference for the full list of fields supported.
import requests
api_key = "<YOUR_API_KEY>"
base_url = "https://api.medallion.co"
headers = {"x-api-key": api_key, "accept": "application/json"}
group_profiles_url = f"{base_url}/p/api/v1/group-profiles/"
group_profiles = [
{
"name": "gp 1",
"npi": 1397549548,
"tax_id_number": "12345",
"incorporation_state": "CA",
},
{
"name": "gp 2",
"npi": 1066057609,
"tax_id_number": "456",
"incorporation_state": "WV",
"incorporation_date": "2020-02-29",
},
{
"name": "gp 3",
"npi": 1409685637,
"tax_id_number": "09732",
"incorporation_state": "HI",
"mailing_city": "Honolulu",
},
]
for group_profile in group_profiles:
response = requests.post(group_profiles_url, json=group_profile, headers=headers)
response.raise_for_status()
group_profile["id"] = response.json()["id"]
Adding Documents
As an aside, Documents can be added to a Group Profile using the POST a Group Profile Document endpoint. See Importing / Adding Providers (Adding Documents) for an example of how to POST to a Documents endpoint.
Adding Practice Locations
Because Practice Locations are independent of Group Profiles, you can choose to do this before you add Group Profiles if you prefer. Either way, the process is roughly the same: you'll use the POST a Practice endpoint, sending at least a name for each Practice Location:
practices_url = f"{base_url}/api/v1/org/practices/"
practices = [
{
"name": "practice 1",
"npi": "1016070835",
"phone": "555-555-5555",
"email": "[email protected]",
},
{"name": "practice 2", "city": "Sioux Falls", "state": "SD", "status": "active"},
{"name": "practice 3"},
]
for practice in practices:
response = requests.post(practices_url, json=practice, headers=headers)
response.raise_for_status()
practice["id"] = response.json()["id"]
Managing relationships
The Medallion API supports adding relationships between:
- Providers and Practice Locations: POST a Provider Practice Association
- Groups and Practices: POST a Practice Group
- Providers, Practices, and Groups: POST a Provider Practice Group Association
In this example, we'll assume that you've already created some providers with given emails, but see Importing / Adding Providers for a refresher on how to do so.
Let's pretend that you want to establish the following relationships:
- Provider with email
[email protected]is associated with Practice 1 - Practice 2 is associated with Group Profile 2
- Provider with email
[email protected], Practice 3, and Group Profile 3 are all associated with one another.
First let's look up the IDs of those providers using their emails and the GET Providers endpoint:
providers_url = f"{base_url}/api/v1/org/providers/"
email_to_provider_id = {}
for email in ["[email protected]", "[email protected]"]:
response = requests.get(providers_url, headers=headers, params={"search": email})
response.raise_for_status()
assert response.json()["count"] == 1
email_to_provider_id[email] = response.json()["results"][0]["id"]
Now we're ready to actually create our relationships:
practice1, practice2, practice3 = practices
gp1, gp2, gp3 = group_profiles
# Provider <> Practice Association
response = requests.post(
f"{base_url}/api/v1/org/provider-practice-associations/",
json={
"provider": email_to_provider_id["[email protected]"],
"practice": practice1["id"],
"is_primary_location": True,
},
headers=headers,
)
response.raise_for_status()
print(f"Provider<>Practice Association ID = {response.json()['id']}")
# Practice <> Group Association
response = requests.post(
f"{base_url}/p/api/v1/practice-group-associations/",
json={
"practice": {"id": practice2["id"]},
"group_profile": {"id": gp2["id"]},
},
headers=headers,
)
response.raise_for_status()
print(f"Practice<>Group Association ID = {response.json()['id']}")
# Provider <> Practice <> Group Association
response = requests.post(
f"{base_url}/p/api/v1/provider-practice-group-associations/",
json={
"practice": {"id": practice3["id"]},
"provider": {"id": email_to_provider_id["[email protected]"]},
"group_profile": {"id": gp3["id"]},
},
headers=headers,
)
response.raise_for_status()
print(f"Provider<>Practice<>Group Association ID = {response.json()['id']}")
Code roundup
The following script summarizes all of the code blocks above:
import requests
api_key = "<YOUR_API_KEY>"
base_url = "https://api.medallion.co"
headers = {"x-api-key": api_key, "accept": "application/json"}
group_profiles_url = f"{base_url}/p/api/v1/group-profiles/"
group_profiles = [
{
"name": "gp 1",
"npi": 1397549548,
"tax_id_number": "12345",
"incorporation_state": "CA",
},
{
"name": "gp 2",
"npi": 1066057609,
"tax_id_number": "456",
"incorporation_state": "WV",
"incorporation_date": "2020-02-29",
},
{
"name": "gp 3",
"npi": 1409685637,
"tax_id_number": "09732",
"incorporation_state": "HI",
"mailing_city": "Honolulu",
},
]
for group_profile in group_profiles:
response = requests.post(group_profiles_url, json=group_profile, headers=headers)
response.raise_for_status()
group_profile["id"] = response.json()["id"]
practices_url = f"{base_url}/api/v1/org/practices/"
practices = [
{
"name": "practice 1",
"npi": "1016070835",
"phone": "555-555-5555",
"email": "[email protected]",
},
{"name": "practice 2", "city": "Sioux Falls", "state": "SD", "status": "active"},
{"name": "practice 3"},
]
for practice in practices:
response = requests.post(practices_url, json=practice, headers=headers)
response.raise_for_status()
practice["id"] = response.json()["id"]
providers_url = f"{base_url}/api/v1/org/providers/"
email_to_provider_id = {}
for email in ["[email protected]", "[email protected]"]:
response = requests.get(providers_url, headers=headers, params={"search": email})
response.raise_for_status()
assert response.json()["count"] == 1
email_to_provider_id[email] = response.json()["results"][0]["id"]
practice1, practice2, practice3 = practices
gp1, gp2, gp3 = group_profiles
# Provider <> Practice Association
response = requests.post(
f"{base_url}/api/v1/org/provider-practice-associations/",
json={
"provider": email_to_provider_id["[email protected]"],
"practice": practice1["id"],
"is_primary_location": True,
},
headers=headers,
)
response.raise_for_status()
print(f"Provider<>Practice Association ID = {response.json()['id']}")
# Practice <> Group Association
response = requests.post(
f"{base_url}/p/api/v1/practice-group-associations/",
json={
"practice": {"id": practice2["id"]},
"group_profile": {"id": gp2["id"]},
},
headers=headers,
)
response.raise_for_status()
print(f"Practice<>Group Association ID = {response.json()['id']}")
# Provider <> Practice <> Group Association
response = requests.post(
f"{base_url}/p/api/v1/provider-practice-group-associations/",
json={
"practice": {"id": practice3["id"]},
"provider": {"id": email_to_provider_id["[email protected]"]},
"group_profile": {"id": gp3["id"]},
},
headers=headers,
)
response.raise_for_status()
print(f"Provider<>Practice<>Group Association ID = {response.json()['id']}")
Updated 11 months ago