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 CHPCDC, CHPMD, etc. Documentation and API(s) use lines of businesses (LOB) terms. Please refer to the additional information section for more details.

CareFirst APIs are secured using the OAuth 2.0 security protocol, which is the industry-standard for applications to integrate APIs. OAuth 2.0 is an authorization framework that allows applications to obtain limited access to user information via APIs.

Additionally, all consumer applications must include an HTTP header (x-api-subscription-key) with a valid subscription key assigned to their application.

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 authenticates and grants the application access.
• The user is redirected back to the application with an authorization code.
• The application requests an access token from the OAuth server by presenting the authorization code.

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 the "Sign In" link at the Menu bar.

Click the "External Developers" link from the Sign In page.

STEP 2

Click "Sign up now" at the bottom of the External Developers sign-in page.

Fill the Mandatory Fields in the Sign up 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.

STEP 1

Navigate to Login Page by clicking the "Sign In" link in menu.

STEP 2

Click the "External Developers" link from the Sign In page.

Enter a valid Email Address

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

If prompted, enter the code that you received to your email or mobile device.

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

STEP 1

Verify if you are in a sandbox environment by selecting the "sandbox" radio button at the top of the screen.

Navigate to My Account-> Dashboard-> Manage applications -> 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 has been registered, approved in the sandbox, and you have received valid credentials, you can utilize the Authorization code grant type to access the APIs through your application or tools such as Postman. It's important to conduct comprehensive testing in the sandbox environment before promoting your application 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-pit.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-pit.carefirst.com/fhir-oauth2/pub/{{lob}}/token

Headers

Body

Once your application has been registered, approved in the sandbox, and you have received valid credentials, you can utilize the Client Credentials grant type to access the APIs through your application or tools such as Postman. It's important to conduct comprehensive testing in the sandbox environment before promoting your application to production.

Once you have received the application credentials, please proceed to send an HTTP POST request to the access token endpoint. Ensure to include the specified parameters in the HTTP body.

Headers

Body

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

Using the radio environment switch button at the top of the page, change the environment to "Production".

STEP 6

Click on "Register Application" and select the approved application from Sandbox that you wish to promote.

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.