Here is what you need to get started developing an application with the MDsave GraphQL API. Below are some links you can find about GraphQL APIs and clients you can use to interface with it.

Introduction to GraphQL

• Apollo Client (JavaScript)

• Apollo iOS (Swift / Objective-C)

• Strawberry Shake (C# / .NET)

• GQL (Python 3+)

• genqlient (Go)

Authentication

You can authenticate with the MDsave API one of two ways: using a secret key to generate a JWT or by using a Static Token. Generating a JWT will give you access to all the Queries and Mutations. Using a static token will give you access to the searchLocations, searchOffers, and searchProcedures queries only. MDsave will generate separate secret keys and static tokens for our test (demo) and production environments.

Generate a JWT

MDsave uses JSON Web Token for authorization.

Obtain a secret key

Contacting the MDsave dev team who will register your account and generate the secret key and securely send it to you.

Create the payload

  {
    "id": "12345",
    "email": "your-email@acme.com",
    "exp": "1578596842"
  }

The exp field should be the timestamp you need the token to expire in UTC e.g. Math.round((Date.now()+250)/1000)

Encrypt the payload

Use the HS256 algorithm with the secret key to generate the JWT. MDsave accepts a standard JWT header { "alg": "HS256", "typ": "JWT" }

Using the header above and the payload from step 2, base64 encode and concatinate both and encrypt the result using the secret key from step 1.

  HMACSHA256(
    base64UrlEncode(header) + "." +
    base64UrlEncode(payload),
    your-secret
  )  

JWT.io is a useful tool to generate JWTs while developing and testing.

Use the JWT

The token generated in the steps above can be included in the header of requests to the API

  {
    "Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6IjM5ODY0IiwiZW1haWwiOiJkZW1vK2VtcGxveWVyQG1kc2F2ZS5jb20iLCJleHAiOjExODEyMzczNDJ9.45l6lG5Q48ec1beY-tNBfrt4ryyLvONCJtwxeEpXr9o"
  }

Use a Static Token

You can also use a static token to authenticate with some of our queries so that you don't have to generate a new JWT every time it expires.

1. Obtain a static token by contact the MDsave dev team. We will register an account in our demo or production environment and generate the token for you.

2. Set the Authorization and payload headers in the requests using the static token along with a payload with timestamp and email. The email address used here should be the same as the one used to generate the static token. | { "Authorization": "Bearer {Static Token}", "payload": "{"id":"243190","email":"your-email@acme.com","exp":1628009118}" }

Note that the value of the payload header needs to be JSON encoded with the quotes escaped.

Sandbox Environment

The URL of the MDsave Sandbox GraphQL API is: https://demo-api.mdsave.com. You can send queries and mutations to that URL with a valid JWT in the Authentication HTTP header. Or you can use the Apollo studio to try things out.

Data Refresh

The database for the sandbox environment will refresh every day so all test purchases made on the platform will removed overnight.

Try it out!

Use the demo playground to try out the queries and mutations from pre-built examples. You can fill in the Authentication headers and data in each tab by clicking on the Query Variables and HTTP Headers buttons at the bottom left of the window. The requests sent through the playground will be sent to our demo API environment.

---

The MDsave GraphQL API uses defined Types that correspond to how the MDsave Marketplace data is structured and are used to interact with the platform across the defined Queries and Mutations. Here are some high level descriptions of what the Types and the data they contain represent and how they map to each other and how they can be used in the API.

Procedure

A Procedure is a high level idea of a medical procedure or service that can be offered on the Marketplace. These include single services like ‘X-ray’ or ‘MRI without Contrast’, that may map to single CPT codes, as well as bundled services like ‘Knee Replacement’ that may encapsulate many CPT codes that are grouped under a single service. These are the basic components of a procedure:

• name

• description

• default included CPT codes

Offer

An Offer is a specific instance of a Procedure that is listed in the Marketplace under a single provider. This offer has a specific price for that provider at a specific location, and is the purchasable entity. An Offer is something that is put into a shopping cart and when the checkout is completed, a Voucher is created for each Offer in the cart that is purchased.

• procedure - this is linked to the Procedure Type above and is the general description of the procedure

• provider - this is the provider that will perform the procedure in this offer

  • a provider contains a reference to a “Hospital” which acts as the parent organization to the provider. Hospitals can be referenced using their unique NPI (National Provider Identifier)

• price - this is unique price for this procedure as offered by the provider. This is the up-front purchase price for this procedure at this provider

• included cpt codes - this provider may have a custom set of CPT codes that correspond to this particular offer

Shopping Cart

The ShoppingCart type functions the exact same way a shopping cart in the marketplace web experience does, with one important distinction: the API currently only supports a createShoppingCart mutation currently, so you will need to send all the selected Offers along with a patient object when creating the cart. However, also like the web experience, you can only add offers from the same Provider to a shopping cart.

Voucher

A Voucher represents a purchase of ShoppingCart for a specific Patient and functions as a proof of purchase for the patient to receive services. Each Offer in a ShoppingCart that is purchased will generate a Voucher that all have the same order number and will have a unique voucher number. For example, purchasing a ShoppingCart with 3 Offers in it will produce 3 Vouchers with the order number 1234567 and the voucher numbers will be:

• 1234567-01

• 1234567-02

• 1234567-03

Each of which will also have a link to a PDF version of the voucher with all of the information needed to schedule and verify the services.

Vouchers have one of three different statuses:

• Available

  • The voucher is purchased but is not yet redeemed. The voucher is still good for the patient to redeem the services.

• Used

  • Once the patient receives services, the voucher is redeemed and the payment is sent to the provider.

• Cancelled

  • The voucher was purchased but has been cancelled and refunded.

---

In this example, we are going to step through a commonly used workflow and provide code samples for each step.

1. Search for Procedures

You can use the searchProcedures query to search for medical procedures that are available on the MDsave Marketplace. This query can be used to power your own search functionality in your application and can be used to surface the many procedures that are bundled in different ways. The results will generally include a bundle of CPT codes that are valid for those services at that provider. You can also search for procedures by CPT code.

By Procedure Name with Autocomplete

You can use the MDsave API to power autocomplete search functionality on your own platform to surface MDsave procedures by name. To demonstrate how this can be done, we will simulate a user typing a procedure name into a search box while we are actively sending the requests as they type. To do this, we will use the searchProcedures query to send these snippets of text, which will return a list of potential matches.

Let’s simulate a user typing “ct scan with contrast” into a search box. You application can start querying the API as they start typing a few letters.

We’ll start by sending “ct s” as the procedure name in the query as if the user was beginning to type their search.

query searchProcedures(
  $query: SearchProceduresInput!,
  $pagination: Pagination
) {
  searchProcedures(
    query: $query,
    pagination: $pagination
  ) {
    procedures {
      id
      name
      url
    }
  }
}  

---

{
  "query": {
    "name": "ct s"
  },
  "pagination": {"offset": 0, "limit": 10}
}  

The API will return this list of procedures. Since there were only a few letters sent, the results will be broad but will narrow as the user types more of their search.

{
    "data": {
        "searchProcedures": {
            "procedures": [
                {
                    "id": 1792,
                    "name": "Low Dose CT Lung Screening",
                    "url": "https://demo.mdsave.com/procedures/low-dose-ct-lung-screening/d785f5cf?utm_medium=affiliate&utm_source=Example+API+Employer"
                },
                {
                    "id": 1435,
                    "name": "Cardiac CT Coronary Angiography",
                    "url": "https://demo.mdsave.com/procedures/cardiac-ct-coronary-angiography/d786ffc8?utm_medium=affiliate&utm_source=Example+API+Employer"
                },
                {
                    "id": 1425,
                    "name": "CT Scan Limited/Follow-up Study",
                    "url": "https://demo.mdsave.com/procedures/ct-scan-limited-follow-up-study/d786fec8?utm_medium=affiliate&utm_source=Example+API+Employer"
                },
                {
                    "id": 1391,
                    "name": "CT Scan with Contrast",
                    "url": "https://demo.mdsave.com/procedures/ct-scan-with-contrast/d781f5cc?utm_medium=affiliate&utm_source=Example+API+Employer"
                },
                {
                    "id": 1399,
                    "name": "CT Scan of Abdomen and Pelvis with Contrast",
                    "url": "https://demo.mdsave.com/procedures/ct-scan-of-abdomen-and-pelvis-with-contrast/d781f5c4?utm_medium=affiliate&utm_source=Example+API+Employer"
                },
                {
                    "id": 1061,
                    "name": "PET Scan",
                    "url": "https://demo.mdsave.com/procedures/pet-scan/d782facc?utm_medium=affiliate&utm_source=Example+API+Employer"
                }
            ]
        }
    }
}  

Now let’s send another query with more text “ct scan with” to continue narrowing the results.

query searchProcedures(
  $query: SearchProceduresInput!,
  $pagination: Pagination
) {
  searchProcedures(
    query: $query,
    pagination: $pagination
  ) {
    procedures {
      id
      name
      url
    }
  }
}  

---

{
  "query": {
    "name": "ct scan with"
  },
  "pagination": {"offset": 0, "limit": 10}
}  

The API returns these procedures:

{
    "data": {
        "searchProcedures": {
            "procedures": [
                {
                    "id": 1391,
                    "name": "CT Scan with Contrast",
                    "url": "https://demo.mdsave.com/procedures/ct-scan-with-contrast/d781f5cc?utm_medium=affiliate&utm_source=Example+API+Employer"
                },
                {
                    "id": 1399,
                    "name": "CT Scan of Abdomen and Pelvis with Contrast",
                    "url": "https://demo.mdsave.com/procedures/ct-scan-of-abdomen-and-pelvis-with-contrast/d781f5c4?utm_medium=affiliate&utm_source=Example+API+Employer"
                }
            ]
        }
    }
}

The url field is the landing page for this procedure on MDsave (they will be mdsave.com urls in production). You can send a user to this page where they can use the MDsave marketplace to continue searching and purchase on the marketplace web site.

The id field returned for each procedure will be the value you will use to reference any of these procedures in future queries. For example, in the next step, we will use the procedure id to search for offers of that procedure.

{
    "id": 1391,
    "name": "CT Scan with Contrast",
    "url": "https://demo.mdsave.com/procedures/ct-scan-with-contrast/d781f5cc?utm_medium=affiliate&utm_source=Example+API+Employer"
}  

By CPT Code

You can also use the searchProcedures query to find procedures by searching their bundled CPT codes. Generally any query will return _any _procedure that contains any of the CPT codes and some common codes are used in many related bundles on MDsave.

Use the searchProcedures query to send a list of CPT codes to find any procedures that contain those codes. In this example, we will use the CPT code 71260 , which is included in some kinds of CT Scan with Contrast.

query searchProcedures(
  $query: SearchProceduresInput!,
  $pagination: Pagination
) {
  searchProcedures(
    query: $query,
    pagination: $pagination
  ) {
    procedures {
      id
      name
      url
    }
  }
}  

---

{
  "query": {
    "procedureCodes": {
        "cptCodes": ["71260"]
    }
  },
  "pagination": {"offset": 0, "limit": 10}
}  

---

{
    "data": {
        "searchProcedures": {
            "procedures": [
                {
                    "id": 1399,
                    "name": "CT Scan of Abdomen and Pelvis with Contrast",
                    "url": "https://demo.mdsave.com/procedures/ct-scan-of-abdomen-and-pelvis-with-contrast/d781f5c4?utm_medium=affiliate&utm_source=Example+API+Employer"
                }
            ]
        }
    }
}  

2. Search for Offers by Location

Now let’s say the user has selected the “CT Scan with Contrast” procedure from the results in step 1 (id: 1391) and we now want to search for offers for that procedure within 50 miles of a certain zip code: 75001 (Dallas, TX).

Use the searchOffers query to look for offers at a location for this procedure:

• In the query data, we will provider a location with zip code 75001 and radius 50, as well as a procedureId in procedureCodes that corresponds to the procedure we searched for (id 1391). This will return all offers for a ‘CT Scan with Contrast’ procedure within 50 miles of that zip code.
• We can order these results as well, we will send total_price in orderBy.field value. This will return the lowest prices at the top.
• You can also order by distance as well that will return the offers closes to the zip code first.

query searchOffers(
    $query: SearchOffersInput!,
    $pagination: Pagination,
    $orderBy: [OrderBy]
) {
    searchOffers(
    query: $query,
    pagination: $pagination,
    orderBy: $orderBy
    ) {
    items {
        offer {
        id
        description
        price
        schedulePhone
        procedure {
            id
            name
        }
        provider {
            id
            fullName
            providerName
            hospital {
                id
                name
                npi
            }
        }
        }
    }
    messages {
        type
        message
    }
    requestId
    }
}  

---

{
  "query": {
    "location": {
        "zipCode": "75001",
        "radius": 50
    },
    "procedureCodes": {
        "procedureIds": [
            1391
        ]
    }
  },
  "pagination": {"offset": 0, "limit": 15},
  "orderBy": {
    "field": "total_price",
    "direction": "ASC"
  }
}  

This returns the results below. Each offer has a unique description that is customized by the provider that is offering it which may show different included services. There is also a schedulePhone value that is the office number that can be called to schedule the patient.

{
"data": {
    "searchOffers": {
        "items": [
            {
                "offer": {
                    "id": 335067,
                    "description": "Procedure Details: This is a CT scan with dye of ANY ONE body part: Spine, Lumbar, Chest, Orbit, Face, Neck, Sinus, Abdomen, Pelvis, Brain or Lower/Upper Extremity. If the patient needs more than one body part scanned, the appropriate number of scans must be purchased.<br/><br/>Price Details: Your purchase includes the following services:<br/>Facility fee - technical (equipment) fee for the imaging<br/>Physician fee - physician interpretation fee",
                    "url": "https://demo.mdsave.com/p/medical-city-dallas-imaging-center-imaging-and-radiology/ct-scan-with-contrast/d581f9cd64da?utm_medium=affiliate&utm_source=Example+API+Employer",
                    "price": 278,
                    "schedulePhone": "(972) 566-2900",
                    "procedure": {
                        "id": 1391,
                        "name": "CT Scan with Contrast"
                    },
                    "provider": {
                        "id": 13030,
                        "fullName": "Medical City Dallas Imaging Center",
                        "providerName": "Medical City Dallas Imaging Center",
                        "hospital": {
                            "id": 2665,
                            "name": "Medical City Dallas Imaging Center",
                            "npi": "1235199829"
                        }
                    }
                }
            },
            {
                "offer": {
                    "id": 335684,
                    "description": "Procedure Details: This is a CT scan with dye of ANY ONE body part: Spine, Lumbar, Chest, Orbit, Face, Neck, Sinus, Abdomen, Pelvis, Brain or Lower/Upper Extremity. If the patient needs more than one body part scanned, the appropriate number of scans must be purchased.<br/><br/>Price Details: Your purchase includes the following services:<br/>Facility fee - technical (equipment) fee for the imaging<br/>Physician fee - physician interpretation fee",
                    "url": "https://demo.mdsave.com/p/preferred-imaging-of-plano-lp-imaging-and-radiology/ct-scan-with-contrast/d581f9cb6ad9?utm_medium=affiliate&utm_source=Example+API+Employer",
                    "price": 304,
                    "schedulePhone": "(972) 312-0799",
                    "procedure": {
                        "id": 1391,
                        "name": "CT Scan with Contrast"
                    },
                    "provider": {
                        "id": 13070,
                        "fullName": "Preferred Imaging Of Plano Lp",
                        "providerName": "Preferred Imaging Of Plano Lp",
                        "hospital": {
                            "id": 2705,
                            "name": "Preferred Imaging Of Plano Lp",
                            "npi": "1861575615"
                        }
                    }
                }
            },
            {
                "offer": {
                    "id": 335594,
                    "description": "Procedure Details: This is a CT scan with dye of ANY ONE body part: Spine, Lumbar, Chest, Orbit, Face, Neck, Sinus, Abdomen, Pelvis, Brain or Lower/Upper Extremity. If the patient needs more than one body part scanned, the appropriate number of scans must be purchased.<br/><br/>Price Details: Your purchase includes the following services:<br/>Facility fee - technical (equipment) fee for the imaging<br/>Physician fee - physician interpretation fee",
                    "url": "https://demo.mdsave.com/p/preferred-imaging-of-frisco-imaging-and-radiology/ct-scan-with-contrast/d581f9c86bd9?utm_medium=affiliate&utm_source=Example+API+Employer",
                    "price": 304,
                    "schedulePhone": "(469) 300-2025",
                    "procedure": {
                        "id": 1391,
                        "name": "CT Scan with Contrast"
                    },
                    "provider": {
                        "id": 13065,
                        "fullName": "Preferred Imaging Of Frisco",
                        "providerName": "Preferred Imaging Of Frisco",
                        "hospital": {
                            "id": 2700,
                            "name": "Preferred Imaging Of Frisco",
                            "npi": "1881028397"
                        }
                    }
                }
            }
        ],
        "messages": [
            {
                "type": "Success",
                "message": ""
            }
        ],
        "requestId": "1e4f4b04-3cb3-40c8-9746-ffeebbf678e0"
    }
}
}

We will capture the offer id and the hospital npi values for one of these offers for the next steps.

3. Create a Shopping Cart

Next, let’s say the user has selected one of these offers. The $155 CT Scan with Contrast at Medical City – Offer id 335067 with hospital NPI 1235199829.

{
    "offer": {
        "id": 335067,
        "description": "Procedure Details: This is a CT scan with dye of ANY ONE body part: Spine, Lumbar, Chest, Orbit, Face, Neck, Sinus, Abdomen, Pelvis, Brain or Lower/Upper Extremity. If the patient needs more than one body part scanned, the appropriate number of scans must be purchased.<br/><br/>Price Details: Your purchase includes the following services:<br/>Facility fee - technical (equipment) fee for the imaging<br/>Physician fee - physician interpretation fee",
        "url": "https://demo.mdsave.com/p/medical-city-dallas-imaging-center-imaging-and-radiology/ct-scan-with-contrast/d581f9cd64da?utm_medium=affiliate&utm_source=Example+API+Employer",
        "price": 278,
        "schedulePhone": "(972) 566-2900",
        "procedure": {
            "id": 1391,
            "name": "CT Scan with Contrast"
        },
        "provider": {
            "id": 13030,
            "fullName": "Medical City Dallas Imaging Center",
            "providerName": "Medical City Dallas Imaging Center",
            "hospital": {
                "id": 2665,
                "name": "Medical City Dallas Imaging Center",
                "npi": "1235199829"
            }
        }
    }
}  

Now we will building a shopping cart with that Offer in it. We will need to provide patient demographic information as well that will be used when checking out the ShoppingCart. It will be up to you to fill in the patient information, but it could come from a user typing in their information in the context of a web application or filled in from some another data source.

To do this, we will use the createShoppingCart mutation, which takes these objects in the query:

• patient (PatientInput)

  • email, firstName, lastName, dateOfBirth, phoneNumber

• hospital (HospitalInput)

  • use the npi value from the Offer: "1235199829"

• procedureCodes (ProcedureCodesInput)

  • in offerIds add the Offer id : 335067

mutation createShoppingCart(
    $patient: PatientInput,
    $hospital: HospitalInput,
    $procedureCodes: ProcedureCodesInput
) {
    createShoppingCart(
    patient: $patient,
    hospital: $hospital,
    procedureCodes: $procedureCodes
    ) {
    shoppingCart {
        id
        url
        patient {
        email
        firstName
        lastName
        dateOfBirth
        phoneNumber
        }
        items {
        offer {
            id
        }
        quantity
        price
        }
        totalPrice
        status
    }
    messages {
        type
        message
    }
    requestId
    }
}

---

{
  "patient": {
    "email": "testpatient@mdsave.com",
    "firstName": "abc123",
    "lastName": "xyz789",
    "dateOfBirth": "2000-01-01",
    "phoneNumber": "5555555555"
  },
  "hospital": {
    "npi": "1235199829"
  },
  "procedureCodes": {
    "offerIds": [335067]
  }
}  

The Shopping Cart URLs can be sent to the patient or to someone who has authorization to transact for the patient to checkout directly on the MDsave website. Since these carts can be created programmatically, the URLs to the pre-built shopping cart could be emailed out or surfaced in another system to reference and complete the checkout.

The API returned a “Success” message with the shoppingCart id and url. The id is the value that we will use to checkout this cart in the next step.

{
    "data": {
        "createShoppingCart": {
            "shoppingCart": {
                "id": "66ccf071b929e1.92169779",
                "url": "https://demo.mdsave.com/carepackage/66ccf071b929e1.92169779?utm_medium=affiliate&utm_source=Example+API+Employer",
                "patient": {
                    "email": "testpatient@mdsave.com",
                    "firstName": "Abc123",
                    "lastName": "Xyz789",
                    "dateOfBirth": "2000-01-01",
                    "phoneNumber": "5555555555"
                },
                "items": [
                    {
                        "offer": {
                            "id": 335067
                        },
                        "quantity": 1,
                        "price": 278
                    }
                ],
                "totalPrice": 278,
                "status": "Active"
            },
            "messages": [
                {
                    "type": "Success",
                    "message": ""
                }
            ],
            "requestId": "1e4f4b04-3cb3-40c8-9746-ffeebbf678e0"
        }
    }
}  

4. Checkout a Shopping Cart

Now we can checkout that shopping cart to purchase Vouchers for the patient for all the Offers that were in the shopping cart. In this example, we will use the shopping cart that we built in the previous step:

"shoppingCart": {
  "id": "66ccf071b929e1.92169779",
  "url": "https://demo.mdsave.com/carepackage/66ccf071b929e1.92169779?utm_medium=affiliate&utm_source=Example+API+Employer",
}  

Build the checkout mutation and send it to complete the transaction. Note that invoice purchases are the only type of transaction that can be completed through the API right now.

• shoppingCartId - returned from the createShoppingCart query in step 3

• paymentMethods - in production this will always need to be {"invoicing": true}

• isScheduled - in a normal workflow when checking out, the patient is asked if they need to be scheduled. If this value is set to true, the provider is notified by MDsave that the patient needs scheduling, and they will reach out.

• sendEmail - If this is checked, then the patient’s email in the shopping cart will receive an email from MDsave with the voucher and any instructions from the provider. The sandbox will not send emails out.

mutation checkout($data: CheckoutInput!) {
    checkout(data: $data) {
    voucherNumbers
    voucherPDFUrl
    messages {
        type
        message
    }
    isSuccess
    requestId
    }
}

---

{
    "data": {
        "shoppingCartId": "66ccf071b929e1.92169779",
        "paymentMethods": {"invoicing": true},
        "address": {
            "street": "123 Main St",
            "city": "Dallas",
            "state": "TX",
            "zipCode": "75001"
        },
        "isScheduled": false,
        "sendEmail": true
    }
}  

An isSuccess:true in the response means the transaction went through. There will be a voucherPDFUrl link also in the response that will be active for 24 hours that can be used to download a copy of the Voucher as a PDF.

{
    "data": {
        "checkout": {
            "voucherNumbers": [
                "8614600-01"
            ],
            "voucherPDFUrl": "https://demo.mdsave.com/ExportPdf/8614600/de84fdc964dd1331aff40459c73bc463913b634b88f0cc1a212e66f5a958a6141327fdeb106e/print",
            "messages": [
                {
                    "type": "Success",
                    "message": "Thank you! Your purchase has been successfully submitted"
                }
            ],
            "isSuccess": true,
            "requestId": "1e4f4b04-3cb3-40c8-9746-ffeebbf678e0"
        }
    }
}  

5. Retrieve Previous Voucher Purchases

Now that we’ve made a purchase, we can use the searchVouchers query to return the previously purchased voucher data. Note that the URLs to the Voucher PDFs will only work for 24 hours after the voucher is purchased.

You can query within a purchasedDate time period as well as by status.

query searchVouchers(
  $query: SearchVouchersInput!,
  $pagination: Pagination
) {
  searchVouchers(
    query: $query,
    pagination: $pagination
  ) {
    items {
      id
      voucherNumber
      status
      price
      purchasedDate
      patient {
        firstName
        lastName
        email
      }
      offer {
        id
        provider {
            hospital {
                id
                npi
            }
        }
        procedure {
            id
        }
      }
    }
    messages {
      type
      message
    }
    requestId
  }
}  

---

{
  "query": {
    "status": "Available",
    "purchasedDate": {
      "start": "2024-08-01",
      "end": "2024-08-31"
    }
  },
  "pagination": { "offset": 0, "limit": 100}
}  

The results will return the voucher that was just purchased through the checkout mutation showing a status of Available.

{
    "data": {
        "searchVouchers": {
            "items": [
                {
                    "id": 861940,
                    "voucherNumber": "8619401-01",
                    "status": "Available",
                    "price": 278,
                    "purchasedDate": "2024-08-27",
                    "patient": {
                        "firstName": "Abc123",
                        "lastName": "Xyz789",
                        "email": "testpatient@mdsave.com"
                    },
                    "offer": {
                        "id": 335067,
                        "provider": {
                            "hospital": {
                                "id": 2665,
                                "npi": "1235199829"
                            }
                        },
                        "procedure": {
                            "id": 1399
                        }
                    }
                }
            ],
            "messages": [
                {
                    "type": "Success",
                    "message": ""
                }
            ],
            "requestId": "1e4f4b04-3cb3-40c8-9746-ffeebbf678e0"
        }
    }
}  

Once the patient receives care and MDsave receives payment from your organization, in the Voucher will go into a Used status, and will be available to query in that status in perpetuity.

How to Get help

If you or your team have additional questions about the GraphQL API or issues getting started with the Sandbox Environment, you can reach out to our API support email mdsaveapi@tendo.com and our Engineering team can assist you.

Current API Limitations

The following outlines current limitations of the MDsave API. These constraints reflect features that are planned or under consideration, but not yet supported. We encourage you to review this list when designing your integration workflows

Platform Scope

• Care Navigation Only: The API is intended for use by care navigation organizations (purchasers on MDsave), not providers (sellers on MDsave).

Voucher Management

• Voucher Redemption Not Supported: The API cannot be used to process or cancel vouchers, only to purchase them.
• Voucher Visibility: Only vouchers purchased by the partner organization are accessible.
• No Voucher Change Notifications: There is no webhook or subscription support for voucher updates.

Cart Management

• Quantity Edits Require Multiple Calls: To adjust quantities in the cart, you must issue multiple addShoppingCartItems calls (e.g., to add a quantity of 2, call the method twice).
• Cart Sharing: The API supports cart sharing via a generated URL, but sharing must be handled by the partner. Split payment for shared carts is not supported.

Pricing and Payment

• No Price Context: Estimated commercial rates and Medicare benchmark percentages are not currently returned.

• Pricing Groups:

  • Group names (e.g., Consumer or Employer-Only) are not displayed in search results.
  • You cannot specify a pricing group when searching; results are limited to the partner's default and public access.

• Payment Options: Supported methods include credit card and employer invoicing.

  • Split payments, PayPal, multiple card support, and Care Credit are not available.
  • Invoice download is not supported.

User and Employer Features

• No User Management: Partners cannot create care navigator users or manage organizational settings via the API.
• No Deductible Check: Real-time deductible or benefits checks are not supported.
• Insurance & Plan of Care Fields: The following fields are not available. Employers requiring any of the above for claims submission or tracking will not be able to complete checkouts or share carts via the API.
  • Insurance Plan
  • Member ID
  • Group ID
  • Plan of Care Identifier

Clinical Data

• Quality Ratings: Provider quality ratings are not included in search or offer data.

We are continuously working to enhance the MDsave API and welcome your feedback on what features would be most useful in future releases. For questions or suggestions, please contact mdsaveapi@tendo.com.