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.
Status Code / Description200 / OK
201 / Created
202 / Accepted (Request accepted, and queued for execution)
400 / Bad request
401 / Authentication failure
403 / Forbidden
404 / Resource not found
405 / Method Not Allowed
409 / Conflict
412 / Precondition Failed
413 / Request Entity Too Large
500 / Internal Server Error
501 / Not Implemented
503 / Service Unavailable
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
Name / DescriptionClient_id / Guid API Key set for Agent and domain combination
Grant_type / Client_credentials
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
Name / DescriptionToken / Authorization Endpoint returns bearer token to be used in subsequent calls.
Default Policy Form definition{ProductGroupID} / Endpoint for Form Definition by product, this uses a default policy under the product to get settings
Policyformdefinition{PolicyID} / Endpoint for Form Definition by policy, this can differ from the default for the product group due to state/underwriter restrictions
Quote / Request a quote. Multiple levels of validation. A fully valid quote can be purchased
Purchase / Endpoint to purchase an existing Quote
Idcard / Endpoint used for retrieving Id Card from link in purchase response
Coverageletter / Endpoint used for retrieving Coverage Letter from link in purchase response
Publicdocument / Endpoint for retrieving plan documents, parameters come from Form Definition
Agent / Returns Agent information as stored in Seven Corners System
Productgroups{retailProductsOnly} / List of Current Active Products Agent is configured to sell
Fieldexclusionscheck / End point that will check field exclusions and return information about violations
Default Bands For Policy / Provides default bands for a policy so that a quote can be created with default selections for the customer.
Allcountries / List of Countries
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
Name / DescriptionDefaultPolicyFormDefinition(GET) / Endpoint for Form Definition by product, this uses a default policy under the product to get settings
GET api/v1/products/defaultpolicyformdefinition/{productGroupId}
Request Information
URI Parameters
Name / Description / Type / Additional informationproductGroupId / integer / Required
Body Parameters
None.
Response Information
Resource Description
FormDefinition
Name / Description / Type / Additional informationEffectiveDateFieldDefinition / Definition / None.
ExpirationDateFieldDefinition / Definition / None.
DisclaimerText / string / None.
UnderwrittenBy / string / None.
HideRequestSendPromotionalMaterials / boolean / None.
IsAgentConfiguredToSellPolicy / boolean / None.
PersonDefinitions / Collection ofPersonDefinition / None.
QuoteFieldDefinitions / Collection ofFieldDefinition / None.
PersonFieldDefinitions / Collection ofFieldDefinition / None.
FieldExclusions / Collection ofFieldExclusion / None.
FieldTriggers / Collection ofFieldTrigger / None.
RequiredAddresses / Collection ofAddressDefinition / None.
ExcludedCountries / Collection ofOption / None.
PhoneTypes / Collection ofOption / None.
ReferenceDocuments / Collection ofDocumentInfo / None.
Response Formats
Sample not available.
6.1Products (Continued)
Method
Name / DescriptionPolicyFormDefinition(GET) / Endpoint for Form Definition by policy, this can differ from the default for the product group due to state/underwriter restrictions
GET api/v1/products/policyformdefinition/{policyId}
Request Information
URI Parameters
Name / Description / Type / Additional informationpolicyId / integer / Required
Body Parameters
None.
Response Information
Resource Description
FormDefinition
Name / Description / Type / Additional informationEffectiveDateFieldDefinition / Definition / None.
ExpirationDateFieldDefinition / Definition / None.
DisclaimerText / string / None.
UnderwrittenBy / string / None.
HideRequestSendPromotionalMaterials / boolean / None.
IsAgentConfiguredToSellPolicy / boolean / None.
PersonDefinitions / Collection ofPersonDefinition / None.
QuoteFieldDefinitions / Collection ofFieldDefinition / None.
PersonFieldDefinitions / Collection ofFieldDefinition / None.
FieldExclusions / Collection ofFieldExclusion / None.
FieldTriggers / Collection ofFieldTrigger / None.
RequiredAddresses / Collection ofAddressDefinition / None.
ExcludedCountries / Collection ofOption / None.
PhoneTypes / Collection ofOption / None.
ReferenceDocuments / Collection ofDocumentInfo / None.
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
Name / DescriptionQuote(POST) / Request a quote. Multiple levels of validation. A fully valid quote can be purchased
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
Name / Description / Type / Additional informationQuoteIdentifier / globally unique identifier / None.
QuoteRequestCount / integer / None.
PolicyQuoteRequests / Collection ofPolicyQuoteRequest / None.
Persons / Collection ofPerson / None.
PrimaryMemberAddresses / Collection ofAddress / None.
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",