Using the Envisage Global Insurance API – Part 1- Accessing the System

About Envisage Global Insurance

Envisage Global Insurance is a specialized international group insurance broker who has been providing international health and travel insurance plans for the cultural exchange and youth travel market for well over 10 years. Whether coverage is needed for a small group with 5 or more participants, or you would like to custom build your own insurance plan for thousands of members, EGI provides the tools to manage this quickly and effectively online. Group administrators can enroll and update members in real time with immediate availability of updated ID cards, as well as cancel enrollment or verify coverage on demand.

EGI Plan Admin Tool

About the Envisage Global Insurance API

The EnvisageGlobalInsurance.com API is provided as a means of automating the basic administrative tasks for an EGI Plan Administrator by providing an interface between our clients’ systems and the online administrative tool. By integrating the API, group administrators can use their in-house software to manage enrollments directly.

This blog post is the first in a series designed to help EGI client systems establish their integration into the EnvisageGlobalInsurance.com system.  For reference, full documentation of the API, including samples, can be found here: http://www.envisageglobalinsurance.com/admin/APIDocumentation.html

The EGI API is primarily a RESTful one, but does require POST authentication for all requests. For that reason, we recommend building your requests via cURL All submitted information must be sent as key-value pairs via POST data while all responses are returned as JSON objects with success and status codes.

Establishing your Credentials

When you first request access to the system via your EGI account representative, a new administrative user will be added to your account and given API credentials.  To access the API from this point forward, the interface that is using the API will need to submit the user and key values provided in that email as part of the posted data.

If you are using PHP and cURL, your post fields should look something like this, at a minimum:

$query = http_build_query([
            'user' => 'yourname@yourcompany.com',
            'key' => '1111111111111111111111111111111111',
    ]);

The initial user added for testing will be created on the primary EGI system, but will be restricted in scope to managing participants on the API Test Plan. Once your testing is complete, there are several options for final implementation, depending on the needs of the client system. The simplest option is to request that the existing API user be granted administrative rights to all of the plans that the group’s software is to manage. Alternately, if the group’s software is capable of tracking the information on a per-user basis, each administrator can be granted an API key which will grant access only to the plans which they are specifically assigned to.  Our technical team will work with you to find a solution that works best for your system.

Common Access Related Errors – Status 403

“No user specified”

The ‘no user specified’ error message is returned with a status 403 when the “user” key-value pair is missing from the posted data.

 

“No API key specified”

The ‘No API key specified’ error message is returned with a status 403 when the “key” key-value pair is missing from the posted data.

 

“Invalid user name”

If you receive the above error, it indicates that the username provided is not currently valid in the system. Please verify your credentials or contact your account representative to ensure that you are submitting the proper information.

 

“Your API Key is not valid”

If you receive the above error, it indicates that the user and key combination submitted is not able to be authenticated against the account specified. If this occurs, please verify that you are using the correct username and API key values. If you are unsure, contact your EGI account representative.

 

“You are not authorized to make updates to this plan”

If you receive the above error, it indicates that you are attempting to make an update to a plan that the current API user has not been granted permission to edit. By default, the only plan accessible during testing is the “API Test Plan”

The Envisage Global Insurance API can be a great way to add efficiency to your group management systems. If you have questions about how to integrate it or about the capabilities of the API, please talk to an account representative, and we’ll be happy to assist.  In upcoming months, we will continue this series with tips on how to post new participants to a plan and other useful information.

 

This entry was posted in Technical Talk and tagged , , . Bookmark the permalink.

Leave a Reply

Your email address will not be published. Required fields are marked *