Skip to main content

Notice: One of our vendors, NationsBenefits, LLC, experienced a cybersecurity incident that affected certain members’ personal information. Learn more.

1-800-260-2055

Documentation

Welcome to the SCFHP Developer Portal!

The portal provides access to SCFHP’s suite of API products, which are based on the HL7 FHIR 4.0.1 standard. The portal uses OAuth 2.0 Authorization Code with Proof Key Code Exchange (PKCE) flow for member authorization. The data that is available through the APIs is that of enrollees who are enrolled in one or more of the following health plan products offered by SCFHP:

  1. Medicare Advantage D-SNP (SCFHP DualConnect)
  2. Medicaid Managed Care Plan (SCFHP Medi-Cal)

SCFHP enables registered developers to access the following APIs:

Provider Directory API

Provider Directory API provides information on the network of contracted providers which includes the names of providers, addresses, phone numbers, and specialty.

Patient Access API

Patient Access API facilitates patient access to information through consumer applications developed by third-party application developers.

List of Products

  1. Organization
  2. Patient
  3. HealthServices (LOB)
  4. Coverage
  5. Practioner
  6. PractionerRole
  7. EOB (a.k.a. Claims, encounters, Labs, Rx)

Register with Developer Portal

To register with the SCFHP Developer Portal, use the following steps:

  1. Click Register to go to the registration page of the SCFHP Developer Portal.

  2. Fill the details as part of the registration process and click Register.
    You will receive an email with an access code and a link to set your password.
  1. Use the link to set your password and enter the access code to verify your identity.
    Instruction to set the password is included on the link.
    The access code has an expiration window of 1 hour. Failing to use the access code within the timeframe will lead you to repeat the registration process.
  1. You can login to the Developer Portal with your email address and password after successful registration.

  2. You can access the My Applications page to register a new application.
  3. You can also click the API Catalog to view the API products along with their OpenAPI specifications.

Register an Application

To register an application on the SCFHP Developer Portal, use the following steps:

  1. Login to the SCFHP Developer Portal and click My Applications.

  2. Click Add app.

  3. Enter your application name and description.

  4. You can enter the callback URL for your application.
    Callback URL is an optional field. If you want to use the built-in OAuth 2.0 Authorization feature on the portal/postman, you can leave this field blank. If you wish to use the OAuth 2.0 Authorization flow with your application, then fill in the Callback URL with the URL you wish OAuth to redirect the Authorization request.
  1. Select the API product(s) that you will use.

  2. Click Submit.
    You can now see your registered application under My Applications.
  1. You will be given a Client ID and Client Secret for each application you register.
    You need to store this information securely to authenticate your API calls.
  1. You can edit or delete your sandbox applications.
    Please note, deleted applications cannot be recovered.

Note: You can register up to 3 applications on the portal. To register a 4th application, you need to contact Healthplan IT support team.

Authorization

The Provider Directory API uses OAuth 2.0 Client Credentials authorization for connecting with the FHIR resources. The Patient Access API uses OAuth 2.0 Authorization code with Proof Key for Code Exchange (PKCE) flow for securing connections with the member data. Your registered application will be given a client ID and client secret. You will need this information to authorize your API calls to both the Provider Directory and Patient Access APIs.

OAuth 2.0 Client Credentials flow for Provider Directory API

The Client Credentials grant is used when third-party applications request an access token to access the FHIR resources.

1. The authorization process starts with your application sending a request to the Authorization server’s /token endpoint with the client credentials:

POST/oauth/v1/token?grant_type=client_credentials

AUTH HEADER:username=<CLIENT_ID>,password=<SECRET>

The following parameters are included in the request:

    1. grant_type: The value must be set to client_credentials.

    2. username: This is the Client ID for your registered application.
      You can obtain the Client ID for your application from the My Applications page.

    3. password: This is the Client Secret for your registered application.
      You can obtain the Client Secret for your application from the My Applications page.

2. The authorization server then validates the request and generates the access_token.

If the request is invalid, you will see the following error message:

Status code: 401 unauthorized

Error message: Invalid client credentials

3. You can see the generated access_token and expiry_time in the response.

4. You can then request for the Provider Directory resource by passing the access_token as the bearer_token in the request authorization header.

5. The received token is validated against the issued token and you can then view the API response.

If the token is invalid, you will see the following error message:

Status code: 401 unauthorized

Error message: Invalid access token

OAuth 2.0 Authorization Code with Proof Key for Code Exchange (PKCE) flow for Patient Access API

OAuth 2.0 Authorization code with PKCE flow describes a technique for public clients to mitigate the threat of having the authorization code intercepted. It is used for adding security during interactions between the third-party application, the user, and the authorization server. OAuth 2.0 Authorization code with PKCE is the standard code flow with an extra step at the beginning and an extra verification at the end. Your application needs to create SHA256 hashed, BASE64 encoded value containing a random string of 43-128 characters, using unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~". The unhashed version is your code verifier which will be used later when requesting the token from the /token endpoint.

  1. The authorization process starts with your application sending a request to the Authorization server’s /authorize endpoint:

POST/oauth/v1/authorize?response_type=code&scope=<SCOPE>&client_id =

<CLINET_ID>&code_challenge=

<CODE_CHALLENGE>&code_challenge_method=S256&state=..&redirect_uri=..&..”

The following parameters are included in the request:

    1. response_type: The value must be set to code.
    2. scope: This is optional. Scope provides the member granular choice over what data they would like to share with the application. For e.g. scope=openid profile/*
    3. client_id: This is the Client ID for your registered application. You can obtain the Client ID for your application from the My Applications page.
    4. code_challenge: The code challenge is a BASE64-URL-encoded string of the SHA256 hash of the code verifier.
    5. code_challenge_method: The value must be S256.
    6. state: This is recommended for your application to identify the authorization request.
    7. redirect_uri: Redirect URI is the location where the authorization server redirects the member once the member has authorized your application. The value should match the Redirect URI that you mentioned while registering your application.

In the background, the authorization server validates the request and caches code_challenge. It checks for the presence of the code_challenge and code_challenge_method and stores the value against the authorization code.

  1. The authorization server redirects the member to the login page. The member enters his/her SCFHP credentials to sign in.
  1. The consent form is displayed to the member. The member can select the scope of access which he/she wants to grant to the third-party application.
  1. Redirect the member to the redirect_uri of your registered application.
    If the member has granted consent to your application, the redirect request will contain the following encoded in a query string:

GET <your_redirect_uri>?code=<your_code>&state=<your_state>

  1. Now, your application can send the following POST request with the code obtained in the previous step for an access token:

POST/oauth/v1/token?grant_type=authorization_code&code=<CODE>&code_verifier=

<CODE_VERIFIER>&state=<STATE>AUTHHEADER:username=<CLIENT_ID>,password=<SECRET>

The authorization server verifies the code_challenge by calculating it from the received code_verifier and comparing it with the previously associated code_challenge.

The authorization server then validates the client_id, client_secret, auth_code, and generates Bearer token information.

  1. You can see the Bearer token information in the response. A successful response has the status code 200 OK in the response header. The following parameters are included in the response body:

"token_type": "BearerToken",

"issued_at": "1613489182030",

"client_id": "<client_id>",

"access_token":<access_token>

"refresh_token": "<refresh_token>",

"application_name": "<application_name>",

"scope": "",

"refresh_token_issued_at": "1613489182030",

"expires_in": "3599",

  1. You can then request for the Patient Access resource by passing the access_token as the bearer token in the request authorization header.

If the token is invalid, you will see the following error message:

Status code: 401 unauthorized

Error message: Invalid access token

Production API Access

Before you request access to production APIs, please read this section carefully. Our aim is to ensure that members feel secure about how their information is handled by third-party applications and that they are given the information they need to make informed decisions. It is imperative that you have read and understand the Terms of Use available on SCFHP’s Developer portal.

This section details the requirements that are expected from your organization’s privacy policy and terms of service. It details requirements pertinent to consent management, use and disclosure, individual access, security and incident management, and accountability and provenance. Requirements around your application’s authentication and authorization management, and application and data security is also stated in this section.

To obtain production access, you will need to comprehend these requirements and provide your responses against each category listed in SCFHP’s risk assessment questionnaire. A risk score is associated with each section of the risk assessment questionnaire, which will be used to assign a risk category to your application. The risk category assigned to your application based on the responses and attestation you provide on the risk assessment questionnaire will be made available to members. After you understand our requirements, you can refer to the Production Access Process for the steps you can take to request access to production APIs.

Requirements for Production Access

When an organization applies for production access, we require that the organization make the following resources publicly available and easily accessible for users to see and read:

  • Privacy Policy
  • Terms of Service

The following sections express our expectations from your application and from your organization at a minimum. An exhaustive list of our expectations is included in the risk assessment questionnaire.

Privacy Policy and Terms of Service

Generally, we expect your privacy policy to indicate how you collect, use and store a member’s healthcare data. The main thing that we want to see with your terms of service is that it in no way contradicts, negates or detracts from the protections detailed in your privacy policy.

Your organization’s privacy policy must inform the members when personal data disclosure has an impact on others, for e.g. impact of disclosure of genetic or family history information on relatives. The privacy policy must indicate that members can opt-out of the service and that they have the right to change options related to personal data collection process, or disclosure to third parties, consistent with the Consent policy. The privacy policy must specify what happens to a member’s personal data in the event of a transfer of ownership or in the case of a company ending or selling its business.

Note: You must notify SCFHP members about any updates to your Privacy Policy and Terms of Service.

Consent Management and Use of Disclosure

Your application’s consent policy should inform the members about the usage of their data including their ePHI and collect member’s consent on the form. Your application’s consent policy should describe how the member information will be collected, used, and shared. Your application must allow the members to withdraw their consent, at any time, and must also specify the process for consent withdrawal or account closure in the privacy policy. Your application must limit the collection of personal to only what the member has expressly consented for.

Individual Access

Members will typically be able to access their personal health record via your application. The members have the right to request corrections to any inaccurate data. Your application must allow the members to make amendments to their personal data. Your application should ensure secure disposal of the member’s personal data and ePHI, upon request.

Security and Incident Management

Ensuring safe transmission of member’s data is our topmost concern. Your organization must comply with all breach notification laws and provide meaningful remedies to address security breaches, privacy, or other violations incurred because of misuse of the member’s health information. Your application must encrypt digital records to safeguard storage and transmission of member data. It is highly encouraged that you follow industry best practices for storing and retaining data. It is essential that your application be configured with a mechanism to verify that ePHI/personal data has not been altered, modified or destroyed in an unauthorized annotation, or disclosure manner. If your organization has suffered data breach in the past, it is vital to provide details regarding the incident and remediation steps taken to confront the situation, in the risk assessment questionnaire.

Accountability and Provenance

Your organization should comply with fair information practices related to record keeping and must comply with state and federal laws. Your application must maintain information about the origin of data and the modifications and changes made to that personal data. You must also notify SCFHP and its members when you receive any certification or accreditation from any independent certifying organization. Members may face data access issues and may need a platform to voice their complaints. It is suggested to establish and clearly communicate a process for collecting and responding to member complaints.

Authentication and Authorization Management

You need to establish proper authentication and authorization controls to protect the application from unauthorized access and safeguard member data. Common mechanisms for multi-factor authentication, password complexity, password length, etc. help in adding to the security standards of the application. You need to configure necessary account protection measures like limiting the number of login attempts, locking account in case of successive failed login attempts, session timeout, etc.

Application and Data Security

Open Web Application Security Project (OWASP) is a standard awareness document for developers and web application security. It represents a broad consensus about the most critical security risks to web applications. It is an added advantage if your application mitigates the Top 10 web or mobile

application security risks. Your application must also be configured to verify that ePHI has not been altered, modified or destroyed in an unauthorized manner and ensures data backup and data recovery best practices. Your web application's firewall protection must mitigate risks such as cross-site scripting (XSS), misconfigured servers, known vulnerabilities risks, etc.

Production Access Process

Once you have read and understood the requirements for production access, you can request access to production APIs using the following steps:

  1. Login to the SCFHP Developer Portal.
  2. Click My Applications
    You will see a link on your registered application that says Request Production Access.
    Note: You can request production access for only 3 applications.
  1. Click the Request Production Access link.

You will be navigated to a Risk Assessment Questionnaire form. This questionnaire contains 8 sections:

    • Application Information
    • Privacy Policy and Terms of Service
    • Consent Management, Use and Disclosure
    • Individual Access
    • Security and Incident Management
    • Accountability and Provenance
    • Authentication and Authorization Management
    • Application and Data Security

The last section Application Onboarding – Risk Assessment displays the application risk score dashboard based on your response.

  1. Enter your application’s callback URL in the Application Information form.

Callback URL is the location to which a member would be re-directed to after they authorize your application.

Your registered email address and application name will be pre-populated

  1. Click Next.
  2. Select your response for each question listed in the sections and provide an input wherever required.

Note: Each question in the Risk Assessment Questionnaire is mandatory.

A risk score is associated with each section which indicates the risk category for your application. There are 3 risk categories for every application i.e. low risk, medium risk, high risk.

    • Low risk: Application risk score between 0 to 30
    • Medium risk: Application risk score between 31 to 70
    • High risk: Application risk score between 71 to 100

The final screen will show you your application’s risk rating and risk level, which is assigned based on the responses provided by you. You will have the opportunity to analyze and edit your response before submitting it for further review by our team.

  1. Provide attestation before you submit your response.
  2. Click Submit to send your final response.

The SCFHP team will evaluate your response and reach out to you in the case where additional follow up is needed.

The SCFHP team will schedule a face-to-face review and you will be notified about the same through an email.

When your application is granted production access, the application will have _prod appended to the application name. You will be able to view your productionized application on the My Applications page. You can further use your productionized application's Client ID and Client Secret to query the Provider Directory and Patient Access APIs and get production data.

Note: SCFHP members can choose to grant or deny their consent for third-party applications to access their personal and medical information, based on the risk scores. You can access production data only if a member has consented your application to use their information.

Sample Use Cases

These use cases will help you understand what information is being returned by the Provider Directory and Patient Access APIs.

Explanation for Practitioner resource from Provider Directory API:

https://api.SCFHP.org/ghp/fhir4/providerdirectory/v1/Practitioner?name=PractitionerName

The above URL returns all information about a person formally involved in the healthCare process and healthCare- related services on behalf of a healthcare facility. Practitioners include and are not limited to physicians, nurses, pharmacists, therapists, technologists, and social workers. The Plan Net Practitioner API returns fields including Practitioner ID, NPI, Name, Address and profile information.

This API call will return a Practitioner resource data. Here is a subset of the data returned by this resource:

{

"resourceType": "Bundle",

"id": "f28add1d-9998-481e-9f05-8d074bd469b7",

"meta": {

"lastUpdated": "2021-04-23T15:39:57.873+00:00"

},

"type": "searchset",

"total": 96,

"link": [

{

"relation": "self",

"url": "https://api.SCFHP.org/ghp/fhir4/providerdirectory/v1/Practitioner?_profile=http%3A%2F%2Fhl7.org%2Ffhir%2Fus%2Fdavinci-pdex-plan-net%2FStructureDefinition%2Fplannet-Practitioner&name=PractitionerName"

}

],

"entry": [

{

"fullUrl": "https://api.SCFHP.org/ghp/fhir4/providerdirectory/v1/Practitioner/PractitionerName",

"resource": {

"resourceType": "Practitioner",

"id": "PractitionerID",

"meta": {

"versionId": "1",

"lastUpdated": "2020-08-21T00:06:22.740+00:00",

"profile": [

"http://hl7.org/fhir/us/davinci-pdex-plan-net/StructureDefinition/plannet-Practitioner"

],

"tag": [

{

"system": "tranzform-apim-request-ns",

"code": "user-request-id",

"display": "cc1f48c2-c9a9-4394-91ae-07433d17c65b\t\t\t1"

}

]

},

. . . . . . . . . .

Explanation for Patient resource from Patient Access API:

GET https://api.SCFHP.org/ghp/fhir4/v1/Patient/[patient_id]

The above URL returns all of the member’s demographics and other administrative information as a Patient FHIR Resource. This information is mostly contact information, not medical data.

This API call will return a Patient resource. Here is a subset of the data returned by this resource:

{

"resourceType": "Patient",

"id": "PatientID",

"meta": {

"versionId": "1",

"lastUpdated": "2020-11-23T23:26:29.190+00:00",

"profile": [

"http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"

],

"tag": [

{

"system": "tranzform-apim-request-ns",

"code": "user-request-id",

"display": "1fb888bb-d0a3-49dc-a64b-d1fff9e01f9e\t\t\t1"

}

]

},

"identifier": [

{

"use": "usual",

"type": {

"coding": [

{

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

"code": "MR",

"display": "MedicalRecordNumber"

}

],

"text": "MedicalRecordNumber"

},

Explanation for Observation resource:

Observations are a central element in healthcare, used to support diagnosis, monitor progress, determine baselines and patterns and even capture demographic characteristics. This resource lets you obtain data for observation types such as vital signs, smoking data, and laboratory results.

In the synthetic data, there are synthetic members with the Vital Signs observation type.

Let us take a synthetic member record:

Username: SyntheticUsername

Password: SyntheticPassword

The Patient ID for this member is: PatientID

Let us do a simple Observation request for the preceding mentioned synthetic member: https://api.SCFHP.org/ghp/fhir4/v1/Observation

Here’s the response:

{

"resourceType": "Bundle",

"id": "02d54614-154e-477d-8614-a8ddad1e46f2",

"meta": {

"lastUpdated": "2021-03-24T09:55:29.319+00:00"

},

"type": "searchset",

"total": 1,

"link": [

{

"relation": "self",

"url": "https://api.SCFHP.org/ghp/fhir4/v1/Observation?patient=PatientID"

}

],

"entry": [

{

"fullUrl": "https://api.SCFHP.org/ghp/fhir4/v1/Observation/ObservationID",

"resource": {

"resourceType": "Observation",

"id": "ObservationID",

"meta": {

"versionId": "1",

"lastUpdated": "2020-10-21T16:01:43.864+00:00",

"profile": [

"https://www.hl7.org/fhir/us/core/StructureDefinition-us-core-observation-lab"
],

"tag": [

{

"system": "tranzform-apim-request-ns",

"code": "user-request-id",

"display": "13182d5d-a006-46cd-96bc-a749f7d71ff5\t\t\t1"

}

]

}

. . . . .

The queries to reach each observation type individually, with combination parameters would be as follows:

Vital Signs: This profile returns data related to a member’s blood pressure and heart rate readings at their last doctor visit.

For a combination of patient and category:

https://api.SCFHP.org/ghp/fhir4/v1/Observation?patient=[reference]&category=[http://terminology.hl7.org/CodeSystem /observationcategory|vital-signs

For a combination of patient and code:

https://api.SCFHP.org/ghp/fhir4/v1/Observation?patient=[reference]&code=[system]|[code]

For a combination of patient, category and date:

https://api.SCFHP.org/ghp/fhir4/v1/Observation?patient=[reference]&category=[http://terminology.hl7.org/CodeSystem /observationcategory|vital-signs&date={gt|lt|ge|le}

Smoking Status:

This profile returns information on the smoking status of the patient, whether they are currently smoking or have smoked in the past.

For a combination of patient and category:

https://api.SCFHP.org/ghp/fhir4/v1/Observation?patient=[reference]&category=[http://terminology.hl7.org/CodeSystem /observationcategory|smoking-status

For a combination of patient and code:

https://api.SCFHP.org/ghp/fhir4/v1/Observation?patient=[reference]&code=[system]|[code]

For a combination of patient, category and date: https://api.SCFHP.org/ghp/fhir4/v1/Observation?patient=[reference]&category=[http://terminology.hl7.org/CodeSystem /observationcategory|smoking-status&date={gt|lt|ge|le}

Laboratory Results

This profile returns information of a member’s test and result, or a nested set of tests, such as microbial susceptibility panel.

For a combination of patient and category

https://api.SCFHP.org/ghp/fhir4/v1/Observation?patient=[reference]&category=http://terminology.hl7.org/CodeSystem /observationcategory|laboratory

For a combination of patient and code:

https://api.SCFHP.org/ghp/fhir4/v1/Observation?patient=[reference]&code=[system]|code

For a combination of patient, category and date

https://api.SCFHP.org/ghp/fhir4/v1/Observation?patient=[reference]&category=http://terminology.hl7.org/CodeSystem /observationcategory|laboratory&date={gt|lt|ge|le}[date]"

Production Data

SCFHP Health Plan regularly monitors and audits system operations, availability, and responsiveness. The system is expected to be operational 24 hours a day, 7 days a week and 365 days a year. System functionality support is available 24 hours a day, 7 days a week and 365 days a year for Vendor API Call Receipts and Responses. If any downtime is scheduled for maintenance of the portal, a banner message will be displayed to that effect.

The production data for Claims will be made available in one business day from adjudication. The Encounter data will be made available in one business day from receipt of encounter. The Clinical data will be made available in one business day from receipt of data. The Provider Directory data will be made available within 30 calendar days of a payer receiving provider directory information or an update to provider directory information.

Developer Registration Form

Registration is done interactively here