Acasta API

Welcome to the Acasta Europe Insurance Policy API Documentation.

Introduction

The Acasta API is a RESTful service that allows you to issue insurance policies on your own website quickly and easily. Whilst we provide examples using PHP you may use any language at your disposal that can send, receive, encrypt and decrypt data using industry standard methods.

Whilst we provide snippets of code examples, you will need a good level of knowledge of the coding language you choose to use.


Requirements

  • Public Encryption Key
  • Account Name
  • Account Password
  • The Current API Version

Once you have completed a successful application to use our API service, you will receive a pack from us with the above details. You will need to keep these details safe and secure. The name and password are unique to you account and are used to securely identify requests from your applications or websites.


Info & Code Highlights

Examples will be shown in blocks similar to the following. All code examples are snippets of relevant code and assume the relevant libraries correctly linked before the code is used.

...
curl_setopt($ch, CURLOPT_URL,"https://api.acastaeurope.co.uk/request/v1.0/policy");
...

Important information will be shown in blocks similar to the following.

Important Information

Pay close attention to these blocks


RESTful End point

The end point for the service is as follows. All requests will be processed at this end point with the required functions appended to the address to complete the request.

End Point

https://api.acastaeurope.co.uk/request

The API is a RESTful service which means every request will need to be accompanied by the correct verb. The main verbs used are GET, POST, PUT and DELETE. Each function listed in the document will have the required verb(s) in an information block.


Further Assistance

If you experience any problems trying to communicate with the API and have followed all the instructions and examples closely then may request further assistance by sending an email to the following address with as much information as possible. The more information you provide the quicker we will be able to assist you. Include as many samples of relevant code and any output from encryption methods.

Support Email Address

brokers@acastaeurope.co.uk

Introduction

To help improve security of personal information all communications with the API are protected using a combination of AES-256bit and RSA encryption. All data must be encrypted using AES and a random key and IV pair. The key and IV pair must then be encrypted using RSA and the public key provided in your welcome pack or available on request.

Most languages have well documented libraries that can be used to provide this encryption. There is no other method of communicating with the API therefore if your chosen language is not able to encrypt the data you will need to pass the information, securely, to another that can.

Encryption

Encryption is a requirement, not an option.

Libraries Used In Examples

PHP

PHP can make use of the OpenSSL extension to provide all the functionality required.


Key And IV Pair

The first step in preparing the data for encryption is to generate a Key and IV pair. This is used by the AES algorithim to encrypt and decrypt the data and should be generated for each request to improve security. This pairing will need to be sent to the API along with the data but must also be encrypted using the RSA algorithm along with the public key as shown later.

// generate a random key and IV
// Note: a key size of 32 bytes will use AES-256 encryption, the IV is 16 bytes long
$key = openssl_random_pseudo_bytes(32);
$iv = openssl_random_pseudo_bytes(16);

Encrypting The Data Using AES

Once you have created the key and IV pair, we can encrypt the data and prepare it for sending to the API. To encrypt the data we simply call the relevant function and pass in the data along with the key and IV pair. Once the data is encrypted we will need to encode the data safe transmission. The various libraries and languages will handle this is different ways but the outcome should be the same.

// use the key and iv to encrypt the data
// output is base 64 encoded already, however we will need to urlencode later
$encrypted = openssl_encrypt($data, 'aes-256-cbc', $key, 0, $iv);

Encrypting The Key And IV Using RSA

Once the data is securely encrypted we need to prepare and encrypt the key and IV pair so that it can be safely and securely sent to the API to be used to decrypt the data. RSA encryption provides the ability to encrypt using a public key which can then only be decrypted using a secret private key that only the API knows. The public key is provided in your welcome pack but is also available on request.

Once encrypted with a public key, decryption can only occur using the secret private key.

Key and IV Pair

The key and IV pair must never be sent in plain form.

// before encrypting the key and iv must be converted into hexadecimal
$keyString = bin2hex($key);
$ivString = bin2hex($iv);

// now encrypt the key and iv using RSA and the public key
// $publicKey is assumed to contain the PEM public key
openssl_public_encrypt($keyString, $keyRsaEncrypted, $publicKey);
openssl_public_encrypt($ivString, $ivRsaEncrypted, $publicKey);

// base64 encode the encrypted key and IV
$key64Encoded = base64_encode($keyRsaEncrypted);
$iv64Encoded = base64_encode($ivRsaEncrypted);

Decrypting Responses

Whilst the status and any possible error codes and messages are in plain text any other response from the API will be encoded and encrypted in a variable called enrypted. To access this information simply decode and decrypt the data using the same Key and IV pair used to encrypt the initial request data.

// $data is assumed to carry the successful return data from a cURL or similar request
//first convert the json string into an object
$response = json_decode($data);
// $response->status contains the result flag of request
// $response->code and $response->message, if present, contain any error information that may have been generated
// $response->encrypted contains all other information as a single urlencoded encrypted json object
// use the key and iv, previously used to encrypt, to decrypt the data
if(($decrypted = openssl_decrypt(urldecode($response->encrypted), 'aes-256-cbc',$key,0,$iv)) !== FALSE){
$decryptedResponseObject = json_decode($decrypted);
//further response information found under individual function sections

}
else{
// handle decrypton error, a likely cause will be the incorrect Key and IV pair
}

Introduction

All requests are handled in the same manor. First prepare a set of headers which will contain the account name along with the encrypted key and IV. The account password must then be encrypted along with all the required data and passed as the request content to the API. The function required will be appended to API end point url as shown in examples below.


Request Headers

The API uses the following additional headers. Setting the Test Mode header to true notifies the system this is a test or development request and the results of the request will be simulated responses.

Acasta API HTTP Headers

x-acasta-encrypted : true
x-acasta-account-name : your Acasta API account name
x-acasta-aes-key : the encrypted AES Key
x-acasta-aes-iv : the encrypted IV key
x-acasta-api-version : the api version you require
x-acasta-test-mode : true or false - optional and the default is false

Test Mode Header

It is important to remember to set this flag to false or remove it when using the live system.


Request Content

The request content is a key value pair object or array formatted as a JSON string before being encrypted. The array must contain your Acasta API account password along with all other fields relevant to the requested function.

Account Password

Always remember to add your Acasta API account password to the content before encrypting.


Request Function

The requested function is dictated partly by the URL end point and partly by the verb. A request to the policy function with the POST or PUT verb notifies the API you wish to create a new policy where as a request to the same function with the DELETE verb will notify the API that you intend to cancel a policy. Similarly a GET verb notifies the API you wish to retrieve information about a previously issued policy. The targeted version number is also part of the request url.

An Example End Point With Version And Function

https://api.acastaeurope.co.uk/request/v1.0/policy


API Version

The API is constantly being developed and therefore possibly changed. Some functions may have different requirements depending on the version of the API. As the API is developed all older versions will be maintained so that websites and applications using those versions will not stop working simply because we released a new version.

We recommend you always use the latest version of the API and update your website(s) and/or application(s) as soon as possible after a new release.

Current API Version

1.0

The API version number is attached to both the request url and the headers. Both must match and must be a valid version before a request will be processed.

Version Syntax

In the request the version number is preceded by the letter v whilst in the header the require value is simply the number.


Interpreting The Response

The response from the API will be a JSON string which you should parse into an object or array. The response will contain at least the status key indicating the result of the request with additional code and message keys if an error occurred.

Response

status : true on success or false if an error occurred.
code : contains an error code if an error occurred
message : contains more detailed information if an error occurred

All error codes and possible solutions are detailed in the error section of this guide.

An Example Request

Below is a example showing a request for a new policy to be issued.

// prepare the data object
$data = [
"account_password" => "password",
...

];
// json encode the data
$jsonData = json_encode($data);
// encrypt the data using previously prepared cipher
...
$encryptedData = openssl_encrypt($jsonData, 'aes-256-cbc', $key, 0, $iv);
...
// prepare a cURL object
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,"https://api.acastaeurope.co.uk/request/v1.0/policy");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"x-acasta-encrypted : true", // always set to true
"x-acasta-account-name : accountname", // your acasta api account name
"x-acasta-aes-key : keyEncrypted", // the encrypted and base 64 aes key
"x-acasta-aes-iv : ivEncrypted", // the encrypted and base 64 aes iv
"x-acasta-api-version : 1.0", // the api version you are targeting
"x-acasta-test-mode : true", // enable test mode

]);
curl_setopt($ch, CURLOPT_POST, TRUE);
//For POST we only need to pass the array, all other verbs we need to http_build_query(), data must always be urlencoded
curl_setopt($ch, CURLOPT_POSTFIELDS,["data"=>urlencode($data)]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,TRUE);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
// set the remaining cURL options
...
...
// process the request
$output = curl_exec($ch);
if(!$output)... // handle cURL error
// decode the returned json object
$response = json_decode($output);
if(isset($response->status) && $response->status == true){
... // handle success
}
else {
... // handle error
}
Post Field

The encrypted data blob is passed to the API as a field called data and must be url encoded.

Introduction

You may request the product pricing information at any time from the API. The data returned will include several variations of the product along with the net rate, Insurance Premium Tax and total. The Insurance Premium Tax and total values are only for evaluation purposes as any commision you add on top will affect both.


Product List

The following is a list of product and their camel case names that must be used for the API to recognise which product you are actioning.

Full List Of Products And Camel Case Names

GAP Insurance - GapInsurance
Motorcycle GAP & RTI - MotorcycleGapRtiInsurance
Taxi GAP & RTI - TaxiGapRtiInsurance
RTI Insurance - RtiInsurance
GAP & RTI Insurance - GapRtiInsurance
Excess Protect Private Motor - ExcessProtectPrivateMotor
Excess Protect Taxi - ExcessProtectTaxi
Excess Protect Motor Trade - ExcessProtectMotorTrade
Excess Protect Commercial Motor - ExcessProtectCommercialMotor
Excess Protect Household - ExcessProtectHousehold
Excess Protect Medical - ExcessProtectMedical
Multi Excess Protect - ExcessProtectLifestyle
Gadget Insurance - GadgetInsurance
Mobile Phone Insurance - MobilePhone
Home Emergency Protect - HomeEmergencyProtect
Landlord Emergency Protect - LandlordEmergencyProtect
Landlord Legal Expenses - LandlordProtect
Family Legal Expenses - FamilyProtect
Motor Legal Expenses - MotorProtect
Motor Breakdown - MotorBreakdown
Sky Warranty Insurance - SkyWarranty
TV Warranty Insurance - TvWarranty
White Goods Warranty Insurance - WhiteGoodsWarranty
Enforcement Agents Protect - EnforcementAgentsProtect
Home Buyers Protect: Safe as Houses - HomeBuyersProtect
Home Sellers Protect: Safe as Houses - HomeSellersProtect
Key Care - KeyCare
Mobile Phone & Tablet Insurance - MobileTabletInsurance
Obligor Mobile Phone & Tablet Insurance - ObligorMobileTabletInsurance


Prices API Address And Verb

All requests to the price api should be sent to https://api.acastaeurope.co.uk/request/v1.0/prices the only verb required is GET as you can only request the current system prices. The only data required, aside from the authorisation data, is an object with a product key containing the camel case product name required.

Prices API Address, Verb and Data Object

Address - https://api.acastaeurope.co.uk/request/v1.0/prices
HTTP Verb - GET
Data Object - product

$data = [
'account_password'=>$account_password,
'product'=>'LandlordEmergencyProtect'

];

Prices Return Array

The returned array of prices will be contained in a key named after the product and will contain all the indemnity options available to your account along with the net rate, Insurance Premium Tax and total values. The Insurance Premium Tax and total are subject to any commission you add on top of the net rate. You can find an example JSON output below.

$data = [
'ExcessProtectCommercialMotor'=>[
[
'indemnity'=>'100.00',
'net_rate'=>'9.00',
'ipt'=>'0.81',
'total'=>'9.81',

],

[
...
],

]

]

Introduction

To issue a new policy we simply need pass all the required fields in a data object to the API using the correct verb and endpoint. If all fields pass validation the policy will be generated and, if requested using the optional parameters, documentation created. Creating the documentation can take a little time so your code should be prepared to wait until it is complete. If validation fails, as with all other requests, you will receive an error result along with any relevant information. The start_date parameter required by all requests is to tell them API when the policy should begin. If you wish the policy to start immediately pass the current date otherwise specify any date in the near future.


Policy API Address And Verb

All requests to the policy api should be sent to https://api.acastaeurope.co.uk/request/v1.0/policy the only verb required is POST as you can currently only request new policies. The data object should contain two fields: the first product key containing the camel case product name required and the second policy containing the policy information such as name and address.

Policy API Address, Verb and Data Object

Address - https://api.acastaeurope.co.uk/request/v1.0/policy
HTTP Verb - POST
Data Object Product - product
Data Object Policy - policy

$data = [
'account_password'=>$account_password,
'product'=>'ExcessProtectCommercialMotor',
'policy'=>[
'first_name'=>$firstName,
'surname'=>$surname,
'address_1'=>$address1,
'address_2'=>$address2,
'town_city'=>$townCity,
'postcode'=>$postcode,
'telephone'=>$telephone,
'email'=>$email,
'start_date'=>$start,
'vehicle_registration'=>$vehicle_registration,
'total'=>200,

],
'email_documentation'=>true,
'return_documentation'=>false,

];

Optional Parameters

There are two optional parameters you may pass to the API. Both default to false however can be used to indicate to the API how you wish documentation to be handled. You may use any or both for any request.

Optional Parameters

email_documentation : true or false Used to ask the API to email the documentation to the client. Requires a valid email address to be passed to the API in the request.
return_documentation : true or false Used to ask the API to return the pdf documentation as part of the return array.


Policy Return Array

If successful, the API will return an array similar to the example below. The main fields to take notice of are the policy_id and the documentation fields. The policy_id will contain the policy number for the new policy to be used for further queries or claims in the future. The documention field will contain the url encoded PDF data for the policy, if requested using the optional parameter. To correctly access the PDF always decode the data before saving to file.

Optional Parameters

product : Will match the product sent in the initial request.
policy_id : Contains the new policy number.
total : Will match the total sent in the initial request.
ipt : The calculated Insurance Premium Tax for this policy.
commission : Your calculated commission for this policy.
net_rate : The net rate for the selected indemnity of the product.
documentation_emailed : true or false indicates the result of the email process. Only sent if request using the optional parameter.
documentation : Contains the document array with the filenames as keys and data as the values of the array. Only sent if requested using the optional parameter. It is important to remember the PDF data is url encoded and must be decoded first.
extra : Contains any extra data relevant to the product selected.

$data = [
'product' => 'ExcessProtectCommercialMotor'
'policy_id' => 'POLICYNUMBER'
'total' => '200'
'ipt' => '16.51'
'commission' => '157.71'
'net_rate' => '25.78'
'documentation_emailed' => true
'documentation'=> [
$filename => $data,
...

],
'extra'=>[
...
],

];

Product Specific Extras

If a product has extra return data, for example the Landlord Protect product can be combined with a Rent Guarantee policy, then all extra data will be returned in the field extra.

Introduction

If an error occurs whilst processing your request an error code and short description will be returned in the reponse object. A list of the error codes and common causes can be found below.


Error Codes

Error Codes and Common Causes

1000: API version in header does not match API version in request url
1001: Header missing or invalid: x-acasta-encrypted
1002: Header missing or invalid: x-acasta-account-name
1003: Header missing or invalid: x-acasta-aes-key
1004: Header missing or invalid: x-acasta-aes-iv
1005: Header missing or invalid: x-acasta-api-version
1006: Header invalid: x-test-mode

1100: Missing data field in post content
1101: Error decrypting the AES Key
1102: Error decrypting the AES IV
1103: Error decrypting the data

1110: An error occurred encrypting the response object

1200: Missing password field in data object
1201: Account name can not be matched to an existing account
1202: Account password is invalid
1203: Account does not have permission to use this API
1204: Account does not have permission to use this action of the API

1300: Missing required request object
1301: Request object did not pass validation
1302: Product is not currently enabled for your account

1400: An error occurred please try again later

2000: An unexpected server error has occurred, please try again later