Guidelines for Providers

As a provider, you can make requests to 1up's Provider Access API and export payer data for members you have an upcoming or active treatment relationship with. To do so, you’ll first need to sign up for production access via the 1up Dev Portal. Once your organization has been verified, you will be able to generate client credentials that allow you to retrieve an authorization token.

This token can then be used to make requests to the Provider Access API and export data for your patients. While you wait for production access, you’ll be able to create sandbox clients if you would like to test out our API and export some mocked FHIR patient data.

1up’s Provider Access Architecture

The 1up Provider Access API is a bulk FHIR data API that meets the HL7 FHIR Bulk Data API specification. In order to make a request to the Provider Access API, an access token must be supplied that identifies the provider organization. This token is obtained through an OAuth 2.0 client credentials flow, enabled by 1up's Dev Portal.

After making a valid FHIR bulk export request, you will receive a URL to track the asynchronous job exporting your patients’ data. Once complete, you will be given additional URL(s) to download your exported patient data as .ndjson files. All of these requests will be made with the same authorization token retrieved on behalf of your client.

Using the 1up Provider Access API

The following procedure provides step-by-step instructions on how to access the 1up Provider Access API and make requests for patient data.

Step 1 - Logging in/Registering for the 1up Dev Portal

  1. Click the following link to access the 1up Dev Portal login page.

  1. Enter your Email and Password.

  2. Click Register for the 1up Dev Portal which brings you to the 1up sandbox registration page.

  3. Fill out the required fields, and select Register. You will receive a link to the email address provided.

  4. Verify your email address by clicking the link you received.

  5. Once your email is verified, refresh the page you used to sign up. You are now logged into the Dev Portal and have access to the sandbox clients tab.

  6. Click Sign In. You will then be taken to the Sandbox Clients page.

  7. To create a Sandbox Client, click Create a Client. Go to Creating a Sandbox Client for more information.

Step 2 - Requesting Production Access

  1. From the Dev Portal home page, in the left hand sidebar, click Production Clients.

  2. On the Production Clients screen, click Request Access. To gain production access, you must submit a multi-stage production access form so 1up can properly validate your Provider Organization.

  3. The Requesting Production Access form opens. Under Organizational Information:

    1. Enter the Organization Type. This defines which client access types you can create. Client access types represent different rule cases (Patient Access, Provider Access, etc).

      The table below shows which client access types a user within each organization can create. You should select either the Provider/Health Systems or the Accountable Care Organization (ACO) type.

    user.attributes.organizationType

    client.attributes.accessType

    Provider/Health Systems

    Attributed members claims data (CMS Provider Access)

    Accountable Care Organization (ACO)

    Attributed members claims data (CMS Provider Access)

    Consumer Application/Digital Health Application

    Member authenticated claims data (CMS Patient Access)

    Payer

    None - Payer to Payer coming soon

    Service Provider/Other

    None - coming soon

    EHR Software

    None - Prior Auth coming soon

    1. Enter the National Provider Identification (NPI) number. You should use the NPI that represents your entire organization or system, rather than the NPI of any individual provider within it.

    2. Enter the Taxpayer Identifier Number (TIN).

  4. Click Next and fill out the remaining information on the form which provides details for the vetting process used by 1up, then click Submit.

  5. Once you submit this form, 1up will review the information provided. While your production access is pending, you can access the 1up sandbox and create clients to pull some synthetic data. Go to Creating a Sandbox Client for more information.

  6. Once your requested production access has been granted, you will have access to the production clients tab in the Dev Portal allowing you to create and manage production clients. Go to Creating Production Clients for more information.

Step 3 - Creating Clients

Creating a Sandbox Client

  1. Log into the 1up Dev Portal.

  2. On the left hand sidebar, click Sandbox Clients.

  3. From the Sandbox Clients page, select Create a client.

  4. Select Provider Access as your Organization Type: “Attributed members claims data (CMS Provider Access)”. The 1up Dev Portal is where users can create clients to make requests to various protected 1up APIs.

  5. Enter a name for your client. This will likely be the name of the application that you have built or plan to build. This should take you back to the Sandbox Clients page, where you can see your first Provider Access client. You will see a client ID next to your clients name, as well as an option to copy the client secret.

Creating Production Clients

  1. Log into the Dev Portal.

  2. From the Dev Portal home page, on the left hand sidebar, click Production Clients, then click Create a client.

  1. On the Client Creation page, under Access Type, from the drop down menu, select "Attributed members claims data (CMS Provider Access)".

  2. Enter a Client Name and Description for your client. For testing purposes, you can enter any information here. In production, this client may represent an application (like an EHR System) that makes Provider Access API requests. To learn more about the OAuth 2.0 Client Credentials Flow, click here.

  3. Click Create. You now have a client!

Step 4 - Exporting Bulk Data

In order for you or your application to make a request to the Provider Access API, a bearer token must first be requested on behalf of your new client. With that token, you will then be able to make your Provider Access API request to export FHIR data. The following instructions demonstrate these requests using basic cURL commands, which can be made from your terminal; however, you can use any tool you'd like to make these HTTP requests.

FHIR data

While the sandbox FHIR data you’ve received is mocked, the system delivering the proper data for your sandbox client is exactly what’s handling production requests. The provider access sandbox client you created, was mapped to a mocked NPI. Once you gain production access as a provider organization, the production clients you create will be attributed to your actual organization’s NPI.

The access token you retrieved contains that NPI. You can paste that token into jwt.io and verify everything within the token. While the NPI we used is not associated with a real provider organization we have seeded our policy information data store with real attribution data as if a payer had members that were treated by this provider. Those members, or patients, then have data stored on the 1up FHIR server associated with them.

The request you made grabbed required data that the payer had stored for any patients they have attributed to your organization.

Example procedure using cURL

  1. Copy your newly created client’s ID and secret from the clients table.

  2. Make a request to retrieve a token, by requesting the proper scope needed to make a bulk FHIR data export request. Substituting your client id and secret.

curl --location 'https://gateway.1up.health/auth/realms/dev-portal/protocol/openid-connect/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=<add-your-client-id-here>' \
  --data-urlencode 'client_secret=<add-your-client-secret-here>' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=bulk-data|user/*.rs'

  1. Copy the access_token. You will use this token for subsequent requests.

  1. Make your FHIR bulk export request by substituting xxx for your copied access token.

curl \
    -H 'Authorization: Bearer xxx' \
    'https://gateway.1up.health/<tenant>/bulk-data/r4/$export'

  1. The last step should have returned a payload that provides a URL to track your asynchronous export job. Copy that URL and make another request to check on its progress. You will continue to use that access token for all of your requests.

curl \
    -H 'Authorization: Bearer xxx' \   'https://gateway.1up.health/<tenant>/bulk-data/r4/$export/job/00000000-0000-0000-0000-000000000000'

  1. As your jobs complete, that endpoint will continue to return URLs for downloadable files of your data. Copy that file name, and make another request to download it.

curl \
    -H 'Authorization: Bearer xxx' \   'https://gateway.1up.health/<tenant>/bulk-data/r4/$export/file/Patient_00000000.ndjson’

  1. Confirm and inspect the FHIR data for your patients.