Introduction

This document outlines the requirements of connecting Jellyvision’s Partner Integration API for Jellyvision partners looking to provide their end users with a more personalized ALEX experience and seamless enrollment process.

Certain capabilities of the Jellyvision Partner Integration are optional; therefore, the connection requirements can vary.

Streamlining the ALEX experience

End-user demographic information

End-user demographic data such as zip code, date of birth, or union status can be provided to the Jellyvision Partner Integration API to pre-answer eligibility and demographic information necessary for the experience.

End-user eligibility mapping

ALEX can be set up via the Jellyvision Integration API to automatically know which medical, dental, and vision plans as well as employer health fund contributions an end-user is eligible for without asking for demographic information.

However, some demographic information will still be asked in order to provide end users with an accurate breakdown of their benefits.

Making enrollment easy

End-user selections

The Jellyvision Integration API also exposes certain choices made by end users during the ALEX experience including selected medical plan, dental plan, HSA contribution, and more.

Where coverage tiers apply, they are also made available via the API. In other words, whether the end user has chosen to only cover themselves, themself and a spouse, their entire family, etc.

Authentication

API Authentication

Establishing a connection

To authenticate with the Jellyvision Partner Integration API, two API keys are provided, one for each environment (see the Appendix for more information).

These API keys come in the form of a Bearer Token, specifically a signed JSON Web Token (JWT).

A POST request to the following URLs is necessary to obtain the API keys, depending on the environment you’re accessing:

• Pre-production: https://login.jellydevs.com/oauth/token
• Production: https://login.myalex.com/oauth/token

Jellyvision will assist if you are unsure which environment to access.

{
  "client_id": "<your-client-id-here>",
  "client_secret": "<your-secret-here>",
  "audience": "https://integrated-partner.myalex.com",
  "grant_type": "client_credentials"
}

Response example

{
  "access_token":"eyJz93a...k4laUWw",
  "token_type":"Bearer",
  "expires_in":86400
}

Example of a decoded JWT access_token (this is purely informational and not necessary to connect to the API)

{
  "iss": "https://login.myalex.com/",
  "sub": "<your-client-id-here>@clients",
  "aud": "https://integrated-partner.myalex.com",
  "exp": 1489715431,
  "iat": 1489679431,
  "scope": "rw:self"
}

Once you’ve obtained an access token, you are able to connect to the Jellyvision Integration Partner API.

Making an API request

The following headers must be included in every API request:

Guardrails

Without the following guardrails in place, Jellyvision cannot guarantee the performance of the ALEX experience:

1. Automatically request a new access token when the API call recieves a “401 Unauthorized” response
2. Request a new access token every 24 hours

If an access token is requested with each API call, rate limiting errors will occur.

Single sign-on (SSO)

Overview

The Jellyvision Integration API follows a standard SAML authentication flow. By default, it supports IdP-initiated SSO authentication.

SP-initiated authentication can be supported upon request and at Jellyvision’s discretion.

Authorization

The following is necessary for each environment (see Appendix for more details):

openssl genrsa -out test-partner.key 4096
openssl req -new -key test-partner.key -out test-partner.csr
openssl x509 -req -days 1825 -in test-partner.csr -signkey test-partner.key -out test-partner.crt

• x509 RSA-SHA256 signing certificate (a public key encoded in PEM or CER format generated from a 4096-bit private key)
• SAML Login URL

SAML attributes

End-users

Streamlining the end-user experience

Overview

The /api/partner/user endpoint allows for POST requests to populate or update user data. If a user does not exist with the provided partner-id, partner-user-id, and partner-client-id, the user will be created.

curl "http://example.com/api/partner/user"
  --request POST
  -d '{ "salary": 49500, "postalCode": "10002" }'
  -H "Authorization: meowmeowmeow"
  -H "Content-Type: application/json"
  -H "Partner-Id: test-partner"
  -H "Partner-Client-Id: test-client"
  -H "Partner-User-Id: a1b2c3f3b334abbafg332a3486bad"
  -H "Product-Key: 2025"

JSON Example:

{
  "salary": 49500,
  "postalCode": "10002",
}

Response:

{
  "userId": "string",
  "requestId": "string",
  "success": true,
  "warnings": null,
  "errors": null,
  "data": {
    "Global": {
      "moduleWhitelist": [],
      "language": 1,
      "salary": "49500",
      "zipCode": "10002",
      "EGInput": {
        "_108399": "_158518",
        "_0": "_130"
      }
    }
  }
}

The data object that is returned on a user call represents the ALEX data model and may be useful for troubleshooting. It does not need to be stored.

{
  "userId": "string",
  "requestId": "string",
  "success": true,
  "warnings": [
    {"salary": "provided value is not a number"},
    {"custom":
      [ {"ATR": "attr key ATR could not be mapped to known property"} ]
    }
  ],
  "errors": null,
  "data": {
    "Global": {
      "moduleWhitelist": [],
      "language": 1,
      "EGInput": {
        "_108299": "_158618"
      }
    }
  }
}

{
  "userId": null,
  "requestId": "string",
  "success": false,
  "warnings": null,
  "errors": ["provided client-id is unknown", "no user-id was provided"]
}

HTTP request

POST http://example.com/api/partner/user

Parameters

Please note that all parameters are optional. The user will be prompted to supply any information required to determine their eligibility for benefits or enable the product to provide benefits recommendations that are not included in the POST request. Similarly, any information that is not required to determine a user’s eligibility for benefits or enable the product to provide benefits recommendations will not be used. For example, if the benefits offered do not differ based upon their full-time status, full-time status does not need to be included in the POST request and, if it is, it will not be utilized within the product.

Most parameters that populate or update user data will be concealed and cannot be edited by users (see descriptions below).

Internal parameters

Internal parameters are universal. They follow strict validation guidelines and must be used as defined. See “Custom” parameters if unable to supply the following parameters in their defined format.

The following internal parameters are supported by default:

The following internal parameters can be supported upon request at Jellyvision’s discretion:

External parameters

External parameters can be supported upon request at Jellyvision’s discretion.

The purpose of external parameters is to provide insights that support organizational initiatives.

External parameters are defined by the Jellyvision Partner API but are validated against partner-supplied values. The type for these values is always a string and strict validation is not performed before mapping is attempted. For analytical purposes, please contact Jellyvision when providing this value.

Custom parameters

curl "http://example.com/api/partner/user"
  -X POST
  -d '{"custom" : {"DISC" : "OPTIN"}, "tobacco": true}'
  -H "Content-Type: application/json"
  -H "Authorization: meowmeowmeow"
  -H "Partner-Id: test-partner"
  -H "Partner-Client-Id: test-client"
  -H "Partner-User-Id: a1b2c3f3b334abbafg332a3486bad"
  -H "Product-Key: 2025"

Retrieving end-user data

Overview

The /api/partner/user/selections endpoint allows a partner to retrieve certain information about the the choices the user made in ALEX.

curl -k "https://example.com/api/partner/user/selections"
  --request GET
  -H "Authorization: Bearer [Base64EncodedKeyAndSecret]"
  -H "Content-Type: application/json"
  -H "Partner-Id: test-partner"
  -H "Partner-Client-Id: test-client"
  -H "Partner-User-Id: a1b2c3f3b334abbafg332a3486bad"
  -H "Product-Key: 2020"

Response:

{
  "userId": "a1b2c3f3b334abbafg332a3486bad",
  "requestId": "string",
  "success": true,
  "warnings": null,
  "errors": [],
  "plans": [{
    "name": "Gotham PPO 750",
    "alexCode": 32532,
    "partnerCode": ["P750"],
    "planType": "medical",
    "premiumTier": 30,
    "premiumTierDescription": "EE+Spouse",
    "waived": false
  },{
    "name": "Dental Plus 500",
    "alexCode": 65444,
    "partnerCode": ["DEN1", "DNT1", "NSP443"],
    "planType": "dental",
    "premiumTier": 10,
    "premiumTierDescription": "EE",
    "waived": false
  }],
  "contributions": [{
    "type": "hsa",
    "annualContribution": 1600
  }]
}

{
  "userId": null,
  "requestId": "string",
  "success": false,
  "warnings": null,
  "errors": ["Either this user does not exist or you are not authorized to retrieve data for this user"]
}

HTTP request

GET http://example.com/api/partner/user/selections

Parameters

Plans

Contributions

ALEX Sessions

Overview

What are ALEX Sessions?

Often, the word “session” can be interpreted ambiguously. The term “ALEX Session” has a specific meaning in our context. Each experience a user has with ALEX is managed via a session. In cases where eligibility or plan information will be supplied by the partner, the ALEX Session must first be populated before taking the user to ALEX.

What’s in an ALEX Session?

An ALEX Session has multiple purposes. The first and most obvious is to collect analytics information so that Jellyvision, our partners, and our customers understand how our users interact with ALEX. Sessions also contain information specific to the user’s interaction with ALEX. In the context of an integrated customer, the user’s eligibility information as well as user-specific plan details may be stored in an ALEX Session.

Since many factors calculated by a benefits election system may affect details, this allows per-visit control over the information displayed to a user. This allows the partner or customer to leverage elections or decisions made by the user during the benefits election process to display only the most relevant information.

Creating an ALEX Session

curl "http://example.com/api/partner/session"
  --request POST
  -d '{"see": ["example", "below"]}'
  -H "Content-Type: application/json"
  -H "Authorization: meowmeowmeow"
  -H "Partner-Id: test-partner"
  -H "Partner-Client-Id: test-client"
  -H "Partner-User-Id: a1b2c3f3b334abbafg332a3486bad"
  -H "Product-Key: 2020"

Payload example (Tiers are truncated for brevity. See the appendix for more examples)

 {
   "medical" :
   {
     "plans" : [
       {
         "partnerCode": "HMO2600",
         "premiumTiers": {
           "tierCoverageTypeId": 1,
           "10": 200.00,
           "20": 400.00
         },
         "healthfund": {
           "prorated": true,
           "employerContributionTiers": {
             "tierCoverageTypeId": 7,
             "10": 350.00
           }
         }
       },
       {
         "partnerCode": "PPO1500",
         "premiumTiers": {
           "tierCoverageTypeId": 1,
           "10": 100.00,
           "20": 200.00
         }
       }
     ],
     "deductionsPerYear": 26
   },
   "dental" : {
     "plans": [
       {
         "partnerCode": "HMO100",
         "premiumTiers": {
           "tierCoverageTypeId": 1,
           "10" : 140.45,
           "20" : 280.34
         }
       },
       {
         "partnerCode": "PPO50",
         "premiumTiers": {
           "tierCoverageTypeId": 1,
           "10" : 49.45,
           "20" : 80.34
         }
       }
     ],
     "deductionsPerYear": 24
   },
   "vision" : {
     "plans": [
       {
         "partnerCode": "VIS",
         "premiumTiers": {
           "tierCoverageTypeId": 1,
           "10" : 110.00,
           "20" : 150.52
         }
       }
     ],
     "deductionsPerYear": 24
   },
   "taxSavings" : {
     "plans": [
       {
         "partnerCodeFSA": "FSA25"
       },
       {
         "partnerCodeDCFSA": "DCFSA35"
       },
       {
         "partnerCodeCommuter": "COMMUTER"
       }
     ]
   }
 }

Response:

{
  "userId": "string",
  "newUser": false,
  "requestId": "string",
  "sessionId": "string",
  "success": true,
  "warnings": null,
  "errors": null
}

{
  "userId": "string",
  "requestId": "string",
  "success": false,
  "warnings": null,
  "errors": ["Either this customer does not exist or you are not authorized to create a session for this customer"]
}

HTTP request

POST http://example.com/api/partner/session

Parameters

Post body

The following denote top-level properties of a JSON body optionally posted to this endpoint. The benefit object is required if there are any plans configured for that benefit, even if the user is not eligible for any plans under that benefit. If medical/dental/vision/tax savings objects are omitted entirely from the payload, unintended consequences to a user’s eligibility for that benefit will result.

Object definitions

The following sections describe the top-level properties listed above.

Medical

Dental

Vision

Tax Savings

Healthfund

Tiers

Tiers are a an object with one to ten keys indicating dollars associated with a coverage tier. The same format is used for premiums and healthfund contributions. See the appendix for the list of tier codes.

Appendix

ALEX targets and environments

Overview

The integrated ALEX ecosystem comprises two environments, referred to as targets. The following chart describes the purpose of these targets.

Response format

HTTP 200

{
  "userId": "string",
  "requestId": "string",
  "success": true,
  "warnings": [
    {"salary": "provided value is not a number"}
  ],
  "errors": null
}

HTTP 401

{
  "userId": null,
  "requestId": "string",
  "success": false,
  "warnings": null,
  "errors": ["Unauthorized"]
}

HTTP codes

The following HTTP codes are used:

Warnings and errors

If the warning’s response value is populated with something other than “null”, it will be an array of issues the API had while attempting to process the request. The most common reason for this is that a provided value is invalid; for example, providing a string instead of a numeric value for the salary parameter. When warnings occur, the API will continue to process the request using any additional data it receives. The user will simply be prompted to answer a question unless the question has been previously answered either through successfully passing data through the API or because of a user’s previous session.

If the error’s value is populated in a response value, the API will halt and not proceed. No user data or plan data will be set or no user information will be returned. This indicates an unrecoverable error and Jellyvision will log these errors. The caller should implement user-friendly error handling for these cases.

Tiers

Common tier object examples

10 tiers

{
  "premiumTiers": {
    "tierCoverageTypeId": 6,
    "10": 67.50,
    "20": 135.00,
    "30": 135.00,
    "40": 202.50,
    "50": 270.00,
    "55": 337.50,
    "60": 202.50,
    "70": 270.00,
    "80": 337.50,
    "90": 405.00
  }
}

EE, EE + 1, EE + 2, Family

{
  "premiumTiers": {
    "tierCoverageTypeId": 2,
    "10": 67.50,
    "20": 135.00,
    "30": 202.50,
    "70": 270.00
  }
}

No Tiers (Flat Amount)

{
  "employerContributionTiers": {
    "tierCoverageTypeId": 7,
    "10": 500.00
  }
}

Overview

Tiers are utilized for premiums and employer healthfund contributions.

Below is a guide to the tiers that ALEX uses that a plan may be configured under. Submitting rates for all 10 tiers is recommended if possible, but plans configured with fewer tiers only require configured tiers to be submitted.

Tiers must always match one of the following configurations.

Tier names and tierCoverageTypeIds

Tier codes and descriptions