Documentation

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. 

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.

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. 

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. 

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. 

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. 

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

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. 

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. 

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

Body

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

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

CareFirst Line of Businesses implementing CMS Interoperability mandate

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

Credentials of test users in sandbox for testing Patient Access API

Sandbox Well-Known /Smart Configuration Patient Access API Endpoints 

Sandbox Patient Access API Endpoints 

Sandbox Well-Known /Smart Configuration Payer Access API Endpoints 

Sandbox Payer Access API Endpoints 

Sandbox Provider Directory API Endpoints 

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

Production Patient Access API Endpoints 

Production Well-Known /Smart Configuration Payer Access API Endpoints 

Production Payer Access API Endpoints 

Production Provider Directory API Endpoints 

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.