API Specification

API Version: 5.1.1


Table of Contents

1 Introduction

1.1 General Architecture

1.2 Supported HTTP methods

1.2.1 HTTP Status Codes

2 Using the API

2.1 Security Overview

2.2 Authorization Access

2.2.1 Username and Password

2.2.2 Token Access

2.3 Calling the API

2.3.1 Using Simple Authentication

2.3.2 Using Token Access

3 API Input/Output

3.1 Output

3.2 Input

3.2.1 Query String

3.2.2 Form Values

3.2.3 HTTP Headers

3.3 Get/Set Operations

3.3.1 GET

3.3.2 SET

4 API End-Points

4.1 Schemes

4.1.1 Get

Parameters

Example Result XML

Example Result JSON

Summary

4.2 Cases

4.2.1 Get

Parameters

Example Result XML

Example Result JSON

Summary

4.2.2 Set

Parameters

XML Request Example

JSON Request Example

4.2.3 Correctly formatting your AddCase XML or JSON resource

4.2.4 Case Payment Details

Account Name

Account Number

Sort Code

BIC Reference

IBAN Reference

Collection Amount

Date of First Collection

Payment Method

Payment Method ID

Payment Frequency ID

4.2.5 Payment Method Information Table

Payment Information Examples

Payment Example XML

Payment Example JSON

Results

4.3 Statistics

4.3.1 Statistics Resource

4.3.2 Get

Example result

4.4 Endorsements

4.4.1 Endorsements Resource

4.4.2 Get

Parameters

Example Result XML

Example Result JSON

4.4.3 Set

Parameters

Results

Success

Failure

4.5 Reports

4.5.1 Reports Resource

4.5.2 GET

Parameters

Reportid

Report Type

5 Example Code

5.1 PHP

5.1.1 Getting the Access Token

5.1.2 Adding a Case

5.2 .NET

6 Troubleshooting

6.1.1 The API returns “The input is not a valid Base-64 string”

6.1.2 The server responds with Bad Format Exception when trying to add a case

6.1.3 I’m getting “Curl error: SSL certificate problem” when trying to access the API through my local PHP client

6.1.4 I’ve successfully added a case with an XML resource, but can’t manage the get the JSON working

6.2.1 Testing with a RESTful Client


1 Introduction

This document provides a full specification for the SchemeServe’s public API.

1.1 General Architecture

The SchemeServe API is a REST-based service which uses both the BASIC and OPENAUTH2 security protocols for user authentication.

What is REST: http://code.tutsplus.com/tutorials/a-beginners-introduction-to-http-and-rest--net-16340

What is OAuth:

http://en.wikipedia.org/wiki/OAuth

1.2 Supported HTTP methods

The following HTTP verbs are currently supported

1.2.1 HTTP Status Codes

The information that returns will contain a HTTP STATUS code along with any valid information requested depending on the call.  For example:

It is the responsibility of the system calling the API to check and appropriately respond to the information returned from every API call.


2 Using the API

2.1 Security Overview

The API uses Basic Authentication and OpenAuth2 to implement security. This allows us to distinguish between operations that do not have to be totally secure, and operations that need complete authorization and appropriate authority.

There are two types of access to the SchemeServe API; authorization access and token access

2.2 Authorization Access

Authorization access is the lowest authorization tier. Using it, only a limited set of operations are available from the API through standard username and password. Very few operations will allow modifications when using this type of access, most of them will involve calls that return information only.

2.2.1 Username and Password

The username and password referred here is the username and password identified by the schemeserve web application.  Within the role/permission group of users within schemeserve, the following roles/permissions of users have access to the API:

  1. Administrators
  2. AdmSuperUsers
  3. ADM_Administrators
  4. PowerUsers
  5. APIUsers

The APIUsers role enables access to the API system only. The other roles specified here give specific access to the SchemeServe web application in addition to the API itself.

Important

It is the responsibility of the API User to ensure that all passwords passed into the system are secured when calling the API. While the API will accept cleartype passwords, the number of operations for this type of access is very small, and none will alter the system in any way.

Note

A special API account is issued for each client individually. Normal account *can not* be used for accessing the API.

2.2.2 Token Access

Token access is the highest authorization tier and gives access to every operation on the API.

Once requested, the token will consist of an an expiration date, meaning that the token has to be checked for validity first before being used. This type of access uses the openauth2 protocol.

2.3 Calling the API

The API can be found at the following URL:


https://slipstream.schemeserve.com/api/

which will be used for all calls to the API.

To call it you must have a valid schemeserve account with the appropriate API access. Most of the schemeserve accounts with admin access to schemes will have access to the api by default.  

Note

For all API references in this document we’ll be using the slipstream demo account. Each SchemeServe client has their own account and in a real case scenario slipstream will be replaced with it in all API calls.

2.3.1 Using Simple Authentication

To retrieve information using Authorization Access:

  1. Make a call to https://slipstream.schemeserve.com/api/<<Operation>>*
  2. Add the following http headers when making the call:
  1. UserID: <<The username of the account making the call>>
  2. Authorization: <<The password of the account making the call>>

cURL example - requesting a token:

C:\SchemeServe>curl https://slipstream.schemeserve.com/api/token/ApiDemoAccess/4Dp42lsk83

Note: The UserID and Authorization parameters can be passed either through the HTTP headers or through a normal query string.

If the call is correct, then an http status code of 200 (or 201) will be returned.  Otherwise an alternative http status code will be returned which indicates an issue with the API call. No operation that inserts or modifies data will be allowed using authorization access.

More: http://en.wikipedia.org/wiki/List_of_HTTP_status_codes

2.3.2 Using Token Access

To retrieve information using token access, a token must be retrieved first:

  1. Make a call to https://slipstream.schemeserve.com/api/token/{userid}/{password} - make sure the userid and the password are url encoded ( http://meyerweb.com/eric/tools/dencoder/ )
  2. When making this call, if all is correct, a successful call will result in a token key returned for the account that made the call.  This token will consist of the following:

        

  1. A token string (used to make subsequent calls).
  1. An expiry date (A unix timestamp taken ranging from 1/1/1970 to the date the expiry was created).

Once the token is retrieved, its string can be used to make calls to the api without having to supply the username and password.  The expiry date is returned to indicate the lifetime of the token. Developers using the api can use this in their systems to pre-determine whether the token they have is valid.

Note: Later on when passing the token, make sure that the expiry date part is removed from the end

To access any operation using the new token:

  1. Make a call to an operation
  2. Pass the token via a query string or a header. The format for passing the token is token={token}.  For example, to pass the token through as a querystring then the url should contain the query string in the format of token={token}.

For example, the following POST request will get the scheme with number using the specified token as a query parameter.

https://slipstream.schemeserve.com/api/schemes/4235?token=ArlPArAk8StTeI3g16QLk+y0cDs=|S...

2.3.3 Switching between XML and JSON end-points

The default format for the API is XML, therefore the following call would accept an XML resource:

https://slipstream.schemeserve.com/api/cases?token=<token>

The correct URL to pass JSON would be:

https://slipstream.schemeserve.com/api/cases/json?token=<token>

with the Content-Type HTTP Header set to “application/json” instead of “text/xml” MIME type.

http://en.wikipedia.org/wiki/List_of_HTTP_header_fields

http://en.wikipedia.org/wiki/Internet_media_type

3 API Input/Output

3.1 Output

The API can return the information in two formats:

  1. XML
  2. JSON

The default format is XML, but this can be changed to JSON using the following call:

while simply calling

will return XML.

The state of the JSON or XML data returned from the API will depend on each operation.  This is documented further in the operations section of this documented. The actual information itself will be identical regardless of which format is returned. The only differences will be syntactical depending on the format that is being used.

3.2 Input

When calling operations from the API, a lot of the data will be filtered, so only specific information is returned.  There are four ways of adding data/values into the API:

  1. Using the URL structure.
  2. Using a query string
  3. Using form values (i.e. HTTP POST body fields)
  4. Using http headers

3.2.1 Query String

This is the easiest and most direct way of passing data to an API operation.  Mostly used for HTTP GET operations where a filter or a specific set of information is being targeted.  Query string values can also be used for other HTTP methods, however this will depend on the data to be added.

3.2.2 Form Values

Used for HTTP POST and PUT queries, the data itself is inserted in the body in the format <variable-name>=<variable-data>. While the query string method can still be used for POST and PUT requests, it’s not recommended due to two factors:

  1. The passed values are directly visible in the URL (which might not be desirable depending on the data’s sensitivity level)
  2. Most of the POST requests consist of larger strings of data, including JSON and XML which can’t be passed through the URL itself

3.2.3 HTTP Headers

Http headers are used only for authentication and/or metadata related information. Examples for this are the username (UserID), the password (Authorization ) and the token strings (Token).

Tip: The best way of initially testing all the methods above is using a RESTful client like POSTMAN in Chrome. This way you can easily edit every aspect of your request and the response youll get.

3.3 Get/Set Operations

Each call to the API is defined as an operation. Each operation is classed as either an Authentication Access type or a Token Access type. Operations have the following classifications:

  1. GET operation
  2. SET operation

3.3.1 GET

The GET operations are read-only and accessible both via a token and the simpler user/password authentication method.

3.3.2 SET

A set operation is an operation that can alter SchemeServe’s data, as well as return data.  A set operation consists of a HTTP POST, HTTP PUT and HTTP DELETE.  Set operations will only ever be defined as token access operations.


4 API End-Points

This section contains a list of the API end-points supported by SchemeServe’s API, as well as their parameters and examples attached.

4.1 Schemes

4.1.1 Get

URL

Parameters

Security Type

https://slipstream.schemeserve.com/api/schemes

None

Authentication Type and Token Type

Parameters

cURL example - retrieving a scheme:

C:\SchemeServe>curl https://slipstream.schemeserve.com/api/schemes/4325?token=vrGy86D6hqMVmb82DiCF5zdtvfg=|SyNg2qh
PTsRjSKPUQj5k6jgyCettI2SKT1aPlYqeszHr%2bOjPt%2fTr%2f4Id45IaqhUYgM0TvoNCbUncQuvnSnFG
Q7yaR6a%2fifoF2R%2frCDrwOv1NWU%2bB%2fZSqrNW7QCJkrr%2bpuLP5xPPREt%2fwxfLU6461ZVZuXxY
%2fsVoT2ZdrxLq7L4I0O7VpwBaItK4UXL8l65G4znZxkzSCwwTOYXjUoiUtBTLCeLI1YFFz

Example Result XML

<schemes xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

    <scheme>

        <agentonly>true</agentonly>

        <allowbrokertostartcover>false</allowbrokertostartcover>

        <allowcheque>true</allowcheque>

        <allowdeposit>true</allowdeposit>

        <allowfullpremium>false</allowfullpremium>

        <allowinvoice>true</allowinvoice>

        <name>AXA Scheme</name>

        <questionsets>

            <questionpage>

                <questionpageid>Page1</questionpageid>

                <questionpagename>Client Details</questionpagename>

                <questions>

                    <question>

                        <helptext>help tip here</helptext>

                        <tag />

                        <type>Client.ContactName</type>

                        <questionid>ClientNameField</questionid>

                        <description>Client name</description>

                        <answers />

                    </question>

                    <question>

                        <helptext>email help tip</helptext>

                        <tag />

                        <type>Client.Email</type>

                        <questionid>ClientEmailField</questionid>

                        <description>Client email</description>

                        <answers />

                    </question>

                </questions>

            </questionpage>

            <questionpage>

                <questionpageid>PageCalculation</questionpageid>

                <questionpagename>Cover Details</questionpagename>

                <questions>

                    <question>

                        <helptext />

                        <tag />

                        <type>Total</type>

                        <questionid>BasicPremiumTotal</questionid>

                        <description>&lt;b&gt;Basic Premium Total&lt;/b&gt;</description>

                        <answers />

                    </question>

                    <question>

                        <helptext />

                        <tag />

                        <type>Total</type>

                        <questionid>PackageDiscount</questionid>

                        <description>- Discount</description>

                        <answers />

                    </question>

                    <question>

                        <helptext />

                        <tag />

                        <type>Total</type>

                        <questionid>TotalPremiumNet</questionid>

                        <description>&lt;b&gt;Total Premium (Net)&lt;/b&gt;</description>

                        <answers />

                    </question>

                    <question>

                        <helptext />

                        <tag />

                        <type>Total</type>

                        <questionid>IPT</questionid>

                        <description>+ IPT</description>

                        <answers />

                    </question>

                    <question>

                        <helptext />

                        <tag />

                        <type>Total</type>

                        <questionid>PolicyFee</questionid>

                        <description>+ Policy Fee</description>

                        <answers />

                    </question>

                    <question>

                        <helptext />

                        <tag />

                        <type>Total</type>

                        <questionid>TotalPremium</questionid>

                        <description>&lt;b&gt;Total Premium&lt;/b&gt;</description>

                        <answers />

                    </question>

                    <question>

                        <helptext />

                        <tag />

                        <type>Total</type>

                        <questionid>CommissionFromInsurer</questionid>

                        <description>&lt;b&gt;Commission From Insurer&lt;/b&gt;</description>

                        <answers />

                    </question>

                    <question>

                        <helptext />

                        <tag />

                        <type>Total</type>

                        <questionid>Commission</questionid>

                        <description>&lt;b&gt;Total Commission&lt;/b&gt;</description>

                        <answers />

                    </question>

                    <question>

                        <helptext />

                        <tag />

                        <type>Total</type>

                        <questionid>DueFromBroker</questionid>

                        <description>(Due From Broker)</description>

                        <answers />

                    </question>

                    <question>

                        <helptext />

                        <tag />

                        <type>YesNoDropDown</type>

                        <questionid>CancellationCoverField</questionid>

                        <description>Cancellation Cover</description>

                        <answers />

                    </question>

                    <question>

                        <helptext />

                        <tag />

                        <type>YesNoDropDown</type>

                        <questionid>LuggageCoverField</questionid>

                        <description>Luggage Cover</description>

                        <answers />

                    </question>

                    <question>

                        <helptext />

                        <tag />

                        <type>YesNoDropDown</type>

                        <questionid>SkiCoverField</questionid>

                        <description>Ski Cover</description>

                        <answers />

                    </question>

                    <question>

                        <helptext />

                        <tag />

                        <type>YesNoDropDown</type>

                        <questionid>BusinessCoverField</questionid>

                        <description>Business Cover</description>

                        <answers />

                    </question>

                </questions>

            </questionpage>

            <questionpage>

                <questionpageid>Page5</questionpageid>

                <questionpagename>Additional Questions</questionpagename>

                <questions>

                    <question>

                        <helptext />

                        <tag />

                        <type>Text</type>

                        <questionid>Page5_Q1</questionid>

                        <description>Additional Question</description>

                        <answers />

                    </question>

                </questions>

            </questionpage>

        </questionsets>

        <schemeid>4235</schemeid>

        <schemeref />

    </scheme>

</schemes>

Example Result JSON

[{

    "agentonly": true,

    "allowbrokertostartcover": false,

    "allowcheque": true,

    "allowdeposit": true,

    "allowfullpremium": false,

    "allowinvoice": true,

    "name": "AXA Scheme",

    "questionsets": [{

        "questionpageid": "Page1",

        "questionpagename": "Client Details",

        "questions": [{

            "helptext": "help tip here",

            "tag": "",

            "type": "Client.ContactName",

            "questionid": "ClientNameField",

            "description": "Client name",

            "answers": []

        }, {

            "helptext": "email help tip",

            "tag": "",

            "type": "Client.Email",

            "questionid": "ClientEmailField",

            "description": "Client email",

            "answers": []

        }]

    }, {

        "questionpageid": "PageCalculation",

        "questionpagename": "Cover Details",

        "questions": [{

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "BasicPremiumTotal",

            "description": "<b>Basic Premium Total</b>",

            "answers": []

        }, {

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "PackageDiscount",

            "description": "- Discount",

            "answers": []

        }, {

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "TotalPremiumNet",

            "description": "<b>Total Premium (Net)</b>",

            "answers": []

        }, {

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "IPT",

            "description": "+ IPT",

            "answers": []

        }, {

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "PolicyFee",

            "description": "+ Policy Fee",

            "answers": []

        }, {

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "TotalPremium",

            "description": "<b>Total Premium</b>",

            "answers": []

        }, {

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "CommissionFromInsurer",

            "description": "<b>Commission From Insurer</b>",

            "answers": []

        }, {

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "Commission",

            "description": "<b>Total Commission</b>",

            "answers": []

        }, {

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "DueFromBroker",

            "description": "(Due From Broker)",

            "answers": []

        }, {

            "helptext": "",

            "tag": "",

            "type": "YesNoDropDown",

            "questionid": "CancellationCoverField",

            "description": "Cancellation Cover",

            "answers": []

        }, {

            "helptext": "",

            "tag": "",

            "type": "YesNoDropDown",

            "questionid": "LuggageCoverField",

            "description": "Luggage Cover",

            "answers": []

        }, {

            "helptext": "",

            "tag": "",

            "type": "YesNoDropDown",

            "questionid": "SkiCoverField",

            "description": "Ski Cover",

            "answers": []

        }, {

            "helptext": "",

            "tag": "",

            "type": "YesNoDropDown",

            "questionid": "BusinessCoverField",

            "description": "Business Cover",

            "answers": []

        }]

    }, {

        "questionpageid": "Page5",

        "questionpagename": "Additional Questions",

        "questions": [{

            "helptext": "",

            "tag": "",

            "type": "Text",

            "questionid": "Page5_Q1",

            "description": "Additional Question",

            "answers": []

        }]

    }],

    "schemeid": 4235,

    "schemeref": ""

}]

Summary

This operation will be used primarily to retrieve the required quote information for a scheme.  By using the data returned here, a new case or an update to a case can be implemented without manually constructing a question set.


4.2 Cases

4.2.1 Get

URL

Parameters

Security Type

https://slipstream.schemeserve.com/api/cases

-mode

-status

-schemeid

-caseid

-caserecordindex

Username/Password and Token Type

Parameters

Mode

The mode enables a particular group of cases to be retrieved.  For example, the mode latest enables the latest premium information to be retrieved.  The following list is available.

  1. latest - the latest case id

Status

The status of cases to retrieve.  This includes the following:

  1. every status
  2. referred
  3. user saved
  4. pending/invited (‘pending’ or ‘invited’ can be used here)
  5. more info
  6. cancelled
  7. declined
  8. lapsed
  9. ntu
  10. draft

schemeID

The scheme to get information from.

caseID

The case id to get the information for.

caseRecordID

0, -1 , -2.   0 will be the most current case record, -1 is the one before, and so on.

cURL example - retrieving a case:

C:\SchemeServe>curl https://slipstream.schemeserve.com/api/cases/2029244?token=vrGy86D6hqMVmb82Di...

Example Result XML

<case

    xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

    <archived>false</archived>

    <client>

        <accountid>15397</accountid>

        <address1/>

        <address2/>

        <badclient>false</badclient>

        <clientid>1583451</clientid>

    </client>

    <createddate>2015-02-05T13:17:14.75</createddate>

    <daysinterm>365</daysinterm>

    <deleted>false</deleted>

    <modifiedlastbyusername i:nil="true"/>

    <questionset>

        <questionpage>

            <questionpageid>Page1</questionpageid>

            <questionpagename>Client Details</questionpagename>

            <questions>

                <question>

                    <helptext>help tip here</helptext>

                    <tag/>

                    <type>Client.ContactName</type>

                    <questionid>ClientNameField</questionid>

                    <description>Client name</description>

                    <answers>

                        <answer>

                            <clientname>

                                <firstname i:nil="true"/>

                                <surname i:nil="true"/>

                                <title>Mr</title>

                            </clientname>

                            <description i:nil="true"/>

                            <value/>

                        </answer>

                    </answers>

                </question>

                <question>

                    <helptext>email help tip</helptext>

                    <tag/>

                    <type>Client.Email</type>

                    <questionid>ClientEmailField</questionid>

                    <description>Client email</description>

                    <answers>

                        <answer>

                            <description i:nil="true"/>

                            <value/>

                        </answer>

                    </answers>

                </question>

            </questions>

        </questionpage>

        <questionpage>

            <questionpageid>PageCalculation</questionpageid>

            <questionpagename>Cover Details</questionpagename>

            <questions>

                <question>

                    <helptext/>

                    <tag/>

                    <type>Total</type>

                    <questionid>BasicPremiumTotal</questionid>

                    <description>&lt;b&gt;Basic Premium Total&lt;/b&gt;</description>

                    <answers>

                        <answer>

                            <description/>

                            <value>0.00</value>

                        </answer>

                    </answers>

                </question>

                <question>

                    <helptext/>

                    <tag/>

                    <type>Total</type>

                    <questionid>PackageDiscount</questionid>

                    <description>- Discount</description>

                    <answers>

                        <answer>

                            <description/>

                            <value>0.00</value>

                        </answer>

                    </answers>

                </question>

                <question>

                    <helptext/>

                    <tag/>

                    <type>Total</type>

                    <questionid>TotalPremiumNet</questionid>

                    <description>&lt;b&gt;Total Premium (Net)&lt;/b&gt;</description>

                    <answers>

                        <answer>

                            <description/>

                            <value>0.00</value>

                        </answer>

                    </answers>

                </question>

                <question>

                    <helptext/>

                    <tag/>

                    <type>Total</type>

                    <questionid>IPT</questionid>

                    <description>+ IPT</description>

                    <answers>

                        <answer>

                            <description/>

                            <value>0.00</value>

                        </answer>

                    </answers>

                </question>

                <question>

                    <helptext/>

                    <tag/>

                    <type>Total</type>

                    <questionid>PolicyFee</questionid>

                    <description>+ Policy Fee</description>

                    <answers>

                        <answer>

                            <description/>

                            <value>0.00</value>

                        </answer>

                    </answers>

                </question>

                <question>

                    <helptext/>

                    <tag/>

                    <type>Total</type>

                    <questionid>TotalPremium</questionid>

                    <description>&lt;b&gt;Total Premium&lt;/b&gt;</description>

                    <answers>

                        <answer>

                            <description/>

                            <value>0.00</value>

                        </answer>

                    </answers>

                </question>

                <question>

                    <helptext/>

                    <tag/>

                    <type>Total</type>

                    <questionid>CommissionFromInsurer</questionid>

                    <description>&lt;b&gt;Commission From Insurer&lt;/b&gt;</description>

                    <answers>

                        <answer>

                            <description/>

                            <value>0.00</value>

                        </answer>

                    </answers>

                </question>

                <question>

                    <helptext/>

                    <tag/>

                    <type>Total</type>

                    <questionid>Commission</questionid>

                    <description>&lt;b&gt;Total Commission&lt;/b&gt;</description>

                    <answers>

                        <answer>

                            <description/>

                            <value>0.00</value>

                        </answer>

                    </answers>

                </question>

                <question>

                    <helptext/>

                    <tag/>

                    <type>Total</type>

                    <questionid>DueFromBroker</questionid>

                    <description>(Due From Broker)</description>

                    <answers>

                        <answer>

                            <description/>

                            <value>0.00</value>

                        </answer>

                    </answers>

                </question>

                <question>

                    <helptext/>

                    <tag/>

                    <type>YesNoDropDown</type>

                    <questionid>CancellationCoverField</questionid>

                    <description>Cancellation Cover</description>

                    <answers>

                        <answer>

                            <description/>

                            <value>Yes</value>

                        </answer>

                    </answers>

                </question>

                <question>

                    <helptext/>

                    <tag/>

                    <type>YesNoDropDown</type>

                    <questionid>LuggageCoverField</questionid>

                    <description>Luggage Cover</description>

                    <answers>

                        <answer>

                            <description/>

                            <value>Yes</value>

                        </answer>

                    </answers>

                </question>

                <question>

                    <helptext/>

                    <tag/>

                    <type>YesNoDropDown</type>

                    <questionid>SkiCoverField</questionid>

                    <description>Ski Cover</description>

                    <answers>

                        <answer>

                            <description/>

                            <value>Yes</value>

                        </answer>

                    </answers>

                </question>

                <question>

                    <helptext/>

                    <tag/>

                    <type>YesNoDropDown</type>

                    <questionid>BusinessCoverField</questionid>

                    <description>Business Cover</description>

                    <answers>

                        <answer>

                            <description/>

                            <value>Yes</value>

                        </answer>

                    </answers>

                </question>

            </questions>

        </questionpage>

        <questionpage>

            <questionpageid>Page5</questionpageid>

            <questionpagename>Additional Questions</questionpagename>

            <questions>

                <question>

                    <helptext/>

                    <tag/>

                    <type>Text</type>

                    <questionid>Page5_Q1</questionid>

                    <description>Additional Question</description>

                    <answers>

                        <answer>

                            <description/>

                            <value>Testing</value>

                        </answer>

                    </answers>

                </question>

            </questions>

        </questionpage>

    </questionset>

    <renewaldate>2016-02-05T00:00:00</renewaldate>

    <renewalpremium>10.0000</renewalpremium>

    <schemeid>4235</schemeid>

    <accountid>15397</accountid>

    <caseid>1993572</caseid>

    <inceptiondate>2015-02-05T00:00:00</inceptiondate>

    <lastmodified>2015-02-05T13:17:14.75</lastmodified>

</case>

Example Result JSON

{

    "archived": false,

    "client": {

        "accountid": 15397,

        "address1": "",

        "address2": "",

        "badclient": false,

        "clientid": 1583451

    },

    "createddate": "/Date(1423142234750+0000)/",

    "daysinterm": 365,

    "deleted": false,

    "modifiedlastbyusername": null,

    "questionset": [{

        "questionpageid": "Page1",

        "questionpagename": "Client Details",

        "questions": [{

            "helptext": "help tip here",

            "tag": "",

            "type": "Client.ContactName",

            "questionid": "ClientNameField",

            "description": "Client name",

            "answers": [{

                "clientname": {

                    "firstname": null,

                    "surname": null,

                    "title": "Mr"

                },

                "description": null,

                "value": ""

            }]

        }, {

            "helptext": "email help tip",

            "tag": "",

            "type": "Client.Email",

            "questionid": "ClientEmailField",

            "description": "Client email",

            "answers": [{

                "description": null,

                "value": ""

            }]

        }]

    }, {

        "questionpageid": "PageCalculation",

        "questionpagename": "Cover Details",

        "questions": [{

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "BasicPremiumTotal",

            "description": "<b>Basic Premium Total</b>",

            "answers": [{

                "description": "",

                "value": "0.00"

            }]

        }, {

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "PackageDiscount",

            "description": "- Discount",

            "answers": [{

                "description": "",

                "value": "0.00"

            }]

        }, {

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "TotalPremiumNet",

            "description": "<b>Total Premium (Net)</b>",

            "answers": [{

                "description": "",

                "value": "0.00"

            }]

        }, {

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "IPT",

            "description": "+ IPT",

            "answers": [{

                "description": "",

                "value": "0.00"

            }]

        }, {

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "PolicyFee",

            "description": "+ Policy Fee",

            "answers": [{

                "description": "",

                "value": "0.00"

            }]

        }, {

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "TotalPremium",

            "description": "<b>Total Premium</b>",

            "answers": [{

                "description": "",

                "value": "0.00"

            }]

        }, {

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "CommissionFromInsurer",

            "description": "<b>Commission From Insurer</b>",

            "answers": [{

                "description": "",

                "value": "0.00"

            }]

        }, {

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "Commission",

            "description": "<b>Total Commission</b>",

            "answers": [{

                "description": "",

                "value": "0.00"

            }]

        }, {

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "DueFromBroker",

            "description": "(Due From Broker)",

            "answers": [{

                "description": "",

                "value": "0.00"

            }]

        }, {

            "helptext": "",

            "tag": "",

            "type": "YesNoDropDown",

            "questionid": "CancellationCoverField",

            "description": "Cancellation Cover",

            "answers": [{

                "description": "",

                "value": "Yes"

            }]

        }, {

            "helptext": "",

            "tag": "",

            "type": "YesNoDropDown",

            "questionid": "LuggageCoverField",

            "description": "Luggage Cover",

            "answers": [{

                "description": "",

                "value": "Yes"

            }]

        }, {

            "helptext": "",

            "tag": "",

            "type": "YesNoDropDown",

            "questionid": "SkiCoverField",

            "description": "Ski Cover",

            "answers": [{

                "description": "",

                "value": "Yes"

            }]

        }, {

            "helptext": "",

            "tag": "",

            "type": "YesNoDropDown",

            "questionid": "BusinessCoverField",

            "description": "Business Cover",

            "answers": [{

                "description": "",

                "value": "Yes"

            }]

        }]

    }, {

        "questionpageid": "Page5",

        "questionpagename": "Additional Questions",

        "questions": [{

            "helptext": "",

            "tag": "",

            "type": "Text",

            "questionid": "Page5_Q1",

            "description": "Additional Question",

            "answers": [{

                "description": "",

                "value": "Testing"

            }]

        }]

    }],

    "renewaldate": "/Date(1454630400000+0000)/",

    "renewalpremium": 10,

    "schemeid": 4235,

    "accountid": 15397,

    "caseid": 1993572,

    "inceptiondate": "/Date(1423094400000+0000)/",

    "lastmodified": "/Date(1423142234750+0000)/"

}

Summary

The data returned for this operation depends on the authorization method used.If this operation is called using an authentication type then a limited collection is returned. However, if the token type is being used then all the collection data for cases are available.

4.2.2 Set

Setting a case involves the insertion of questions to create a quote.

URL

Parameters

Security Type

https://slipstream.schemeserve.com/api/cases/

-case resource (XML/JSON)

Token Type only.

Parameters

The Case Resource

The Case resource is basically the XML/JSON HTTP POST body containing the actual case to be created. The question set is contained on every case resource. By submitting a case resource with a completed question set, a new case can be created.  When submitting a new case, the caseid and the accountid  need not be submitted, these will be automatically generated upon successful creation.

The structure of the question set can be viewed in both the example case output shown above, or the schemes output.

If a case ID is present when the operation is called with this parameter, and api call is a POST operation, then an error will be returned and a case will not be submitted.  If a case ID is present in a PUT operation, then the existing case that matches the case ID will be updated if possible. Note SchemeServe API does not currently support updating cases via the API.

schemeID

The scheme for which cases are added or updated.

Mode

Optional, used for specific set operations.

XML Request Example

<case xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

    <questionset>

        <questionpage>

            <questionpageid>Page1</questionpageid>

            <questionpagename>Client Details</questionpagename>

            <questions>

                <question>

                    <helptext>help tip here</helptext>

                    <tag />

                    <type>Client.ContactName</type>

                    <questionid>ClientNameField</questionid>

                    <description>Client name</description>

                    <answers>

                        <answer>

                            <clientname>

                                <firstname>Stephanie</firstname>

                                <surname>Mc'Govern</surname>

                                <title>title</title>

                            </clientname>

                        </answer>

                    </answers>

                </question>

                <question>

                    <helptext>email help tip</helptext>

                    <tag />

                    <type>Client.Email</type>

                    <questionid>ClientEmailField</questionid>

                    <description>Client email</description>

                    <answers>

                        <answer>

                            <address>

                                <addressline1>line 1</addressline1>

                                <addressline2>line 2</addressline2>

                                <town>line 3</town>

                                <county>line 4</county>

                                <postcode>post code</postcode>

                            </address>

                        </answer>

                    </answers>

                </question>

            </questions>

        </questionpage>

        <questionpage>

            <questionpageid>PageCalculation</questionpageid>

            <questionpagename>Cover Details</questionpagename>

            <questions>

                <question>

                    <helptext />

                    <tag />

                    <type>Total</type>

                    <questionid>BasicPremiumTotal</questionid>

                    <description>&lt;b&gt;Basic Premium Total&lt;/b&gt;</description>

                    <answers>

                       <answer>

                          <value>test value</value>

                       </answer>

                    </answers>

                </question>

                <question>

                    <helptext />

                    <tag />

                    <type>Total</type>

                    <questionid>PackageDiscount</questionid>

                    <description>- Discount</description>

                    <answers>

                       <answer>

                          <value>test value</value>

                       </answer>

                    </answers>

                </question>

                <question>

                    <helptext />

                    <tag />

                    <type>Total</type>

                    <questionid>TotalPremiumNet</questionid>

                    <description>&lt;b&gt;Total Premium (Net)&lt;/b&gt;</description>

                    <answers>

                       <answer>

                          <value>test value</value>

                       </answer>

                    </answers>

                </question>

                <question>

                    <helptext />

                    <tag />

                    <type>Total</type>

                    <questionid>IPT</questionid>

                    <description>+ IPT</description>

                    <answers />

                </question>

                <question>

                    <helptext />

                    <tag />

                    <type>Total</type>

                    <questionid>PolicyFee</questionid>

                    <description>+ Policy Fee</description>

                    <answers>

                       <answer>

                          <value>test value</value>

                       </answer>

                    </answers>

                </question>

                <question>

                    <helptext />

                    <tag />

                    <type>Total</type>

                    <questionid>TotalPremium</questionid>

                    <description>&lt;b&gt;Total Premium&lt;/b&gt;</description>

                    <answers>

                       <answer>

                          <value>test value</value>

                       </answer>

                    </answers>

                </question>

                <question>

                    <helptext />

                    <tag />

                    <type>Total</type>

                    <questionid>CommissionFromInsurer</questionid>

                    <description>&lt;b&gt;Commission From Insurer&lt;/b&gt;</description>

                    <answers>

                       <answer>

                          <value>test value</value>

                       </answer>

                    </answers>

                </question>

                <question>

                    <helptext />

                    <tag />

                    <type>Total</type>

                    <questionid>Commission</questionid>

                    <description>&lt;b&gt;Total Commission&lt;/b&gt;</description>

                    <answers>

                       <answer>

                          <value>test value</value>

                       </answer>

                    </answers>

                </question>

                <question>

                    <helptext />

                    <tag />

                    <type>Total</type>

                    <questionid>DueFromBroker</questionid>

                    <description>(Due From Broker)</description>

                    <answers>

                       <answer>

                          <value>test value</value>

                       </answer>

                    </answers>

                </question>

                <question>

                    <helptext />

                    <tag />

                    <type>YesNoDropDown</type>

                    <questionid>CancellationCoverField</questionid>

                    <description>Cancellation Cover</description>

                    <answers>

                       <answer>

                          <value>test value</value>

                       </answer>

                    </answers>

                </question>

                <question>

                    <helptext />

                    <tag />

                    <type>YesNoDropDown</type>

                    <questionid>LuggageCoverField</questionid>

                    <description>Luggage Cover</description>

                    <answers>

                       <answer>

                          <value>test value</value>

                       </answer>

                    </answers>

                </question>

                <question>

                    <helptext />

                    <tag />

                    <type>YesNoDropDown</type>

                    <questionid>SkiCoverField</questionid>

                    <description>Ski Cover</description>

                    <answers>

                       <answer>

                          <value>test value</value>

                       </answer>

                    </answers>

                </question>

                <question>

                    <helptext />

                    <tag />

                    <type>YesNoDropDown</type>

                    <questionid>BusinessCoverField</questionid>

                    <description>Business Cover</description>

                     <answers>

                       <answer>

                          <value>test value</value>

                       </answer>

                    </answers>

                </question>

            </questions>

        </questionpage>

        <questionpage>

            <questionpageid>Page5</questionpageid>

            <questionpagename>Additional Questions</questionpagename>

            <questions>

                <question>

                    <helptext />

                    <tag />

                    <type>Text</type>

                    <questionid>Page5_Q1</questionid>

                    <description>Additional Question</description>

                    <answers>

                       <answer>

                          <value>test value</value>

                       </answer>

                    </answers>

                </question>

            </questions>

        </questionpage>

    </questionset>

    <schemeid>2499</schemeid>

    <archived>false</archived>

    <client />

    <deleted>false</deleted>

</case>

JSON Request Example

{

    "questionset": [{

        "questionpageid": "Page1",

        "questionpagename": "Client Details",

        "questions": [{

            "helptext": "help tip here",

            "tag": "",

            "type": "Client.ContactName",

            "questionid": "ClientNameField",

            "description": "Client name",

            "answers": []

        }, {

            "helptext": "email help tip",

            "tag": "",

            "type": "Client.Email",

            "questionid": "ClientEmailField",

            "description": "Client email",

            "answers": []

        }]

    }, {

        "questionpageid": "PageCalculation",

        "questionpagename": "Cover Details",

        "questions": [{

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "BasicPremiumTotal",

            "description": "<b>Basic Premium Total</b>",

            "answers": []

        }, {

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "PackageDiscount",

            "description": "- Discount",

            "answers": []

        }, {

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "TotalPremiumNet",

            "description": "<b>Total Premium (Net)</b>",

            "answers": []

        }, {

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "IPT",

            "description": "+ IPT",

            "answers": []

        }, {

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "PolicyFee",

            "description": "+ Policy Fee",

            "answers": []

        }, {

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "TotalPremium",

            "description": "<b>Total Premium</b>",

            "answers": []

        }, {

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "CommissionFromInsurer",

            "description": "<b>Commission From Insurer</b>",

            "answers": []

        }, {

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "Commission",

            "description": "<b>Total Commission</b>",

            "answers": []

        }, {

            "helptext": "",

            "tag": "",

            "type": "Total",

            "questionid": "DueFromBroker",

            "description": "(Due From Broker)",

            "answers": []

        }, {

            "helptext": "",

            "tag": "",

            "type": "YesNoDropDown",

            "questionid": "CancellationCoverField",

            "description": "Cancellation Cover",

            "answers": []

        }, {

            "helptext": "",

            "tag": "",

            "type": "YesNoDropDown",

            "questionid": "LuggageCoverField",

            "description": "Luggage Cover",

            "answers": []

        }, {

            "helptext": "",

            "tag": "",

            "type": "YesNoDropDown",

            "questionid": "SkiCoverField",

            "description": "Ski Cover",

            "answers": []

        }, {

            "helptext": "",

            "tag": "",

            "type": "YesNoDropDown",

            "questionid": "BusinessCoverField",

            "description": "Business Cover",

            "answers": []

        }]

    }, {

        "questionpageid": "Page5",

        "questionpagename": "Additional Questions",

        "questions": [{

            "helptext": "",

            "tag": "",

            "type": "Text",

            "questionid": "Page5_Q1",

            "description": "Additional Question",

            "answers": []

        }]

    }],

    "schemeid": 4235

}

4.2.3 Correctly formatting your AddCase XML or JSON resource

When sending a POST request to create a case, it’s important to pass the correct XML/JSON format so it can be successfully parsed by the system. For example, a typical Create Case XML resource would consist of the following elements:

<case>

    <questionset>

        <questionpage>

            ...

            <questions>

                <question>

                    ...

                    <answers>

                        <answer>

Although we can compose each request manually, it’s usually better to get a pre-generated question set and edit it to ensure it’s up-to-date and correct. This can be done by querying the Get Schemes API end-point:

https://slipstream.schemeserve.com/api/schemes/4235?token=<token>

or

https://slipstream.schemeserve.com/api/schemes/4235/json?token=<token>

which will return that scheme’s question set with some extra scheme-related nodes

<?xml version="1.0" encoding="UTF-8"?>

<schemes xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

   <scheme>

      <agentonly>true</agentonly>

      <allowbrokertostartcover>false</allowbrokertostartcover>

      <allowcheque>true</allowcheque>

      <allowdeposit>true</allowdeposit>

      <allowfullpremium>false</allowfullpremium>

      <allowinvoice>true</allowinvoice>

      <name>AXA Scheme</name>

      <questionsets>

         <questionpage>

            <questionpageid>Page1</questionpageid>

            <questionpagename>Client Details</questionpagename>

            <questions>

               <question>

                  <helptext>help tip here</helptext>

                  <tag />

                  <type>Client.ContactName</type>

                  <questionid>ClientNameField</questionid>

                  <description>Client name</description>

                  <answers />

               </question>

               <question>

                  <helptext>email help tip</helptext>

                  <tag />

                  <type>Client.Email</type>

                  <questionid>ClientEmailField</questionid>

                  <description>Client email</description>

                  <answers />

               </question>

            </questions>

         </questionpage>

        …

      </questionsets>

      <schemeid>4235</schemeid>

      <schemeref />

   </scheme>

</schemes>

At this point we almost have a complete Add Case XML resource, but there are also a couple of modifications we need to get done:

  1. Rename the <questionsets> node to <questionset>
  2. Take out the whole <questionset> node with all of its sub-elements and put them inside the correct Add Case elements template, e.g.:

<case xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

   <questionset>

      ----> insert the questionset node here  <----

   </questionset>

   <schemeid>2499</schemeid>

    <archived>false</archived>

    <client />

    <deleted>false</deleted>

</case>

    3.   Specify the correct SchemeId inside the <schemeid> element.

    4.   Add the appropriate answers to the question set.

For the 4-th step, you can see that all of the answers returned from the Get Scheme call are empty

               <question>

                  ...

                  <answers />

               </question>

The <answers /> empty nodes should be replaced with the generic answer format with the correct value:

               <answer>

                    <value>test value</value>

               </answer>

For the client-related answers at the beginning of each question set, a special format should be used as follows:

                

                         <answer>

                            <clientname>

                                <firstname>firstname</firstname>

                                <surname>surname</surname>

                                <title>title</title>

                            </clientname>

                        </answer>

                        <answer>

                            <address>

                                <addressline1>line 1</addressline1>

                                <addressline2>line 2</addressline2>

                                <town>line 3</town>

                                <county>line 4</county>

                                <postcode>post code</postcode>

                            </address>

                        </answer>

The final result should match the XML example from the previous section.

4.2.4 Case Payment Details

Payment details can be passed to a new case, causing  a payment schedule or a payment record to be set up and stored for the case.  If the payment is specified as a direct debit payment, then the schedule will be fully setup, and the payments will be initiated based on the payment schedule submitted.

When a case is successfully submitted with valid payment details, a unique mandate reference number will be passed back upon a valid case submittal.

To setup a payment on a case, the following is required:

Account Name

The account name is self explanatory - this is the account name for the bank account that will be debited.

Account Number

The acount number is self explanatory - this is the account name for the bank account that will be debited.

Sort Code

The sort code is self explanatory - this is the account sort code for the bank account that will be debited.

BIC Reference

This is self explanatory - this is the BIC Number for the bank account that will be debited.

IBAN Reference

This is self explanatory - this is the IBAN Reference for the bank account that will be debited.

Collection Amount

This is the amount required to be collected for this case.  When specifically referring to direct debits, this is the amount that will be collected at the scheduled times.

Date of First Collection

This is the amount required to be collected for the first time.  Typically, some premiums will require a different first payment than the actual scheduled payment for direct debits.

Payment Method

The Payment Method is the way in which payment has been made.  The following values can be applied here:

Please note, only the number is passed when submitting a case.

Please refer to the the payment method table below for more information.

Payment Method ID

The payment method id is the identifier that tells the system which type of payment method to use.

Please refer to the the payment method table below for more information.

Payment Frequency ID

This is the identifier that controls the frequency of payments within a payment schedule.  This only applies to direct debit payments.  

4.2.5 Payment Method Information Table

                                   

Payment Method ID

Type of payment

Payment Frequency ID

Payment Frequency

4

DataCash Direct Debit

2

Monthly

3

Cash Payment

4

N/A

4

DataCash Direct Debit

5

Weekly

4

DataCash Direct Debit

6

Monthly

4

DataCash Direct Debit

7

Quarterly

4

DataCash Direct Debit

8

Anually

5

Paybase Direct Debit

9

Monthly

5

Paybase Direct Debit

10

Quarterly

5

Paybase Direct Debit

11

Annually

8

External Payment

13

Monthly

8

External Payment

14

Annually

Payment Information Examples

The following is an example JSON and XML snippet that forms the overall payment schedule for a case.

Payment Example XML

...

<paymentdetails>
   
<accountname>XXX</accountname>
   
<accountnumber>0</accountnumber>

    <sortcode>XXX</sortcode>
   
<bic>XXX</bic>

    <iban>XXX</iban>
   
<collectionamount>12.34</collectionamount>
   
<dateoffirstcollection>1999-05-31T11:20:00</dateoffirstcollection>
   
<dayofmonthdebited>1</dayofmonthdebited>
   
<firstcollectionamount>12.34</firstcollectionamount>
   
<paymentfrequencyid>0</paymentfrequencyid>
   
<paymentmethod>8</paymentmethod>
   
<paymentmethodid>13</paymentmethodid>
</paymentdetails>

...

Payment Example JSON

...

"paymentdetails":        

{        "accountname":"XXX",

"accountnumber":"0",

"bic":"XXX",

"collectionamount":12.34,

"iban":"XXX",

"paymentmethod":8,

"sortcode":"XXX",

"paymentmethodid":13,

"paymentfrequencyid":0

}

...

Results

Success

A successful call to this operation will depend on the following conditions:

If the call to the operation matches the conditions, then the new case resource is returned.  If the operation is for a new quote and the question set contains only some of the questions when the operation was executed, then a case may still be created, however it will not be complete. It is the responsibility of the caller to ensure a case is complete based on the output that is returned upon a successful call.        

Failure

A failed call to this operation will return the following:


4.3 Statistics

The API has also has a statistics section, designed to deliver useful information on the usage SchemeServe.

4.3.1 Statistics Resource

The statistics resource has the following fields:

4.3.2 Get

URL

Parameters

Security Type

https://slipstream.schemeserve.com/api/statistics

Authentication type

A set of statistics are delivered through the api when this operation is executed.  The statistics that are delivered will depend on the login of the user attempting to access the API.  If an internal Schemeserve administrator with full admin rights to Schemeserve executes this operation, then the statistics will be based on SchemeServe entirely.  When a user logs in with access only to a specific account and set of schemes, then the statistics delivered will only apply to them.

Example result

<statistics xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

        <statistic>

                <description>Gets the number of companies that schemeserve currently supports</description>

                <name>NumberAccounts</name>

                <result>88</result>

        </statistic>

        <statistic>

                <description>The total revenue generated by schemeserve</description>

                <displayresult>£1,699,915,475,219.19</displayresult>

                <name>TotalRevenue</name>

                <result>1699915475219.19</result>

        </statistic>

        <statistic>

                <description>The total number of schemes being used in Schemeserve</description>

                <name>TotalSchemes</name>

                <result>181</result>

        </statistic>

</statistics>

4.4 Endorsements

4.4.1 Endorsements Resource

Endorsement templates can be imported into an account through the API. The endorsements resource has the following fields:

4.4.2 Get

URL

Parameters

Security Type

https://slipstream.schemeserve.com/api/endorsements/templates/

-schemeid

-insurerid

Username/Password authentication

Parameters

Schemeid

The scheme for the endorsement.

Insurerid

The insurer id of all the endorsements.

Example Result XML

<endorsementlibrary>

    <endorsementlibraryitem>

        <createddate>1999-05-31T11:20:00</createddate>

        <deleted>true</deleted>

        <modifiedlastbyusername>String content</modifiedlastbyusername>

        <schemeid>2147483647</schemeid>

        <masteraccountid>2147483647</masteraccountid>

        <insurerid>2147483647</insurerid>

        <title>String content</title>

        <body>String content</body>

        <identifier>String content</identifier>

        <type>String content</type>

        <lastmodified>1999-05-31T11:20:00</lastmodified>

    </endorsementlibraryitem>

    <endorsementlibraryitem>

        <createddate>1999-05-31T11:20:00</createddate>

        <deleted>true</deleted>

        <modifiedlastbyusername>String content</modifiedlastbyusername>

        <schemeid>2147483647</schemeid>

        <masteraccountid>2147483647</masteraccountid>

        <insurerid>2147483647</insurerid>

        <title>String content</title>

        <body>String content</body>

        <identifier>String content</identifier>

        <type>String content</type>

        <lastmodified>1999-05-31T11:20:00</lastmodified>

    </endorsementlibraryitem>

</endorsementlibrary>

Example Result JSON

[{
        
"createddate":"\/Date(928146000000+0100)\/",
        
"deleted":true,
        
"modifiedlastbyusername":"String content",
        
"schemeid":2147483647,
        
"masteraccountid":2147483647,
        
"insurerid":2147483647,
        
"title":"String content",
        
"body":"String content",
        
"identifier":"String content",
        
"type":"String content",
        
"lastmodified":"\/Date(928146000000+0100)\/"
}]

4.4.3 Set

This operation concerns the import of one or multiple endorsement items into a chosen scheme and insurer.  This operation enables you create an entire endorsement library consisting of multiple endorsement items.

URL

Parameters

Security Type

https://slipstream.schemeserve.com/api/endorsements/templates/

endorsement resource

POST

Token Type only.

Parameters

Endorsement Resource

The structure of the endorsement item can be viewed in the example endorsement output shown above.

Results

Success

A successful call to this operation will depend on the following conditions:

If the call to the operation matches the conditions, then the new endorsement resource is returned.        

Failure

A failed call to this operation will return the following:

Example Request XML

<endorsementlibrary>

    <endorsementlibraryitem>

        <createddate>1999-05-31T11:20:00</createddate>

        <deleted>true</deleted>

        <modifiedlastbyusername>String content</modifiedlastbyusername>

        <schemeid>2147483647</schemeid>

        <masteraccountid>2147483647</masteraccountid>

        <insurerid>2147483647</insurerid>

        <title>String content</title>

        <body>String content</body>

        <identifier>String content</identifier>

        <type>String content</type>

        <lastmodified>1999-05-31T11:20:00</lastmodified>

    </endorsementlibraryitem>

Example Request JSON

[{
        
"createddate":"\/Date(928146000000+0100)\/",
        
"deleted":true,
        
"modifiedlastbyusername":"String content",
        
"schemeid":2147483647,
        
"masteraccountid":2147483647,
        
"insurerid":2147483647,
        
"title":"String content",
        
"body":"String content",
        
"identifier":"String content",
        
"type":"String content",
        
"lastmodified":"\/Date(928146000000+0100)\/"
}]


4.5 Reports

4.5.1 Reports Resource

Reports can be downloaded, or specific reports can be uploaded to a different place (such as an FTP server).

The reports resource has the following fields:

4.5.2 GET

URL

Parameters

Security Type

https://slipstream.schemeserve.com/api/reports/<reportid>/<reporttype>

reportid

reporttype

Authentication type

Parameters

Reportid

The report id to retrieve

Report Type

The report type, added as an integer.  There are two report types available:

5 Example Code

5.1 PHP

Note: For a complete example of how to query the API using PHP, check our GitHub public repository

https://github.com/admnetwork/SchemeServe.API.ExamplePHP

5.1.1 Getting the Access Token

The following PHP snippet illustrates the minimum amount of code needed to execute a successful request using cURL.

<?php

$url = 'https://slipstream.schemeserve.com/api/token/<username>/<password>';

$ch = curl_init();

curl_setopt( $ch, CURLOPT_URL, $url );

curl_setopt( $ch, CURLOPT_HEADER, 0 );

curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );

curl_setopt( $ch, CURLOPT_TIMEOUT, 100 );

curl_setopt( $ch, CURLINFO_HEADER_OUT, true );

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0); // remove this from production

$output = curl_exec($ch);

if(!$output) {

        echo 'Curl error: ' . curl_error($ch);

        return false;

}

echo $output;

?>

A successful request will result in the token itself followed by an expiration timestamp.

vUHmEnSqCDIDI/ygdrU39cjazj0=|SyNg2qhPTsRjSKPUQj5k6j0u%2fye6Xh0r6%2fjoz7f06%2f%2bCHeOSGq

oVGIFHIKPCp8otPdVFX3S0l%2fcuJ8acs0Pm5qDI1gMQX9c%2bRUocIQEGzWuoDJS9m6lJ%2blcS%2bw4J

vRF5Cgi83Bxm94BbXhEdEiUF78V0B8thLg3qadF4QROI3tGWrh0P0npyQgHB6algsGDG4DK0Ob1oRe%2fW

xH1OAlBTeg%3d%3d1423321710

Important

  • The expiration timestamp (1423321710) should be removed when passing the token for the subsequent requests.
  • The CURLOPT_SSL_VERIFYPEER  parameter is required only on development and should not be included on production

5.1.2 Adding a Case

The following snippet of code illustrates a successful Case creation request with either XML and JSON resource.

<?php

$url = 'https://slipstream.schemeserve.com/api/token?token=HlZvrFZ2U5A3aPbZ85U3vR1jqaU=|SyNg2qhPTsRjSKPUQj5k
6j0u%2fye6Xh0r6%2fjoz7f06%2f%bCHeOSGqoVGIFHIKP1p8otPdVFX3S0l%2fcuJ8acs0Pm5qDI1gMQX9c%2b66v
5KXyof6CoDJS9m6lJ%2blcS%2bw4JvRF5Cgi83Bxm94BbXhEdEiUF78V0B8thLg3qadF4QROI3tGnFu%2fnpR4wgcg
3YMEKbsCB4DK0Ob1oRe%2fWxH1OAlBTeg%3d%3d';

// for JSON the URL above will become https://slipstream.schemeserve.com/api/token/json

$case = file_get_contents('./request-body-xml', true);

$ch = curl_init();

curl_setopt( $ch, CURLOPT_URL, $url );

curl_setopt( $ch, CURLOPT_HEADER, 0 );

curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );

curl_setopt( $ch, CURLOPT_TIMEOUT, 100 );

curl_setopt( $ch, CURLINFO_HEADER_OUT, true );

//curl_setopt( $ch, CURLOPT_HTTPHEADER, array('Content-type: application/json') );

curl_setopt( $ch, CURLOPT_HTTPHEADER, array('Content-type: text/xml') );

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0); // remove this from production

curl_setopt( $ch, CURLOPT_POSTFIELDS, $case );

$output = curl_exec($ch);

if(!$output) {

        echo 'Curl error: ' . curl_error($ch);

        return false;

}

echo $output;

?>

Note

For an XML or JSON add case resource example, refer to the Add Case HTTP Set section.

5.2 .NET

SchemeServe’s API demo application for .Net can be found at

https://github.com/admnetwork/SchemeServe.API.ExampleDotNET 

If you have any question or concerns, don’t hesitate to get in touch support@schemeserve.com

6 Troubleshooting

6.1 Common Issues
This section contains a list of common issues and information on how to address them.

6.1.1 The API returns “The input is not a valid Base-64 string”

Make sure the expiry date timestamp is removed from the token.

6.1.2 The server responds with Bad Format Exception when trying to add a case

There are few possible reasons for this error:

  1. Your Case resource XML/JSON format is wrong
  2. Something in the actual question set has changed and the resource is no longer up to date

In both cases the best thing to do is to re-generate the question set using a call to the Scheme end-point and making sure it matches the current version.

6.1.3 I’m getting “Curl error: SSL certificate problem” when trying to access the API through my local PHP client

Adding the following line to your development code will resolve the issue

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);

Make sure you remove this line from production code.

6.1.4 I’ve successfully added a case with an XML resource, but can’t manage the get the JSON working

There are few possible reasons for that:

Reason #1: Using the wrong URL end-point

The correct JSON URL end point is https://slipstream.schemeserve.com/api/cases/json not https://slipstream.schemeserve.com/api/cases 

Reason #2: Not sending the correct headers

        For JSON resources, the correct Content type is application/json not text/xml .

Reason #3: Using an online XML to JSON converter

If you’ve already managed to create a case using XML, the most intuitive move would be to use one of the many XML to JSON Converters . Unfortunately this will not produce the correct JSON format for SchemeServe when there are arrays in the request. Instead, the Get Scheme call should be used to retrieve the correct JSON format.

6.2 Further steps

When we’re having difficulties executing a request, one of the most-efficient ways of resolving the problem is separating it into modules and testing them independently. For example, in the example code in chapter 5, we can distinguish the following layers:

6.2.1 Testing with a RESTful Client

Isolating the HTTP request can be achieved with a number of clients, both web-based and stand-alone. One of them is POSTMAN which is Chrome plugin used for troubleshooting RESTful APIs.

The image above illustrates POSTMANs basic interface which allows you to specify various headers, query parameters and options, as well as to preview the result in a user-friendly format.

This will test the HTTP layer without any intervention from the development environment or other tools. The next possible point of failure would be the Apache & PHP environments, as well as any tools like cURL.

Tip: For simple GET queries you can use the developer console of your browser (F12 for Chrome) to view the HTTP parameters, headers, cookies and other useful information, but won’t be able to edit the actual request.