Implementation for Providers

This page is intended for technical staff at provider organizations.

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.

From the Dev Portal, provider organizations can both create a sandbox client and request access to the production client. Accessing production data requires verification by 1upHealth. Once your organization is verified, you can generate client credentials and retrieve an authorization token. This token can be used to make requests to the Provider Access API and export data for your patients.

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 URLs 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.

Quick-start with a sandbox client

You can test the process for creating a client, setting up access with client credentials and an authorization token, and requesting patient data with a sandbox client.

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

2. Register for the 1up Dev Portal, then complete email verification, and login.

3. Click 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 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 client's name as well as an option to copy the client secret.

6. Copy your new client ID and client secret from the clients table.

7. Request an authorization token by pasting the following code into a terminal. Replace the {curly brackets} and any text inside them with the appropriate value.

   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'

8. Copy the access_token from the response to a text file. You will use this token for subsequent requests.

9. Make your FHIR bulk export request by replacing {access_token} for your copied access token. This request returns all data the payer has saved for any patients attributed to your organization. Replace {tenant} with bison for this sandbox client. For a production client, you would replace {tenant} with the tenant value for a payer. Contact 1upHealth support for a list of available payers for your production client.

   curl --location 'https://gateway.1up.health/v1/{tenant}/bulk-data/r4/$export' \
       --header 'Authorization: Bearer {access_token}'

10. Copy the job URL from the response.

11. Send a request to check the progress of the FHIR bulk export. The response will include a list of files using URLs.

    1
    2
    curl --location '{job_URL}' \
        --header 'Authentication: Bearer {access_token}'

12. Copy the URL for any of the files.

13. Send a request to return the data from one of the files.

    1
    2
    curl --location '{file_URL}' \
        --header 'Authentication: Bearer {access_token}'

14. Review the patient information returned from the sandbox client.

Bulk export for production clients

The process and commands are the same in production as they are for the quick start instructions.

1. Copy your production client ID and client secret.

2. Request an authorization token by pasting the following code into a terminal. Replace the {curly brackets} and any text inside them with the appropriate value.

   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'

3. Copy the access_token from the response to a text file. You will use this token for subsequent requests.

4. Make your FHIR bulk export request by replacing {access_token} for your copied access token. This request returns all data the payer has saved for any patients attributed to your organization. Replace {tenant} with the tenant value for a payer. Contact 1upHealth support for a list of available payers for your production client.

   curl --location 'https://gateway.1up.health/v1/{tenant}/bulk-data/r4/$export' \
       --header 'Authorization: Bearer {access_token}'

5. Copy the job URL from the response.

6. Send a request to check the progress of the FHIR bulk export. The response will include a list of files using URLs.

   1
   2
   curl --location '{job_URL}' \
       --header 'Authentication: Bearer {access_token}'

7. Copy the URL for any of the files.

8. Send a request to return the data from one of the files.

   1
   2
   curl --location '{file_URL}' \
       --header 'Authentication: Bearer {access_token}'

9. Review the patient information returned from the sandbox client.