1upHealth Docs
1up HomepageSupportDevConsoleGet API Keys
Search
⌃K
Links
Comment on page

Getting Started with CMS R4 Payer Patient Access APIs

How to get access to our Demo Health Plan sandbox and begin testing your apps in advance of connecting to our network of Payer FHIR R4 endpoints

Overall Setup

These steps are intended for apps looking access member-mediated Patient Access APIs for health plan data (primarily claims data).
  1. 1.
    Create a Developer Account Using our Developer Portal following the steps here (if you haven't already done so).
  2. 2.
    Create an application with your app's redirect_uris (where the user will be sent after they authorize their health plan data be shared with your app) and securely save your client ID and secret. If you have multiple redirect_uris you can enter them in a comma separated list like in example below.
    Note - you may not use a localhost redirect with our PROD environments, but can in our sandbox while testing and developing. http://redirect1/callback,http://redirect2/callback,http://redirect3/callback
  3. 3.
    Send an email to payer-patient-access@ 1up.health with the following information:
    1. 1.
      Company Name
    2. 2.
      App Description (short sentence describing your use case)
    3. 3.
      Your App Client ID (created in step 2 above)
  4. 4.
    Once we review your information we will sync your app credentials (client ID, secret and redirects) with our Demo Health Plan environment. See information below.

Testing with Demo Health Plan Sandbox Env

After following the steps above, you can begin testing your app with our Demo Health Plan Environment.

Step 1: User Authorization to receive a OAuth 2 code

Your application will use a stand_alone launch and directly hit our authorization server https://auth.1updemohealthplan.com/oauth2/authorize/test endpoint. When you hit this endpoint, you will need to include the following query parameters.
  • client_id: This must contain the client_id of the application you previously registered in the 1upHealth developer console.
  • redirect_uri: This must contain the redirect_uri you registered with your application.
  • scope: The default scope will be user/*.read. However you will also be able to specify in the query parameter these additional scopes:patient/*.read and openid. See more information on scopes here.
  • state: If you choose to pass a state with the request, the authorization server will simply return it as a query string parameter when redirecting to your application. This parameter is not required but it is recommended that it is used to confirm the validity of a session. See more here.
Here is a sample request to our Demo Health Plan endpoint with variables that you need to fill in:
https://auth.1updemohealthplan.com/oauth2/authorize/test?client_id={your_app_client_id}&scope=user/*.read&state={state}&redirect_uri={your_app_redirect_uri}
When you arrive at the authorization page the user will need to verify their identity through their email. To test in our 1up Demo Health Plan environment, enter the following information:
1.Click "Create an account"
2. Enter the following information for one of our synthetic users loaded to our sandbox environment:
Attribute
Test Member 1
Test Member 2
Test Member 3
CARIN STU2 Test Member
First Name
Mayte822
Sherie778
Delmar187
George
Last Name
Venegas795
Fahey393
Tromp100
Bluth
Birthdate
01/04/2011
04/29/1974
05/15/1961
01/01/1943
Member ID
01-testmemid
02-testmemid
03-testmemid
04-testmemid
Postal Code
02116
01810
02109
15239
3. Enter your own email to be temporarily associated with one of the test users above. The email must be unique per test member (i.e. you can't use the same email twice across more than 1 test member).
4. At the end of the authorize process the user will will be sent back to the redirect_uri you registered with your application client ID that you included as a URL parameter above, and will include the OAuth 2.0 auth code passed back as a query parameter. This authorization code expires in 5 minutes.

Step 2: Exchange Code for Token

You will receive an authorization code in the response from above which you can exchange for an OAuth 2 access token using our https://auth.1updemohealthplan.com/oauth2/token endpoint. This authorization code expires in 5 minutes. Below is a sample request where you will need to fill in your app details.
Here is a Postman collection with the APIs to exchange the OAuth 2 code for a token, and use that token to query FHIR resources:
​​
Run in Postman
​​
curl --location --request POST 'https://auth.1updemohealthplan.com/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={your_client_id}' \
--data-urlencode 'client_secret={your_client_secret}' \
--data-urlencode 'code={code_received_above}' \
--data-urlencode 'grant_type=authorization_code'

Step 3: Query FHIR Resources Using Token

After receiving an access_token in Step 2, you can now use that Token to query FHIR resources you have the scopes and permissions to access (read-only).
curl --location --request GET 'https://api.1updemohealthplan.com/r4/Patient' \
--header 'Authorization: Bearer {access_token_from_above}'
The following resources will typically be available:
  • Patient
  • ExplanationOfBenefit
  • Coverage
  • Organization
  • Practitioner
  • A few health plans may also have a subset of Clinical Resources available (e.g. Observation, Encounter, AllergyIntolerance, etc.) for some patients
Note: The linkage between ExplanationOfBenefit and Coverage resources will not always be reliable and present.
​
Instead you need to make queries for FHIR resources using the Patient resource. You can use _include and _revinclude as well. See more information on those queries here.
Resources will adhere to the following FHIR Implementation Guides:
Previous
Digital Insurance Track
Next
CMS Production Access
Last modified 5mo ago