TPA Stream Connect

Client Library

Usage

Our JavaScript Client Library is designed to allow users of your Web or Mobile application to connect their Health Insurance accounts with your Application.

To get up and running, you can simply copy and paste the JavaScript snippets below, and run it in isDemo mode today. You can use the provided callbacks to customize the look, feel, and overall experience for your users.

JavaScript Client

Source Code

You can find the source code to our JavaScript Client here: https://github.com/TPAStream/stream-connect-js-sdk

CDN Example

<script src="https://app.tpastream.com/static/js/sdk.js"></script>
<script>
    window.StreamConnect({
        el: '#react-hook',
        tenant: {
            systemKey: 'test',
            vendor: 'internal'
        },
        employer: {
            systemKey: 'some-system-key',
            vendor: 'internal',
            name: 'some-name'
        },
        user: {
            firstName: 'Joe',
            lastName: 'Sajor',
            email: 'some-email@place.com',
            memberSystemKey: 'some-system-key',
            phoneNumber: '333333333',
            dateOfBirth: '11-11-1121'
        },
        apiToken: 'Some Provided Key → 21poi34kjqf21j1poi1d2po', // We'll provide this.
        isDemo: false,
        realTimeVerification: true,
        renderChoosePayer: true,
        doneGetSDK: ({ user, payers, tenant, employer }) => {},
        doneChoosePayer: ({ choosePayer, streamPayers }) => {},
        doneTermsOfService: () => {},
        doneCreatedForm: () => {},
        donePostCredentials: ({ params }) => {},
        doneRealTime: () => {},
        donePopUp: () => {},
        doneEasyEnroll: ({ employer, payer, tenant, policyHolder, user }) => {},
        handleFormErrors: (error, {response, request, config}) => {},
        userSchema: {}
    })
</script>
As of SDK version 0.4.7 the CDN provider is now versioned and will support up to 10 minor versions behind.

Supported Parameters

The SDK currently supports the following parameters:

  • el (This is where the SDK will render: Note -> This is a ‘css selector’)

  • tenant
    • systemKey
    • vendor
  • employer

    • systemKey
    • vendor (This will usually be ‘internal’)
    • name
  • user

    • firstName
    • lastName
    • email
    • memberSystemKey
    • phoneNumber
  • apiToken

  • realTimeVerification -> Bool

  • renderChoosePayer (If this is set to false doneChoosePayer* will pass all the required methods to create your own module)

  • isDemo -> Bool (This is recommended for sandboxing before you hook the SDK up for real)

  • userSchema (This is an object {} following react-jsonschema-form for making ui:schema)

  • doneGetSDK * (Below are args passed into the func)

    • user
    • payers
    • tenant
    • employer
  • doneChoosePayer * (The following params only appear when renderChoosePayer is false)

    • streamPayers

    • choosePayer * (The function to be called to render the next SDK step)

      • payer (An obj value from streamPayers)
      • Your functional call should look like choosePayer({payer: streamPayers[some_index]})
  • doneTermsOfService *

  • doneCreatedForm *

  • donePostCredentials *

    • params (All submitted params to our API)
  • donePopUp *

  • doneRealTime *

  • doneEasyEnroll *

    • employer
    • payer
    • policyHolder
    • user
    • tenant
  • handleFormErrors *

    • error
    • error_parts
      • response
      • request
      • config

Note: only ‘el’ is required for demo mode

Function (() => {}) parameters are Starred*

Android Example

In Android, you can implement the JavaScript SDK by creating an html file in your assets folder that loads the SDK, then loading it in a WebView. Here’s a simple example implementation in Java.

public class ViewWeb extends Activity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.content);
        WebView webview = (WebView) findViewById(R.id.webView);
        webview.loadUrl("file:///android_asset/stream-connect.html");
    }
}

iOS Example

In iOS, you can implement the JavaScript SDK by creating a directory in your project (“stream-connect” in the below example), and putting an html file in it (index.html in the below example) that loads the SDK. You can then load it into a WKWebView. Here’s a simple example implementation in Objective-C.

import UIKit
import WebKit

class ViewController: UIViewController, WKUIDelegate, WKNavigationDelegate {

    @IBOutlet weak var webView: WKWebView!
    override func viewDidLoad() {
        super.viewDidLoad()
        webView.uiDelegate = self
        webView.navigationDelegate = self
        let url = Bundle.main.url(forResource: "index", withExtension: "html", subdirectory: "stream-connect")!
        webView.loadFileURL(url, allowingReadAccessTo: url)
        let request = URLRequest(url: url)
        webView.load(request)
    }
}

Change Log

v0.4.8 (Latest)

  • Add individual endpoints for the following: payer and terms of service
  • Seperate the versions of the api and create a version manager.
  • Drastically improve initial endpoint loadtime by bringing down less info.

v0.4.7

  • Add versioning to the CDN provider
  • Append version to all request headers for underlying api to read.

Webhooks

Claim Webhook

TPA Stream offers a claim webhook feature in which TPA Stream will post new claims to a customer-provided endpoint. We will POST any new claim that comes into TPA Stream via this webhook immediately after it is processed.

Claim Webhook URL

To edit the claim webhook URL, click on “Account Settings” on the settings page.

_images/account-settings.png

Note that you will only see this setting if the claim webhook feature is enabled.

Once the webhook URL has been updated, all future posts will go to that URL.

Replaying a Claim Post

_images/replay-claim-webhook.png

To manually replay a claim post, find the appropriate claim on the claims page and click the “Replay webhook” button. If the button is not shown, please verify that the webhook feature is enabled and a URL is set as described above. This “replay” functionality is useful for testing, and can also be used to trigger a webhook for any pre-existing claims that are in the system, if desired.

First Crawl Completion Webhook

TPA Stream also offers a crawl webhook feature that posts details about the first crawl of a policyholder to a customer-provided endpoint. It will POST this information after all the claims for the crawl have been processed. The last POST for a policy holder will occur when the crawl is successful for the first time. For example, if the first two crawls fail and next two attempts are successful, 3 POST requests will be made. Two for the failures and a third, final POST for the first success.

First Crawl Completion Webhook URL

To edit the first crawl completion webhook URL, click on “Account Settings” on the settings page similar to editing the claim webhook URL.

Replaying a Crawl Completion Post

_images/replay-crawl-webhook.png

To manually replay a first completion webhook post, find the appropriate member on the member page. Under policy holders, there will be a button to replay the webhook request. If the button is not shown, please verify that the webhook feature is enabled and a URL is set as described above. This “replay” functionality is useful for testing. If a crawl for that policy holder has not happened yet, it will return a failure. Note that the replay will not have crawl_claim_ids and will not be retried upon failure.

Request Retries

The request will be an HTTP POST with Content-Type header of application/json. An example of the JSON you can expect can be found at the end of this document. For Webhook POSTs, TPA Stream listens for the following codes from your server and reacts accordingly:

  • If TPA Stream receives a 200 or 2xx (Success) code it will determine the webhook POST is successful and not retry.
  • If TPA Stream receives a 406 (Not Acceptable) code, TPA Stream will determine the POST is rejected and not retry.
  • For any other code, TPA Stream will retry POSTing with an exponential backoff delay for up to 4 hours.

Security

TPAStream-Signature Verification

Also included in the request is a JWT signature that can be used to verify that the request has originated from TPA Stream, and not any other party. This header is passed in the TPAStream-Signature header of the request. The signature can be verified using our SSH RSA public key. The key can be obtained from https://app.tpastream.com/keys. The JWT hashing algorithm used is RS256.

We strongly recommend that you verify our JWT signature as a part of your webhook. Examples of how to decode a JWT in several common programming languages can be found at https://jwt.io. Note that the JWT library you choose must support RS256 (nearly all of them do), and should also support an exp check (although you could easily perform this simple expiration date check yourself using a UTC timestamp).

Example Claim Webhook JSON Request

{
   "data": {
      "service_provider_billing_npi_number": null,
      "computed_coinsurance_patient": null,
      "group_name": null,
      "members": [{
          "id": 99999999,
          "email": "johnny@appleseed.com",
          "first_name": "Johnny",
          "last_name": "Appleseed",
          "employer": {
              "id": 999,
              "name": "Dunder Mifflin"
          }
      }],
      "group_number": null,
      "eob_date": "2017-07-01T16:51:16.701956",
      "date_column": "2017-07-01T16:51:16.701956+00:00",
      "service_provider_number": "laMhYxXFh",
      "service_provider_billing_number": null,
      "coinsurance_patient": null,
      "modifieddate": "2017-06-01T04:14:29.348875+00:00",
      "service_provider_billing_address": null,
      "status": "Partially Approved",
      "amount_billed": 228,
      "reduction": null,
      "claim_medical_lines": [{
         "claim_medical_line_id": 10004,
         "procedure_code": "87254 - VIRUS INOCULATION SHELL VIA",
         "days_supply": null,
         "copayment": null,
         "date_of_service": {
         "bounds": "[]",
         "start": "2020-01-16",
         "end": "2020-01-17"
         },
         "vendor_system_id": "2b7e0936",
         "discount": null,
         "coinsurance_patient": null,
         "amount_allowed": null,
         "national_drug_code": null,
         "prescription_type_id": null,
         "patient_responsibility": 0,
         "procedure_name": "Preventive Visit-Ages 18-39 - see note E23",
         "prescription_type_str": null,
         "amount_billed": 228,
         "reduction": null,
         "amount_paid": null,
         "amount_not_covered": null,
         "diagnosis_code": "M19.172",
         "quantity": null,
         "amount_paid_other": null
      }],
      "amount_paid_other": null,
      "computed_reduction": null,
      "vendor_system_id": "28284fbbaa164d02",
      "discount": null,
      "computed_amount_billed": null,
      "service_provider_npi_number": null,
      "patient_responsibility": 0,
      "dataobject_id": 104,
      "remarks": "leverage ubiquitous users",
      "service_provider_billing_name": null,
      "network": null,
      "amount_not_covered": null,
      "copayment": null,
      "computed_copayment": null,
      "policy_holder": {
         "id": 104,
         "first_name": "Parrish",
         "last_name": "Appleseed"
      },
      "patient_account_number": null,
      "tpafiles": [],
      "date_of_service": {
         "bounds": "[]",
         "start": "2020-01-28",
         "end": "2020-01-28"
      },
      "incurred_value": null,
      "is_incomplete": null,
      "id": 10004,
      "type": null,
      "amount_allowed": null,
      "service_provider_address": "1097 Dicha Garden",
      "claim_requests": [],
      "computed_amount_paid": null,
      "check_number": "8858906",
      "last_updated_status": "2020-02-11T13:56:45.249767+00:00",
      "processed_on": "2017-06-21T00:30:46.791615",
      "createddate": "2016-03-17T07:11:30.580677+00:00",
      "computed_amount_allowed": null,
      "dependents": [{
          "id": 999,
          "member_id": 9999,
          "first_name": "Sally",
          "last_name": "Appleseed",
          "email": "sally@appleseed.com",
          "ssn": "999999999",
          "relationship": "spouse",
          "createddate": "2017-07-01T16:51:16.701956",
          "modifieddate": "2017-07-01T16:51:16.701956",
      }],
      "patient_payer_number": null,
      "service_provider_billing_phone": null,
      "claim_medical_id": 10004,
      "check_date": "2020-01-24T23:49:50+00:00",
      "computed_patient_responsibility": null,
      "amount_paid": null,
      "service_provider": "Salary.com",
      "patient_name": "Abram",
      "policy_holder_id": 104
   }
}

Example Crawl Webhook JSON Request

{
    "data": {
        "members": [
            {
                "id": 63167
            }
        ],
        "policy_holder": {
            "id": 189162,
            "login_correction_message": "The login information you provided for Anthem is invalid. Please re-enter your login information.",
            "login_problem": "invalid"
        },
        "success": false
    }
}