Seven Corners API Guide

Seven Corners API Guide

February 2017

Table of Contents

Seven Corners API Guide

February 2016

1.Getting Started

2.Seven Corners API Basics

2.2Request Format and Responses

2.3Status Codes

2.2Validations

2.3Validation Status

3.Seven Corners API Required Data

Request Body

3.1API Key

3.2Token Request Format

4.Sources and Descriptions

4.1Field Definitions

5.API Glossary

6.Products

GET api/v1/products/defaultpolicyformdefinition/{productGroupId}

Request Information

URI Parameters

Body Parameters

Response Information

Resource Description

Response Formats

6.1Products (Continued)

GET api/v1/products/policyformdefinition/{policyId}

Request Information

URI Parameters

Body Parameters

Response Information

Resource Description

Response Formats

7.Quote

POST api/v1/quote

Request Information:

URI Parameters

Body Parameters

Request Formats

application/json, text/json

application/xml, text/xml

application/x-www-form-urlencoded

Response Information

Resource Description

Response Formats

application/json, text/json

application/xml, text/xml

8.2 Quote (Continued)

POST api/v1/defaultbandsforpolicy

Request Information

URI Parameters

Body Parameters

Request Formats

application/json, text/json

application/xml, text/xml

application/x-www-form-urlencoded

Response Information

Resource Description

Response Formats

application/json, text/json

application/xml, text/xml

9.Purchase

POST api/v1/purchase

Request Information

URI Parameters

Body Parameters

Request Formats

application/json, text/json

application/xml, text/xml

application/x-www-form-urlencoded

Response Information

Resource Description

Response Formats

application/json, text/json, application/xml, text/xml

10.Fulfillment

GET api/v1/IdCard/{code}

Request Information

URI Parameters

Body Parameters

Response Information

Resource Description

Response Formats

10.1 Fulfillment (Continued)

GET api/v1/CoverageLetter/{code}

Request Information

URI Parameters

Body Parameters

Response Information

Resource Description

Response Formats

11.Public Document

GET api/PublicDocument?key={key}&associationType={associationType}

Request Information

URI Parameters

Body Parameters

Response Information

Resource Description

Response Formats

12.Agent

GET api/v1/agent/{policyId}

Request Information

URI Parameters

Type

integer

Body Parameters

Response Information

Resource Description

Response Formats

application/json, text/json

application/xml, text/xml

13.Products

GET api/v1/products/productgroups/{retailProductsOnly}

Request Information

URI Parameters

Body Parameters

Response Information

Resource Description

Response Formats

application/json, text/json

application/xml, text/xml

13.1 Products (Continued)

POST api/v1/products/FieldExclusionsCheck

Request Information

URI Parameters

Body Parameters

Request Formats

application/json, text/json

application/xml, text/xml

application/x-www-form-urlencoded

Response Information

Resource Description

Response Formats

1.Getting Started

If you are reading this manual then you have already:

Secured an API Key to access the Seven Corners API by contacting your Seven Corners Sales Rep and Program Management representative.

Your information has been validated and approved by the IT department allowing us to maintain compliance with state and federal regulations.

If you haven’t completed these steps you will not be able to access the API. Please contact your Seven Corners Sales Representative to get started.

2.Seven Corners API Basics

The Seven Corners ASP.NET Web API is a RESTful service and can be consumed on the Client or Server Side. Sevencorners.com consumes the API client side as and Angular.js app. Additionally, a RESTful API is an interface that uses HTTP requests to GET, PUT, POST and DELETE data. Requests are made using HTTP.

For nearly all operations, the submitted data, and the returned data structure, is defined within a JavaScript Object Notation (JSON) object. Basic information on the content and data types for JSON are provided in JSON Basics.

When accessing specific areas of the API, specific information and examples on the HTTP methods and request, JSON structures are provided.

2.2Request Format and Responses

The following HTTP request methods are supported:

• GET

Request the specified item. As with normal HTTP requests, the format of the URL defines what is returned. In most cases the information is returned in the form of a JSON document.

• HEAD

TheHEADmethod is used to get the HTTP header of aGETrequest without the body of the response.

• POST

Upload data. POSTis used to set values, including uploading documents, setting document values, and starting certain administration commands.

• PUT

Used to put a specified resource. PUTis used to create new objects, including databases, documents, views and design documents.

• DELETE

Deletes the specified resource, including documents, views, and design documents.

• COPY

A special method that can be used to copy documents and objects.

2.3Status Codes

Errors when accessing the API are reported using standard HTTP Status Codes as listed in the grid below.

2.2Validations

Validations are returned as validations on the response and are bubbled up from most specific to Validation for entire Quote. The Quote can be purchased when response validations are all valid and QuoteVersion is returned. QuoteVersion on Purchase Request must be the latest for the Quote.

2.3Validation Status

1 – Valid

2 – Warning (we can return a quote but this is not valid for purchase)

3 – Invalid (we cannot return a quote)

NOTE: The development team will be updating the statuses to return as text to improve the consumption of the API.

3.Seven Corners API Required Data

Thissectiondescribesthe datarequiredforcommunicatingsecurely withtheAPI.

**Instead of a Username and password to use as authentication credentials, you will need to submit a request via the Seven Corners Program Manager for an API key for your domain.

Request Body

3.1API Key

The API Key is unique for Agent and Domain combination. The agent associated with the API key used is credited the sale. The api_keymust be sent with all client requests. The api_key helps the server to validate the request source.

client_id=88EA34EB-229F-4DDC-9E52-5C797673A015&grant_type=client_credentials

[env].api.sevencorners.com/token. NOTE: This subdomain is not used for production.

**Note – for all other requests to the API the following header will need to be added:

Authorization: Bearer [returned token]

Origin: http:demo.com

3.2Token Request Format

To authenticate to the API a token must be used through the URL provided in the HOST section below.

Host: dev.api.sevencorners.com

Connection: keep-alive

Content-Length: 76

Cache-Control: no-cache

Origin: chrome-extension://aicmkgpgakddgnaphhhpliifpcfhicfo

Content-Type: application/x-www-form-urlencoded

User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/48.0.2564.97 Safari/537.36

Postman-Token: d01fc955-44f5-4ddc-1de5-abd1653e5b1b

Accept: */*

Accept-Encoding: gzip, deflate

Accept-Language: en-US,en;q=0.8

Cookie: __lc.visitor_id.5655821=S1452259500.0c88c4bf8f; _ceir=1; _ga=GA1.2.1024155766.1452262061

4.Sources and Descriptions

Sources

4.1Field Definitions

The field definitions identify which fields are required and if they are policy selection affecting, rate affecting, trigger exclusions, or have dependent fields (number of days for Collision Damage Waiver on one of the Roundtrip plans).

5.API Glossary

API

"API" is an acronym for Application Programming Interface. It is a name used to refer to a special framework some web applications or services provide which allows a user to connect to the system and perform some number of discrete actions such as running functions, requesting data, or updating information.

Action

An "action" is the part of an API's URL "anatomy" that describes or names a function that is available for a user to invoke. The action comes after the endpoint such than a typical API request URL might look like:Enter Hyperlink

Call

A "call" is another name for a "request" or a communication sent by a user to the API, in the form of a URL string, which invokes a specific action on one particular endpoint, and may also include additional parameters or values.

DELETE

"DELETE" is one of the four HTTP "methods", typically used for removing records from a system.

Encryption

"Encryption" is the act of converting of obfuscating the original representation of something using an algorithm or sequence of steps that change the representation into something else entirely. Encryption may be one-way (meaning that once applied, it cannot be undone) or two-way (meaning that once applied, it can be undone).

Endpoint

An "endpoint" is the part of an API's URL "anatomy" that describes or names the domain of objects or functions that can be manipulated or invoked by calling specific actions available under the endpoint.The endpoint comes after the host value such than a typical API request URL might look like Enter Hyperlink

GET

"GET" is one of the four HTTP "methods", typically used for retrieving or querying records from a system.

Hash

A "hash" is a single value (i.e., string, number, etc.) or potentially a combined/concatenated set of values that have been encrypted.

HTTP

"HTTP" is an acronym for hyper-text transport protocol. It is one of the key architectural components behind how web-based content on the internet is accessed through web browsers.

HTTPS

"HTTPS" is an acronym for hyper-text transport protocol secure. It is the same in principle and function as HTTP, but exists when data transmitted via HTTP is encrypted before it is sent between two communicating entities (i.e., a user requesting information from a web server).

JSON

"JSON" is an acronym for JavaScript Object Notation. It is a format for information, based on the JavaScript language, that is intended for consumption by a programmed function.

Method

HTTP provides support for four "methods" which each describe a type of result a user might want to achieve through a given communication with a web server or API. The four methods are:"GET" (for retrieving data), "PUT" (for inserting data), "POST" (for updating data), and "DELETE" (for removing data).

Parameter

A "parameter" is like a variable added to an API request that provides additional information, instruction, or the necessary value the target action is supposed to utilize. Parameters come after the action value such than a typical API request URL might look like:Enter Hyperlink

POST

"POST" is one of the four HTTP "methods", typically used for updating existing records in a system.

Public / Private Key Encryption

Public / private key encryption is a form of encryption whereby a value (i.e., string, number, record of information, etc.) someone wishes to allow others to prove the authenticity of (i.e., proving it came from the original person) is encrypted using a one-way hashing algorithm. This hash is created using a non-secret value (the public key) as well as a second secret value (the private key) which is known only to the party encrypting the information and given to any party who wishes to validate the authenticity of the information. The receiving party will get a copy of the original data and the public key. If this party also knows the private key, they will be able to re-create the hash value thereby proving it is authentic.

PUT

"PUT" is one of the four HTTP "methods", typically used for inserting or creating records into a system.

Resource

A "resource" is a name for the combination of an "endpoint" and "action" in an API's URL "anatomy". A resource would refer to the values that come after the host in this example:Enter Hyperlink

Response

A "response" is the data that an API sends back to a user after it is called. The format of an API response is usually XML or JSON.

REST

"REST" is an acronym for Representational State Transfer. It is a form of software architecture that is primarily used for web service design. The World Wide Web (WWW) is itself based on REST.

Request

A "request" is the callor a communication sent by a user to the API, in the form of a URL string, which invokes a specific action on one particular endpoint, and may also include additional parameters or values.

SOAP

"SOAP" is an acronym for Simple Object Access Protocol. It is a form of software architecture used for web service design, like REST.

URL

"URL" is an acronym for Uniform Resource Locator. The URL is the unique address for any object or function that can be accessed or invoked on the web.

Web Service

Web Service is a more generic name than API for referring to a special framework some web applications provide which allows a user to connect to the system and perform some number of discrete actions such as running functions, requesting data, or updating information.

XML

"XML" stands for Extensible Markup Language.It is a language used for providing information as well as describing that information, such that programs can interpret data without really understanding the data itself.

Methods

NOTE: All hyperlinks in the sections going forward will deliver the user to the intended help section within the API/Help URL.

6.Products

Method

GET api/v1/products/defaultpolicyformdefinition/{productGroupId}

Request Information

URI Parameters

Body Parameters

None.

Response Information

Resource Description

FormDefinition

Response Formats

Sample not available.

6.1Products (Continued)

Method

GET api/v1/products/policyformdefinition/{policyId}

Request Information

URI Parameters

Body Parameters

None.

Response Information

Resource Description

FormDefinition

Response Formats

Sample not available.

7.Quote

Note: The Quote can be purchased when response validations are all valid and QuoteVersion is returned. QuoteVersion on Purchase Request must be the latest for the Quote.

Method

POST api/v1/quote

Request Information:

Person

PersonIdentifier – this must be unique per person per quote, and is used to tie per person fields to the person

QuoteRequestCount -This is option allows client to know the order request were sent in for asynchronous operation

QuoteIdentifier - Initial request will be sent without this and it will be provided on the response to be used for subsequent requests to update this quote

URI Parameters

None.

Body Parameters

QuoteRequest

Request Formats

application/json, text/json

Sample:

{

"quoteIdentifier": "c83725e3-23ce-428e-a365-3be44fac65f8",

"quoteRequestCount": 1,

"policyQuoteRequests": [

{

"policyId": 1,

"productGroupId": 1,

"effectiveDate": "2016-02-09T10:06:48.6157929-05:00",

"expirationDate": "2016-02-09T10:06:48.6157929-05:00",

"fields": [

{

"code": "sample string 1",