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 CHPCDC, 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 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.
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 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.
Register Yourself as Developer
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.
Register Yourself as a Developer from Brokerage Agency
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.
Select "Developer from Brokerage Entity" in the Developer Type drop down
Provide the reCAPTCHA. Upon success, you will be navigated to the next step.
STEP 3
Enter Company Information
Fill the Mandatory Fields in the Sign up Page
1. Company Legal Name
2. Employer Identification number
3. Company Email Domain
Be sure to accept the HIPAA Affirmation
STEP 4
Enter Company Address
Fill the Mandatory Fields
1. Street Address
2. State
3. City
4. Zip Code
5. Phone
6. Website URL
STEP 5
Enter Customer Service Information
Fill the Mandatory Fields
1. Customer Service Email
2. Customer Service Phone
STEP 6
Enter Primary Contact Information
Fill the Mandatory Fields
1. First Name
2. Last Name
3. Company Email Address
4. Company Phone Number
5. Designation
STEP 7
Enter Secondary Contact Information
Fill the Mandatory Fields
1. First Name
2. Last Name
3. Company Email Address
4. Company Phone Number
5. Designation
STEP 8
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 9
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 10
Confirmation Screen will be displayed.
Login to Developer Portal as Developer
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.
Register your application in sandbox
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.
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 using Authorization code grant type
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.
Getting an authorization code
Authorization URI example. Please refer to the additional information section for lob/plan specific endpoints.
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-pit.carefirst.com/fhir-oauth2/pub/{{lob}}/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-apix-pit.carefirst.com/extfhirpatientaccess/v1/Patient/62f4fdda-3bf5-3de1-9a27-cc6b64c75fb8' \
--header 'Authorization: Bearer {{Access Token}}'
{
"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"
}
}
]
}
Invoking APIs using Client Credentials grant type
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.
Getting an access token
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.
| Environment | Token Endpoint | Scope |
|---|---|---|
| Sandbox | https://api-pit.carefirst.com/token/v2 | fb0bbf9f-9a04-46ce-a473-027706c2e37d/.default |
| Production | https://api.carefirst.com/token/v2 | 6e6bd3b4-6922-4d5b-b852-a5ff09bda986/.default |
Headers
| content-type | application/x-www-form-urlencoded |
| x-api-subscription-key | {your_subscription_key} |
Body
| client_id | {your_client_id} |
| grant_type | "client_credentials" |
| client_secret | {your_client_secret} |
| scope | {Refer to the above scope table} |
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
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).
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 | Payer Access |
| CHPDC | YES | YES | YES |
| CHPMD | YES | YES | YES |
| DSNP | YES | YES | YES |
| MAPD | YES | YES | YES |
| MHBE | YES | Not applicable. | YES |
| EGWP | YES | 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
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
| LOB | API Endpoint |
| CHPDC | https://chpdc-apix.carefirst.com/extfhirproviderdir/v1 |
| CHPMD | https://chpmd-apix.carefirst.com/extfhirproviderdir/v1 |
| DSNP | https://dsnp-apix.carefirst.com/extfhirproviderdir/v1 |
| MAPD | https://mapd-apix.carefirst.com/extfhirproviderdir/v1 |
| MHBE | Not applicable. |
| EGWP | https://egwp-apix.carefirst.com/extfhirproviderdir/v1 |
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.