Payer implementation

Payer organizations that want to utilize 1up Payer to Payer Data Exchange must register on the 1up Dev Portal and complete the identity verification process. 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 Payer-to-Payer Data Exchange and bulk export member data from our partnered payer organizations.

See Payer network for a list of our partnered payer organizations.

In order to make a request to the Payer-to-Payer Data Exchange, an access token must be supplied that identifies your payer organization. This token is obtained through an OAuth 2.0 client credentials flow, enabled by 1up's Dev Portal.

Once you complete this procedure, 1upHealth will review the information provided to verify your organization. While your production access is pending, you can access the 1up sandbox and create clients to pull synthetic data. Once your requested production access has been granted, you will have access to create and manage production clients.

1. Access the 1up Dev Portal login page.
2. Register for the 1up Dev Portal, complete email verification, and login.
3. From the Dev Portal home page, in the left hand sidebar, click Production Clients.
4. On the Production Clients screen, click Request Access. To gain production access, you must submit a multi-stage production access form so 1up can validate your organization.
5. Fill out the Requesting Production Access form:
   1. Select Payer under Organization Type. This requests access to the Payer claims data (CMS Payer-to-payer access) access type.
   2. Select a Federal Identity Type and enter the required information.
   3. Click Next and fill out the remaining information on the form which provides details for the vetting process used by 1up.
   4. Click Submit.

1. Login to the 1up Dev Portal.
2. From the Dev Portal home page, in the left hand sidebar, click Production Clients. The client creation screen is displayed.
3. Under Access Type, select Payer claims data (CMS Payer-to-payer access).
4. Enter a Client Name and Description for your client.
5. Click Create.

The production process is the same as the sandbox process, except you insert a real member's information in the request for their data.

Contact 1upHealth for a list of {tenant} values you can query.

1. Copy your production client ID and client secret.

2. Request an authorization token by pasting the following code into a terminal. Use the copied client_id and client_secret for this request.

   curl -i -X POST \
       https://gateway.1up.health/auth/realms/dev-portal/protocol/openid-connect/token \
       -H 'Content-Type: application/x-www-form-urlencoded' \
       -d 'client_id={your-id-here}' \
       -d 'client_secret={your-secret-here}' \
       -d grant_type=client_credentials \
       -d 'scope=member-match|read'

3. Copy the access_token from the successful response. You will use this token for subsequent requests.

4. Send a request for a specific member's data from a specific payer using the below request. The values listed in the request below are required, but additional data may be provided in the request.

   Required fields

   Member match requests must contain exactly one each of the memberPatient, CoverageToMatch, and Consent parameters. The CoverageToLink parameter is optional.

   curl --location 'https://gateway.1up.health/v1/{tenant}/member-match/$member-match' \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer {access_token}' \
   --data '{
   "resourceType": "Parameters",
   "id": "{member-id}",
   "parameter": [
       {
       "name": "MemberPatient",
           "resource": {
           "name": [
               {
                   "given": ["{given-name}"],
                   "family": "{family-name}"
               }
               ],
           "birthDate": "{YYYY-MM-DD}"
           }
       },
   {
       "name" : "CoverageToMatch",
       "resource" : {
           "identifier" : [
           {
               "value" : "{coverage-id}"
           }
           ]
       }
       }
       ,
       {
       "name": "Consent",
       "resource": {
           "resourceType": "Consent",
           "id": "{consent-id}",
           "status": "active",
           "policy": [
       {
       "uri": "http://hl7.org/fhir/us/davinci-hrex/StructureDefinition-hrex-consent.html#regular"
       }
   ],
   "provision": {
       "type": "permit",
       "period": {
       "start": "{YYYY-MM-DD}",
       "end": "{YYYY-MM-DD}"
       }
   }
       }
       }
   ]
   }

5. Copy the groupId value from the successful response.

6. Send a request to bulk export the member's data using the groupId value.

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

7. Copy the job-id from the end of the text value in the successful response.

   {
       "resourceType": "OperationOutcome",
       "id": "{operation-id}",
       "issue": [
           {
               "severity": "information",
               "code": "informational",
               "details": {
                   "text": "Asynchronous export running. Track job at https://gateway.1upcoredev.com/v1/{tenant}/bulk-data/r4/$export/job/{job-id}"
               }
           }
       ]
   }

8. Send a request to check on the status of the bulk export and return the URLs necessary for receiving the member data.

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

9. Copy the url ending in .ndjson for one of the batches. From the example below, https://gateway.1upcoredev.com/v1/bison/bulk-data/r4/$export/file/{batch-1-.ndjson-url} is one of the URLs out of 6 batches.

   {
       "id": "{job-id}",
       "transactionTime": "YYYY-MM-DDTHH:mm:ss.SSSZ",
       "request": "https://gateway.1up.health/v1/{tenant}/bulk-data/r4/Group/cmk1cuald0005l701sdo7gs8c/$export",
       "requiresAccessToken": true,
       "status": "Successful",
       "resourceCount": 31,
       "batches": {
           "running": 0,
           "complete": 6,
           "failed": 0,
           "total": 6
       },
       "lastUpdated": "YYYY-MM-DDTHH:mm:ss.SSSZ",
       "output": [
           {
               "type": "Specimen",
               "url": "https://gateway.1up.health/v1/{tenant}/bulk-data/r4/$export/file/{batch-1-.ndjson-url}"
           },
           {
               "type": "Coverage",
               "url": "https://gateway.1up.health/v1/{tenant}/bulk-data/r4/$export/file/{batch-2-.ndjson-url}"
           },
           {
               "type": "Patient",
               "url": "https://gateway.1up.health/v1/{tenant}/bulk-data/r4/$export/file/{batch-3-.ndjson-url}"
           },
           {
               "type": "ExplanationOfBenefit",
               "url": "https://gateway.1up.health/v1/{tenant}/bulk-data/r4/$export/file/{batch-4-.ndjson-url}"
           },
           {
               "type": "Encounter",
               "url": "https://gateway.1up.health/v1/{tenant}/bulk-data/r4/$export/file/{batch-5-.ndjson-url}"
           },
           {
               "type": "Observation",
               "url": "https://gateway.1up.health/v1/{tenant}/bulk-data/r4/$export/file/{batch-6-.ndjson-url}"
           }
       ]
   }

10. Send a request to receive the requested member data from one of the batches. The data is returned as Newline Delimited JSON (NDJSON).

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

11. Send requests for each of the remaining batches.