Documentation

Read more...

Introduction

 

The CareFirst API Platform is following industry-standard protocols to expose CareFirst API(s) using the REST/JSON and OAuth 2.0 security protocols. API stands for Application Programming Interface, which is a software intermediary that allows two applications to talk to each other. 

 
The Developer needs to register their application in the sandbox to start building and testing their application. Once the application is tested in the sandbox with non-production data, the developer can promote the configuration to production and request approval. CareFirst will approve the application to connect to the production environment. 

 

CareFirst has multiple plans like CHPDC, CHPMD etc. Documentation and API(s) use lines of businesses (LOB) terms. Please refer to the additional information section for more details. 

 

API Security

 

CareFirst API(s) are secured using the OAuth 2.0 security protocol. OAuth 2.0 is the industry-standard security protocol for applications to integrate API(s). OAuth 2 is an authorization framework that enables applications to obtain limited access to user information via API(s).

 

OAuth 2 provides authorization flows for web and other types of applications. Third party applications need to be registered on the CareFirst Developer Portal with a valid grant type to access health data.

 

OAuth 2.0 Protocol

 

CareFirst uses OAuth 2.0 protocols for authentication since API(s) exchange Members protected health information with third party applications upon authorization from the member. To access CareFirst's API(s) in the sandbox, your application needs to use the Authorization Code grant type. 

 

OAuth Grant Types

 

Authorization Code

 

The Authorization Code grant type is used by web and mobile apps. It is used by both web apps and native apps to obtain an access token after a user authorizes an application. Below are very high-level steps: 

The application opens a browser to send the user to the OAuth server.

The user sees the authorization prompt and approves the app’s request.

The user is redirected back to the application with an authorization code in the query string.

The application exchanges the authorization code for an access token.

 

Client Credentials

 

This flow is useful when the party that requires access to an API is a machine. This is a machine-to-machine authorization flow. In this case, the client is the resource owner, and no end-user authorization is required. An example is a CRON job as a client calling an API to do some function. 

 

Register Yourself as Developer

 

STEP 1 

 

Click “Register” link at Menu bar. 

 

It Navigates to Register -> Create Account 

 

STEP 2 

 

Create an Account Screen 

 

Fill the Mandatory Fields in the Create Account Page 

 

1. First Name 

 

2. Last Name 

 

3. Role

 

4. Company Name 

 

5. US Contact Phone Number

 

6. Email 

 

7. Password 

 

8. Confirm Password 

 

Be sure to fill out all required fields and provide the reCAPTCHA. Upon success, you will be navigated to the next step.  

 

STEP 3 

 

Verify Phone Number screen 

 

1. Enter the code received to your mobile phone VIA SMS. 

 

If you did not receive the code, click on “If you did not receive the code, please

click here to resend it.” to generate new code. This will send a message again with a new code.  

Each code will be valid for 10 minutes. By providing a valid code, you will be redirected to the

next step. 

 

STEP 4 

 

Verify Email Address screen 

 

1. Enter the code received in your Email. 

 

If you did not receive the code in your Email, you can click on “If you did not receive the code, please click here to

resend it.” to generate new Code. This will send an Email again with a new code.  

 

Each code will be valid for 10 minutes. By providing a valid code, you will be redirected to the

next step. 

 

STEP 5 

 

Terms of Use Screen 

 

1. Scroll the content entirely on the Terms of Use page to enable the Accept button. 

 

2. Click on "I have read and accept the terms of use".

 

3. Now click on “Accept” to submit. 

 

STEP 6 

 

Confirmation Screen will be displayed with a login now button. 

 

Login to developer Portal as Developer

 

STEP 1 

 

Navigate to Login Page by clicking the “Login” link in menu. 

 

STEP 2 

 

Enter a valid Email / Username 

 

STEP 3 

 

Enter a valid Password 

 

Be sure to fill out all required fields and provide the reCAPTCHA. Upon success, you will be navigated to the next step.  

 

STEP 4 

 

Enter the code received to your mobile phone VIA SMS. 

 

If you did not receive the code, click on “If you did not receive the code, please

click here to resend it.” to generate new code. This will send a message again with a new code.  

 

Each code will be valid for 10 minutes. By providing a valid code, you will be logged into the Developer Portal. 

 

Register your application in sandbox

 

STEP 1 

 

Navigate to Login-> Manage application -> Register application 

 

STEP 2 

 

Registration Screen 

 

1. Application Name

 

2. Application Display name (Non-Mandatory) 

 

3. Application Type  

 

4. Grant Type  

 

5. Response Types 

 

6. Token Endpoint Authorization Method 

 

7. Application Description (Non-Mandatory) 

 

8. Products 

 

STEP 3 

 

URIs Screen 

 

1. Application URI 

 

2. Login initiate URI 

 

3. Login Redirect URI 

 

4. Logout Redirect URI  

 

5. Attestation Certs URI (Non-Mandatory) 

 

6. Privacy URI 

 

7. TOS URI 

 

STEP 4 

 

Contact Details Page 

 

1. Contact Email

 

2. US Support Contact Phone Number. 

 

STEP 5 

 

Attestation Screen   

 

CareFirst encourages developers to attest to their application. Based on attestation, we display a warning to

our members during the login process. The warning message is displayed to members if an application is not attested-to

by the developer. Attestation of an application is optional to the developer. 

 

1. Scroll the content entirely on the attestation page to enable the Submit button. 

 

2. Click on "I have read and accept the application attestation". 

 

3. Click on the “Submit” button to attest. 

 

Now your application is registered in the sandbox, and you can view the application credentials to invoke the

APIs. 

 

View application credentials

 

STEP 1 

 

Login to the Developer Portal using valid credentials 

 

STEP 2 

 

Click on the Manage Applications card 

 

STEP 3 

 

Check whether the registered application is available in the Sandbox Environment. 

 

STEP 4 

 

To view the application credentials, click on the “View Credentials” button

 

Invoking APIs in sandbox

 

Once your application is registered successfully in the sandbox and you have valid credentials, you can invoke the APIs from your application and/or other tools like Postman. Please test your application entirely before promoting the it to production.

 

Please refer to the additional information section for more details about different endpoints and test data w.r.t different line of businesses or plans. 

 

Getting an authorization code

 

Authorization URI example. Please refer to the additional information section for lob/plan specific endpoints. 

 

https://idp-sita.carefirst.com/fhir-oauth2/sec/{{LOB}}/authorize?aud=testaud&redirect_uri=http://localhost:8080&state=qwertyuop&scope=openid&client_id={{client_id}}&response_type=code 

 

Below parameter value needs to be changed 

Replace {{LOB}} with lob name you plan to test. Please refer to the additional information section for lob name. 

Replace {{client_id}} with your application client id. 

redirect_uri 

scopes 

state 

aud 

 

On a successful call, you should have the authorization code in your redirect URI. 

 

Getting an access token

 

After receiving the application credentials and the authorization code, send a post request against the Access Token endpoint using the URL, headers, and body content below. Please refer to the additional information section for lob/plan specific endpoints. 

 

URL 

 

POST   https://idp-sita.carefirst.com/fhir-oauth2/pub/chpdc/token 

 

Headers

 

content-type 

application/json 

accept 

application/json 

authorization 

Basic base64({your_client_id}:{your_client_secret}) 

 

Body

 

code 

{oauth code} 

grant_type 

"authorization_code" 

redirect_uri 

{your_redirect_uri} 

 

Using an access token to call Patient API

 

Please refer to the additional information section for lob/plan specific endpoints. 

 

Sample Request

 

curl --location --request GET 'https://chpdc-api-sita.carefirst.com/v1/fhir/patientaccess/Patient/62f4fdda-3bf5-3de1-9a27-cc6b64c75fb8' \ 

 

--header 'Authorization: Bearer {{Access Token}}' 

 

 

Sample Response

 

{

             "resourceType": "Patient",

             "id": "62f4fdda-3bf5-3de1-9a27-cc6b64c75fb8",

             "meta":  {

                  "versionId": "1",

                  "lastUpdated": "2021-11-03T11:35:51.384+00:00",

                  "profile":  [

                        "http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Patient",

                         "http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Patient|1.1.0"

                  ]

              },

             "extension": [

            {

                  "url": "https://carefirst.com/internal/last_updated_date",

                  "valueId": "2021-11-01"

            },

           {

                 "url": "https://carefirst.com/internal/row_id",

                 "valueId": "488024"

           },

           {

                 "url": "https://carefirst.com/internal/source_id",

                "valueId": "MEDCAIDDC"

           }

          ],

          "identifier": [  

          {

              "type":

               {

                  "coding": [

                   {

                       "system": "http://terminology.hl7.org/CodeSystem/v2-0203",

                      "code": "MB"

                   }

               ]

            },

                 "system": "https://carefirst.com/internal/CF_MEMBER_LIFE_ID",

                "value": "15675098"

            },

           {

                "system": "https://carefirst.com/internal/lob",

                "value": "CHPDC"

           },

           {

               "system": "https://carefirst.com/internal/group",

               "value": "1000"

            },

            {

               "system": "https://carefirst.com/internal/plan",

               "value": "DCM"

            }

        ],

         "name": [

            {

                  "family": "Jaschuh",

                 "given":

                         "Wn"

            ]

          }

       ],

        "gender": "male",

        "birthDate": "1961-00-00",

        "address":

          [

               {

                  "city": "WASHINGTON",

                 "state": "DC",

                "postalCode": "20019",

                "period":

                      {

                           "start": "2021-10-28",

                           "end": "9999-12-31"

                      }

              }

        ]

 }

 

Get the application ready for Production

 

Promote the application to production 

 

In this step, the developer promotes the application configuration to production use. Once promoted to production, you will see the application in the production category displayed.  

 

The Developer needs to edit and update the application configuration details with production values. Once the developer is ready with the production application, the application needs to be submitted for CareFirst Approval. 

 

Please follow the steps below to make sure your application is ready to call CareFirst production API(s). 

 

Submit the Application for Approval  

 

STEP 1 

 

Login to the Developer Portal using valid credentials 

 

STEP 2 

 

Click on the Manage Applications card 

 

STEP 3 

 

Check whether the registered application is available in the Sandbox Environment. 

 

STEP 4 

 

Click on the “View Credentials” link to view credentials. 

 

STEP 5 

 

Click on “Promote to Prod” button to promote the application to the Production environment. 

 

STEP 6 

 

Click on “Submit for Approval”  

 

Invoking APIs in production 

 

Once the application is approved by CareFirst, you can start calling the CareFirst API(s) in production. Please note that approval must be completed before your application can use the API(s). 

 

Additional Information

 

CareFirst Line of Businesses implementing CMS Interoperability mandate

 

LOB 

LOB Name 

CHPDC

CareFirst BlueCross BlueShield Community Health Plan District of Columbia (aka DC Medicaid) 

CHPMD

CareFirst BlueCross BlueShield Community Health Plan Maryland (aka MD Medicaid) 

DSNP 

CareFirst BlueCross Blue Shield Medicare Advantage Dual Prime (aka MD DSNP) 

MAPD 

CareFirst BlueCross Blue Shield Medicare Advantage 

MHBE 

Maryland Health Benefits Exchange 

EGWP 

Employer Group Waiver Plan 

 

CMS Interoperability mandate API(s) implemented by LOB(s)

 

LOB 

Patient Access 

Provider Directory 

CHPDC 

YES 

YES 

CHPMD 

YES 

YES 

DSNP 

YES 

YES 

MAPD 

YES 

YES 

MHBE 

YES 

Not applicable. 

EGWP 

YES 

YES 

 

Credentials of test users in sandbox for testing Patient Access API

 

LOB 

Username 

Password 

CHPDC 

 chpdc_cftestuser5 

 chpdc_cftestuser6

 Test@123 

CHPMD 

  chpmd_cftestuser5 

 Test@123 

DSNP 

  dsnp_cftestuser5  

 Test@123 

MAPD 

 mapd_cftestuser5 

Test@123  

MHBE 

 mhbe_cftestuser5 

Test@123 

EGWP 

 egwp_cftestuser2 

 Test@123 

  

Sandbox Well-Known /Smart Configuration Patient Access API Endpoints 

 

LOB 

Well-Known Endpoint URL 

CHPDC 

https://chpdc-api-sita.carefirst.com/v1/fhir/patientaccess/metadata 

CHPMD 

https://chpmd-api-sita.carefirst.com/v1/fhir/patientaccess/metadata 

DSNP 

https://dsnp-api-sita.carefirst.com/v1/fhir/patientaccess/metadata 

MAPD 

https://mapd-api-sita.carefirst.com/v1/fhir/patientaccess/metadata 

MHBE 

https://mhbe-api-sita.carefirst.com/v1/fhir/patientaccess/metadata 

EGWP 

https://egwp-api-sita.carefirst.com/v1/fhir/patientaccess/metadata 

 

Sandbox Patient Access API Endpoints 

 

LOB 

API Endpoint 

CHPDC 

 https://chpdc-api-sita.carefirst.com/v1/fhir/patientaccess 

CHPMD 

 https://chpmd-api-sita.carefirst.com/v1/fhir/patientaccess 

DSNP 

 https://dsnp-api-sita.carefirst.com/v1/fhir/patientaccess 

MAPD 

 https://mapd-api-sita.carefirst.com/v1/fhir/patientaccess 

MHBE 

 https://mhbe-api-sita.carefirst.com/v1/fhir/patientaccess 

EGWP 

https://egwp-api-sita.carefirst.com/v1/fhir/patientaccess 

 

Sandbox Provider Directory API Endpoints 

 

LOB 

API Endpoint 

CHPDC 

https://chpdc-api-sita.carefirst.com/v1/fhir/provider 

CHPMD 

https://chpmd-api-sita.carefirst.com/v1/fhir/provider 

DSNP 

https://dsnp-api-sita.carefirst.com/v1/fhir/provider 

MAPD 

https://mapd-api-sita.carefirst.com/v1/fhir/provider 

MHBE 

Not applicable. 

EGWP 

https://egwp-api-sita.carefirst.com/v1/fhir/provider 

 

Production Well-Known/Smart Configuration for Patient Access API Endpoints 

 

LOB 

Well-Known Endpoint URL 

CHPDC 

https://chpdc-api.carefirst.com/v1/fhir/patientaccess/metadata 

CHPMD 

https://chpmd-api.carefirst.com/v1/fhir/patientaccess/metadata 

DSNP 

https://dsnp-api.carefirst.com/v1/fhir/patientaccess/metadata 

MAPD 

https://mapd-api.carefirst.com/v1/fhir/patientaccess/metadata 

MHBE 

https://mhbe-api.carefirst.com/v1/fhir/patientaccess/metadata 

EGWP 

https://egwp-api.carefirst.com/v1/fhir/patientaccess/metadata 

 

Production Patient Access API Endpoints 

 

LOB 

API Endpoint 

CHPDC 

 https://chpdc-api.carefirst.com/v1/fhir/patientaccess 

CHPMD 

 https://chpmd-api.carefirst.com/v1/fhir/patientaccess 

DSNP 

 https://dsnp-api.carefirst.com/v1/fhir/patientaccess 

MAPD 

 https://mapd-api.carefirst.com/v1/fhir/patientaccess 

MHBE 

 https://mhbe-api.carefirst.com/v1/fhir/patientaccess 

EGWP 

https://egwp-api.carefirst.com/v1/fhir/patientaccess 

 

Production Provider Directory API Endpoints 

 

LOB 

API Endpoint 

CHPDC 

https://chpdc-api.carefirst.com/v1/fhir/provider 

CHPMD 

https://chpmd-api.carefirst.com/v1/fhir/provider 

DSNP 

https://dsnp-api.carefirst.com/v1/fhir/provider 

MAPD 

https://mapd-api.carefirst.com/v1/fhir/provider 

MHBE 

Not applicable. 

EGWP 

https://egwp-api.carefirst.com/v1/fhir/provider 

 

Help center

 

You may get help by using the FAQ, Contact Us and Documentation pages from the Help Center. 

 

If you have a question or need additional assistance, please reach out to our team by using the Contact Us form located in the Help Center.