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
