BCI BRIDGES PEOPLE

AND

TECHNOLOGY.

YOU

LL

SEE

B-CONNECTED INTEGRATION GUIDE

Version 3.0

Contents
Section 1: B-Connected Integration ............................................................................................................ 3
Audience ................................................................................................................................................... 3
Overview ................................................................................................................................................... 3
Usage and Integration on the Partner's Website ................................................................................... 4
Section 2: Security ....................................................................................................................................... 6
Public Certificate ...................................................................................................................................... 6
Attribute Definitions MetaData.xml ..................................................................................................... 6
Endpoint URI's UAT and Production..................................................................................................... 6
UAT URI ................................................................................................................................................. 6
Production URI ..................................................................................................................................... 6
Section 3: B-Connected API ......................................................................................................................... 7
Audience ................................................................................................................................................... 7
Overview ................................................................................................................................................... 7
Endpoints and URI Formats .................................................................................................................... 8
Operations .................................................................................................................................................... 8
InitEnrollment ............................................................................................ Error! Bookmark not defined.
Demographic ............................................................................................................................................ 9
Layout Demographic Data................................................................................................................ 9
Layout Dependent Data ................................................................................................................ 12
Sample JSON Request (POST Data) .................................................................................................... 13
GetBenefit ..................................................................................................... Error! Bookmark not defined.
Sample GetBenefit SAML Assertion (POST Data) ................................... Error! Bookmark not defined.
BenefitConfirmations ................................................................................................................................ 15
FinishEnrollment ........................................................................................... Error! Bookmark not defined.
Appendix A ................................................................................................................................................. 16

2
Benefit Communications Inc. Proprietary and Confidential

Section 1: B-Connected Integration

Audience
This document is intended for partners who integrate the B-Connected application into their system.
This document assumes that the audience is aware of the terminology associated with basic HTML
web pages such as <iframe> and basic JavaScript.

Overview
The B-Connected uses BCI's B-Connected API that provides supplemental benefit enrollments in realtime based on employee eligibility and plan offerings.
The B-Connected service can be plugged in on the partner's website and provides customers with a
seamless end-to-end enrollment experience.

3
Benefit Communications Inc. Proprietary and Confidential

Usage and Integration on the Partner's Website

The B-Connected widget can be integrated on the partner's system in the form of an <iframe>
pointing to B-Connected's implementation for the supplemental benefits:

<iframe id='BciFrame' />

A reference to BCI's JavaScript file will be required in the <head> tag:
<script src="https://www.electbenefits.com/ESS/bciapi.js" type="text/javascript"></script>
Three JavaScript functions will be required in the <head> tag:
<script>
function onBciStart() {
document.getElementById('[button id on partner system]').disabled = true;
}
function onBciFailure() {
document.getElementById('[button id on partner system]').disabled = false;
}
function onBciSuccess() {
document.getElementById('[button id on partner system]').disabled = false;
}
</script>
A full HTML page example using the JavaScript functions and calling those functions from a button
on the page is below.
<!DOCTYPE html>
<html>
<head>
<title>Customer's Site</title>
<!-- BCI'S PROPRIETARY ENROLLMENT SCRIPT -->
<script src="https://www.electbenefits.com/ESS/bciapi.js" type="text/javascript"></script>
4
Benefit Communications Inc. Proprietary and Confidential

<!-- CUSTOMER-SPECIFIC CODE TO CUSTOMIZE UI EXPERIENCE -->

<script>
function onBciStart() {
document.getElementById('btnEnrollment').disabled = true;
}
function onBciFailure() {
document.getElementById('btnEnrollment').disabled = false;
}
function onBciSuccess() {
document.getElementById('btnEnrollment').disabled = false;
}
</script>
</head>
<body>
<!-- CUSTOM UI BUTTON FOR INITIATING ENROLLMENT -->
<button id='btnEnrollment' onclick='BciInit(onBciStart,onBciFailure,onBciSuccess);'>Enroll for
Benefits</button>
<br />
<!-- IFRAME FOR CONTENT FROM BCI -->
<iframe id='BciFrame' />
</body>
</html>

5
Benefit Communications Inc. Proprietary and Confidential

Section 2: Security
The B-Connected service uses SAML 2.0 as its initial authentication. In order to access the service
the client must use an assertion with some specific attributes mentioned below. The SAML must be
authenticated using the certificate file (.cer) from where the user is coming from.
The .cer file must be generated from the web server where the host system resides. BCI will need
this file in order for the SSO (Single Sign-On) process to work.

Public Certificate
BCI's public certificate is included in the MetaData.xml file provided as part of this guide. The .cer file
is also provided for convenience. This will be the certificate that will be needed to decrypt the SAML
Response and/or the SAML Assertion.
A SAML 2.0 Assertion is required with the following attributes to the URI's below in order to begin the
process. The ClientID will be assigned by BCI.

Attribute Definitions MetaData.xml

File
Field
Position

File Field Name

Description

Required/
Optional

Data Type

Special Note

ClientID

Client's Unique ID

Alpha (70)

Assigned by BCI

Endpoint URI's UAT and Production

UAT URI
https://dashboard.electbenefits.com/SSOTestBed/ESS/sso/<client>/AssertionService.aspx

Production URI
https://www.electbenefits.com/ESS/sso/<client>/AssertionService.aspx

6
Benefit Communications Inc. Proprietary and Confidential

Section 3: B-Connected API

Audience
This document is intended for programmers that consume the B-Connected API. This reference guide
provides examples of the API operation accessible using REST protocol with JSON request and
response.

Overview
BCI offers a REST API that provides the eligibility and plan information for supplemental benefits.
Since BCI's B-Connected API is a REST API based on open standards, you can use any web
development language to access the API.

Security

The B-Connected API, uses tokens as its authentication. In order to obtain the {apiToken}, which is
used in each API call, the user must first obtain a token through the hidden API call GET
https://api3.electbenefits.com/api/v1/Tokens/{Username}/{Password} This call will return an {apiToken}
that will be valid for a 48 hour period. A new token can be obtained at any time using this method.
Usernames and Passwords can be obtained by contacting BCI.

Sample JSON Response

[
{
"Token": " 138,217,24,220,179,48,50,116,35,172,162,162,157,32,122",
"Message": "Token has been issued for 48 hours!"
}
]

7
Benefit Communications Inc. Proprietary and Confidential

Endpoints and URI Formats

The B-Connected API provides access to resources via URI paths. The API uses JSON as the
communication format and hence, to use the API, your application has to make an HTTP request over
SSL, in JSON format and parse the JSON response.
Endpoint URIs for B-Connected's API will have the following format:
https://api3.electbenefits.com/api/v1
POST Demographics/{apiToken}
POST Benefits/{token}
GET BenefitConfirmations/{id}/{apiToken}
GET BenefitConfirmations/{clientid}/{apiToken}
GET BenefitConfirmations/{id}/{benid}/{apiToken}

Operations

API requests are standard HTTP POST and GET requests.

Acceptable request representations: application/json and application/xml
Available response representations: application/json and application/xml

8
Benefit Communications Inc. Proprietary and Confidential

Demographic
The Demographics API call is responsible for sending B-Connected the employee and dependent
demographic data. There is one parameter that is required to be passed into this API called
{apiToken}.
The employee and dependent demographic information will be sent, In the body, to the API via HTTP
POST. The dependent(s) are nested within the employee response. Each dependent will be listed one
after the other. The employee and dependent demographic layouts are below with their coinciding
JSON Requests.
The {apiToken} is a unique GUID assigned to the host and will not change for 48 hours.

Layout Demographic Data

File
Field
Position

File Field Name

Description

Required/
Optional

Data Type

EEID

Employee ID

Alpha (20)

SSN

Employee Social
Security #

Alpha (11)

FirstName

First Name

Alpha (50)

MiddleName

Middle Name/Initial

Alpha (50)

LastName

Last Name

Alpha (50)

DOB

Date of Birth

Date (10)

Gender

Male, Female (M/F)

Alpha (6)

Address1

Employee Address1

Alpha (50)

Address2

Employee Address2

Alpha (50)

10

City

Employee City

Alpha (50)

9
Benefit Communications Inc. Proprietary and Confidential

Special Note

no dashes

MM/DD/YYYY

If available

File
Field
Position

File Field Name

Description

Required/
Optional

Data Type

11

State

Employee State

Alpha (2)

12

Zip

Employee Zip

Alpha (10)

13

Email1

Employee E-Mail (work

or personal)

Alpha (128)

if available

14

HomePhone

Employee Home
Phone #

Alpha (15)

if available

15

DepartmentCode

Employee Dept Code

Alpha (20)

16

DepartmentDesc

Employee Dept
Description/Name

Alpha (50)

17

LocationCode

Employee Location
Code

Alpha (20)

18

LocationDesc

Employee Location
Description

Alpha (50)

19

JobCode

Job Code

Alpha (20)

20

JobDesc

Job Description

Alpha (50)

21

FTPT

Full Time/Part Time

Status (FT/PT)

Alpha (10)

22

PayFreq

12, 24, 26, 52

Alpha (10)

23

SalaryClass

Hourly or Salary

Alpha (10)

24

Exempt

Exempt Status (Yes /

No / Exempt /
NonExempt)

Alpha (10)

25

DOH

Date of Hire (most

recent date of hire)

Date (10)

10
Benefit Communications Inc. Proprietary and Confidential

Special Note

MM/DD/YYYY (need date to

base benefit eligibility from)

File
Field
Position

File Field Name

Description

Required/
Optional

Data Type

Special Note

26

AnnualSal

Annual Salary (Benefit

Salary)

Decimal
(15)

per pay amount and

scheduled hours also
acceptable

27

Dependents

Dependent Object
defined below

OBJECT

11
Benefit Communications Inc. Proprietary and Confidential

Layout Dependent Data

File
Field
Position

File Field Name

Description

Required/
Optional

Data Type

Special Note

SSN

Employee's SSN

Alpha (11)

no dashes

DepID

Dependent ID

Alpha (20)

Client system unique

dependent identifier

Fname

Dependent First Name

Alpha (50)

Mname

Dependent Middle
Name/Initial

Alpha (50)

Lname

Dependent Last Name

Alpha (50)

DOB

Dependent Date of Birth

Date (10)

Yyyymmdd

dpSSN

Dependent SSN

Alpha (11)

if available

Relationship

Relation to EE
(Spouse/Child/Beneficia
ry)

Alpha (20)

Gender

Male/Female (M/F)

Alpha (10)

10

Student

Student Status for

Overage Dependents
(Y/N)

Alpha (1)

if available

11

Disabled

Disabled (Y/N)

Alpha (1)

if available

12

dpSmoker

Dependent Smoker
Status (Y/N)

Alpha (1)

required for dependent level

smoker rates

12
Benefit Communications Inc. Proprietary and Confidential

Sample JSON Request (POST Data)

{
"EEID":"125874587",
"SSN":"123456789",
"FirstName":"Test",
"MiddleName":"",
"LastName":"Employee",
"DOB":"19790727",
"Gender":"M",
"Address1":"123 anywhere",
"Address2":"",
"City":"Itta Bena",
"State":"MS",
"Zip":"38941",
"Email1":test@test.com,
"HomePhone":"1254874580",
"DepartmentCode":"",
"DepartmentDesc":"",
"LocationCode":"",
"LocationDesc":"",
"JobCode":"",
"JobDesc":"attorney",
"FTPT":"FT",
"PayFreq":"26",
"SalaryClass":"S",
"Exempt":"N",
"DOH":"06/1/2001",
"AnnualSal":"25000",
"Dependents":[{
"SSN":"123456789",
"DepID":"234567898-001",
"FName":"Test".
"MName":"",
"LName":"Employee",
"DOB":"07/27/1979",
"dpSSN":"455454544",
"Relationship":"Spouse",
"Gender":"F",
"Student":"N",
"Disabled":"N",
"dpSmoker":"N"
}],
{apiToken}
}

13
Benefit Communications Inc. Proprietary and Confidential

Benefits
The Benefits API is used to pass benefit information directly through the API. There is one parameter
that is required to be passed into this API called {apiToken}.
The benefit information will be passed, in the body, to the API via HTTP POST. There can be multiple
benefits passed into the API.
The {apiToken} is a unique GUID assigned to the host and will not change for 48 hours.

Layout Benefits Data

File
Field
Position

File Field Name

Description

SSN

Employee's SSN

Alpha (11)

no dashes

BenID

Benefit ID

Alpha (20)

See chart in Appendix A for

benefit id legend

BenDeduction

Benefit Per Pay Period

Deduction

Alpha (20)

TotalBenAmount

Total Benefit Amount

Requested

Alpha (30)

InforceBenAmou
nt

Benefit Amount inforce

Alpha (30)

BenEffDate

Benefit Effective Date

Date (10)

Required/
Optional

Data Type

Sample JSON Request (POST Data)

{
"SSN":"123456789",
"benefitObject": {
"BenID":"LIF",
"BenDeduction":"12.84",
"TotalBenAmount":"200000",
"InforceBenAmount":"100000",
"BenEffDate":"20150101"
},
{apiToken}
}

14
Benefit Communications Inc. Proprietary and Confidential

Special Note

yyyymmdd

BenefitConfirmations
The BenefitConfirmations API call has three versions. One is used to pull all benefit information back
for a person. There are parameters that are required to be passed into this API called {id}, and
{apiToken}.
The {id} parameter maps to the employee SSN. The {apiToken} is a unique GUID assigned to the
host and will not change for 48 hours.
The second version is used to pull all benefit information back for an entire client. There are
parameters that are required to be passed into this API called {clientid}, and {apiToken}.
The {clientid} parameter maps to a BCI defined client ID. The {apiToken} is a unique GUID assigned to
the host and will not change for 48 hours.
The third version is used to pull back benefit information for a particular person and for a particular
benefit. There are three parameters that are required to be passed into this version of the API called
{id}, {benid}, and {apiToken}.
The {id} parameter maps to the employee SSN and the {benid} parameter maps to a unique BCI
defined benefit code. See Appendix A for a chart defining the benefit parameters. The {apiToken} is a
unique GUID assigned to the host and will not change for 48 hours.

15
Benefit Communications Inc. Proprietary and Confidential

Appendix A
Benefit

Parameter

Accident

ACC

Critical Illness

CI

Whole Life

WLIFE

STD worksite

STD

Hospital Indemnity

GHI

Employee Life

LIF

Spouse Life

SLF

Child Life

CLF

STD - voluntary

VSTD

LTD voluntary

VLTD

16
Benefit Communications Inc. Proprietary and Confidential