Payer implementation

This page is intended for technical staff at external payer organizations (payers not partnered with 1upHealth).

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.

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.

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 member data with a sandbox client.

Replace the {curly brackets} and any text inside them with the appropriate value. The sandbox tenant for this process is bison .

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 Payer claims data (CMS Payer-to-payer access).

5. Enter a Client Name.

6. Click Create.

7. From Sandbox Clients, copy your new client's Client ID and Client Secret.

8. Using Postman or a terminal window, send the following request for an authorization token. 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=member-match-sandbox|read'

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

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

    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/bison/member-match-sandbox/$member-match' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer {auth-token-for-member-match}' \
    --data '{
      "resourceType": "Parameters",
      "id": "member-match-in",
      "parameter": [
        {
          "name": "MemberPatient",
            "resource": {
              "name": [
                  {
                    "given": ["Jay"],
                    "family": "Young"
                  }
                ],
              "birthDate": "2001-03-11"
            }
          },
    {
          "name" : "CoverageToMatch",
          "resource" : {
            "identifier" : [
              {
                "value" : "17148123-47da-43a0-8401-8d5d1368db02"
              }
            ]
          }
        }
        ,
        {
          "name": "Consent",
          "resource": {
            "resourceType": "Consent",
            "id": "consent123",
            "status": "active",
             "policy": [
        {
          "uri": "http://hl7.org/fhir/us/davinci-hrex/StructureDefinition-hrex-consent.html#regular"
        }
      ],
      "provision": {
        "type": "permit",
        "period": {
          "start": "2022-01-01",
          "end": "2035-01-31"
        }
      }
          }
        }
      ]
    }

11. Copy the groupId value from the successful response.

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

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

13. Copy the job ID from the end of the text value in the successful response. The job ID from the example below is the number 44bb133a-2033-4ba1-a29d-f50abb99e538.

    {
        "resourceType": "OperationOutcome",
        "id": "j7dl66lqv6",
        "issue": [
            {
                "severity": "information",
                "code": "informational",
                "details": {
                    "text": "Asynchronous export running. Track job at https://gateway.1upcoredev.com/v1/bison/bulk-data/r4/$export/job/44bb133a-2033-4ba1-a29d-f50abb99e538"
                }
            }
        ]
    }

14. 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.1upcoredev.com/v1/bison/bulk-data/r4/$export/job/{job-id}' \
    --header 'Authorization: Bearer {token}'

15. 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/Specimen_2ae9a36c.ndjson is one of the URLs out of 6 batches.

    {
        "id": "44bb133a-2033-4ba1-a29d-f50abb99e538",
        "transactionTime": "2026-01-05T16:08:38.956Z",
        "request": "https://gateway.1upcoredev.com/v1/bison/bulk-data/r4/Group/cmk1cuald0005l701sdo7gs8c/$export",
        "requiresAccessToken": true,
        "status": "Successful",
        "resourceCount": 31,
        "batches": {
            "running": 0,
            "complete": 6,
            "failed": 0,
            "total": 6
        },
        "lastUpdated": "2026-01-05T16:08:51.646Z",
        "output": [
            {
                "type": "Specimen",
                "url": "https://gateway.1upcoredev.com/v1/bison/bulk-data/r4/$export/file/Specimen_2ae9a36c.ndjson"
            },
            {
                "type": "Coverage",
                "url": "https://gateway.1upcoredev.com/v1/bison/bulk-data/r4/$export/file/Coverage_ff99b57c.ndjson"
            },
            {
                "type": "Patient",
                "url": "https://gateway.1upcoredev.com/v1/bison/bulk-data/r4/$export/file/Patient_797bccd4.ndjson"
            },
            {
                "type": "ExplanationOfBenefit",
                "url": "https://gateway.1upcoredev.com/v1/bison/bulk-data/r4/$export/file/ExplanationOfBenefit_f53222ae.ndjson"
            },
            {
                "type": "Encounter",
                "url": "https://gateway.1upcoredev.com/v1/bison/bulk-data/r4/$export/file/Encounter_edd3675f.ndjson"
            },
            {
                "type": "Observation",
                "url": "https://gateway.1upcoredev.com/v1/bison/bulk-data/r4/$export/file/Observation_ac712cd2.ndjson"
            }
        ]
    }

16. 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.1upcoredev.com/v1/bison/bulk-data/r4/$export/file/{url-ending-in-.ndjson}' \
    --header 'Authorization: Bearer {token}'

17. Send requests for each of the remaining batches.

Request production access

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

Create a production client

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.

Bulk export for production clients

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.

Replace the {curly brackets} and any text inside them with the appropriate value.

1. Copy your production client ID and client secret.

2. Using Postman or a terminal window, send the following request for an authorization token.

   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=member-match|read'

3. Copy the access_token from the response to a text file. 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.

   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 {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 {auth-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 {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 {token}'

11. Send requests for each of the remaining batches.