Paymentshield REST API Reference

These are the docs for the Paymentshield REST API, which allows integrators to quote, sell, and deliver Paymentshield insurance policies in a secure and accessible way.

Our API is composed of a number of services separated by function but accessed through one easy URL scheme.

All API endpoints:

Environments

The code samples on this page use the UAT environment, which you should use to develop your integration. When you go to production, use the Live environment, which will create real quotes and policies in our live system.

General API Principles

• All message bodies (requests and responses) are raw JSON: set content-type header to application/json
• We currently use verbs GET and POST:
  • GET is idempotent, with no side-effects.
  • POST is used for functions which have an effect on system and data state.
• Responses have an informative HTTP Status:
  • 200 OK
  • 201 Created
  • 400 Bad Request
  • 401 Unauthenticated
  • 403 Forbidden
  • 500 Server Error
• Response bodies have an additional StatusCode field to give fine-grained error information
• Response bodies will have an array of Messages which is populated if there are problems with the data you send us
• Swagger (OpenAPI) definitions are available for each service upon request

Error Handling

{
    "StatusCode": "ClientError",
    "Messages":
    [
        {
            "MessageType": "Authentication",
            "Summary": "Sorry, we couldn’t log you in with those details. Please check and try again"
        }
    ]
}

This is how we use HTTP status codes:

In many cases, we return additional information in the JSON response body in the StatusCode and Messages parameters.

StatusCode

MessageType

Version History

Version 2024-01-28

We refreshed our Home product, improving cover levels and amending some questions.

• New Home Insurance ProductId 1015, which replaces 1008.
• New question set 167, which replaces 157.
• From 2024-01-28, all new requests for quotes should target the new ProductId.
• We recommend that you use Quote API v2 to create and retrieve quotes on the refreshed product, see Version 2023-02-05
  • If you use v1, you can quote and sell with a full API integration, but you can't hand over to our Quote & Buy web journey.

Please check the updated Reduced Question Set Defaults.

🌠 We are now providing a Postman collection with examples of how to authenticate, quote, apply, and get docs and catalogue data for the home product.

Version 2023-12-17

Tenants Contents Monthly

We moved our Tenants Contents product to a monthly subscription model.

• New Tenants Contents ProductId 1014, which replaces 1013.
• New question set 158, which replaces 148.

QuickQuote v2

• All QuickQuotes will now proceed into our modernised Quote & Buy journey (root URL of https://quote.paymentshieldadviserhub.co.uk/)
• New /v2/QuickQuote route, which will return a v2 shaped model (see notes for 2023-02-05 below)
• All QuickQuotes can now benefit from a deeper set of assumptions, as the mandatory answers required for a quick quote have been reduced. This is a non-breaking change, as you may continue to send as much data as you have, to refine the indicative price (we call this "flexible quick quote").

The QuickQuote docs have been revised and updated.

Version 2023-02-05

API v2 Routes were added for integration with new "reduced question sets". See Reduced Question Set Defaults.

New question set version 157 for Home, which replaces 147.

For the new /v2 routes, the following changes apply:

• Quote Request:
  • UseDefaults is no longer needed.
• Quote Response:
  • Added QuestionSetId
  • Added BranchNumber
  • Added CallChannelType
  • Removed QuoteSessionContinuationUri
  • Added CoverSelections
  • Answer.Source will now show "Default" for values that were defaulted due to the reduced question journey.
  • QuoteRequestContinuationUri values are based around a root URL of https://quote.paymentshieldadviserhub.co.uk/
  • If CommissionSacrifice is set to a non-zero value, then as well as the Premiums collection, you will also receive an OriginalPremiums collection. The former refers to the reduced amounts and the latter refers to the original full amounts. If you do dynamic CommissionSacrifice calculations in your frontend, base them on OriginalPremiums (otherwise you'll be reducing the price twice).
• Apply Request:
  • Added IsPartialApply (bool) which works like IsPartialQuote - allowing you to save Application stage data without submitting the application.

Additionally, the following global changes apply:

• Each Answer object will always have a Source property. See Quote Response - Answers Array.

Version 2021-12-12

• New question set versions, which include an AutoRenewalConsent question, for FCA compliance:
  • Home: 145 (STD), 147 (VC)
  • Landlords: 137
  • Tenants Contents: 143
  • Tenants Liability: 141
  • Rent Protection: 142

Version 2021-03-08

• Rent Protection version 136 - Moved email address to application stage
• Added document delivery preference
• Changed the validation on 'NewLetOrProductTransfer'.
• Please note update to the product specific rules summary.

Version 2020-09-16

• Tenants Contents version 133 – Refreshed product with replacement of Applicant1Occupation and Applicant2Occupation with Applicant1Student and Applicant2Student

Version 2020-08-02

• Add /Catalogue/SdnTemplate endpoint
• Add /SDN endpoint
• Document the cofc Confirmation of Cover document for Tenants Contents
• Document deferred payment frequencies

Version 2020-07-27

• Rent Protection version 89 – Refreshed product with updates to Eligibility Stage questions and validation rules for TermOfInsurance and MonthlyRent
• Landlords version 127 – Refreshed product reintroducing the RentGuarantee add-on

Version 2020-05-31

• Allow UserReference in request and response for GET Quote, POST Quote, POST Quote/{id}, and POST Quote/{id}/Apply
• Allow CommissionSacrifice in request and response for POST Quote/{id}/Apply
• Introduce GET Quotes feature to search quotes
• Introduce POST /Security/Refresh
• Public release of Update and Edit Quote features
• Flexible handling of extra answers in request for POST QuickQuote

Authentication

<?php

$data = [
    'Email' => '[email protected]',
    'Password' => 'BrokerPassword'
];

$url  = 'https://apiuat.paymentshield.co.uk/Security/Login';
$json = json_encode($data);
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => $url,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => $json,
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ]
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

$response = $err
    ? "cURL Error $err"
    : $response;

POST https://apiuat.paymentshield.co.uk/security/login HTTP/1.1
Content-Type: application/json
{
    "Email": "[email protected]", 
    "Password": "BrokerPassword"
}

Replace the Email and Password fields with your credentials.

POST https://apiuat.paymentshield.co.uk/security/login HTTP/1.1
Content-Type: application/json
{
    "UserId": "123456", 
    "Passkey": "aaaaaaaa"
}

You can use UserId and Passkey authentication instead of email and password. The UserId is also known as Seller Number.

We have a custom authentication scheme due to our internal system; we don't use OAuth or similar.

The general flow of authentication is like this:

1. Authenticate by POSTing either email+password or userid+passkey in a JSON body to the Login endpoint
2. We'll send back a response containing your UserId (a constant, unique integer ID) and a session Token (GUID) which is valid for 40 minutes. The Token's validity is reset to the full time whenever it is used for an authenticated API call. You can store the Token in local storage within your app.
3. You should know your SystemId, a GUID identifying the piece of software calling the API. This is somewhat like an API key (with the UserId and Token together forming a kind of API secret).
4. In all subsequent requests to any of our API services, send the UserId, Token, and SystemId in HTTP headers.

Login

To login, POST to the /Security/Login endpoint as shown in the code samples on the right.

Token Refresh

We provide a Token Refresh endpoint to function as a "keep alive", which will renew your session active time, extending the session. It is essentially a no-op, and your session token will stay the same.

We recommend you build this into your integration, for example on button presses, to avoid having to log users back in regularly.

POST to the /Security/Refresh endpoint with the usual security headers and no body. The response will be a simple JSON body with a StatusCode of OK. If the session has already expired, you will receive the usual 401 error with status AuthenticationRefused.

Quote Service

You can use the Quote Service to get Quotes and QuickQuotes and retrieve those you created earlier. The Quote service relies upon some external services to PSL to get prices, which can mean it takes a while to get prices, particularly for complex quotes featuring multiple tiers of cover.

Integration Types

Full vs Partial integration

We use the term 'full integration' to mean integrations which complete a Quote & Buy journey using only API endpoints. In contrast, a 'partial integration' gets a quote or quick quote from the API and then uses a ContinuationUri that we provide to transfer the user for them to complete the journey in our Adviser Hub web frontend.

v1 and v2

The Quote API v2 is used for our "reduced question set" journey. Currently this applies only to Home, but will be extended in future.

Reduced question sets allow you to send fewer Answer values than are usually required by:

• Filling Default Answers - see Reduced Question Set Defaults
• Supplementing your data with Third Party data results (This feature is coming later in 2023 for integrators.)

There are v2 routes for the following endpoints:

• POST v2/Quote/
• POST v2/Quote/{guid}/Apply
• POST v2/Quote/{int}/SaveResultsStage (New)

For an overview of differences in v2 payloads, see the Version History section

QuoteRequests and Quotes

A QuoteRequest is a well-defined request for cover which we submit to one or more insurers. QuoteRequests have integer IDs (QuoteRequestId). If insurers can provide prices for the specified cover, we return these in the response and refer to each insurer offer as a Quote, which has a QuoteId - a GUID. A customer can apply for a Quote.

Create Quote

POST to the /Quote endpoint to create a quote.

<?php

// Use the token from your login response
$userId = 123456;
$token = '9c92d88f-d28f-4eb6-8e69-f96707113544';
$systemId = '56cba828-1376-4ced-96d4-11a950e4afe8';

$data = [
  'ProductId' => 1010,
  'BranchNumber' => 'PS180092',
  'UseDefaults': true,
  'IsIndicativeQuote': false,
  'CommissionSacrifice': 0,
  'UserReference' => 'MyRef_123',
  'Answers': [
    ['InterfaceKey' => 'Applicant1Title', 'Value' => 'Miss'],
    ['InterfaceKey' => 'Applicant1Forename', 'Value' => 'Jessica'],
    ...
  ]
];

$url  = 'https://apiuat.paymentshield.co.uk/Quote';
$json = json_encode($data);
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => $url,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => $json,
  CURLOPT_HTTPHEADER => [
  "Content-Type: application/json",
  "UserId: $userId",
  "Token: $token",
  "SystemId: $systemId",
  ]
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

$response = $err
  ? "cURL Error $err"
  : $response;

POST https://apiuat.paymentshield.co.uk/Quote/ HTTP/1.1
Content-Type: application/json
UserId: 123456
Token: 9c92d88f-d28f-4eb6-8e69-f96707113544
SystemId: 56cba828-1376-4ced-96d4-11a950e4afe8

{
  "ProductId": 1015,
  "BranchNumber": "AB000000",
  "UseDefaults": true,
  'IsIndicativeQuote': false,
  "CommissionSacrifice": 0,
  "UserReference": "MyRef_123",
  "Answers": [
    {
      "Value": "Mrs",
      "InterfaceKey": "Applicant1Title"
    },
    {
      "Value": "Kayleigh",
      "InterfaceKey": "Applicant1Forename"
    },
    {
      "Value": "Porter",
      "InterfaceKey": "Applicant1Surname"
    },
    ...
    {
      "Value": "One",
      "InterfaceKey": "NumberOfBedrooms"
    },
    {
      "Value": "Flat",
      "InterfaceKey": "PropertyType"
    },
    ...
  ]
}

Create a new full Quote Request. A Quote Request is our term for a well-specified request for insurance quotes, for a given customer, based on the customer information you provide. As long as your request provides valid answers to all mandatory questions, a Quote Request will be created in our database and we will pass back a QuotesResponse with a QuoteRequestId. From here, you can continue the user journey in our web frontend using the ContinuationUri in the response.

You can find the types and examples of each request field in the Swagger definition of the API.

Please see the code pane for an example of the HTTP headers and JSON request you should send. The fields we require in the request are explained in more detail below:

ProductId

The four-digit ID of a Paymentshield product offering. Not all integrators can sell the full range of products. If you want to be authorised to sell a different range of products, please get in touch. To browse products and their related question sets, please see the Question Sets section at the bottom of the page.

BranchNumber

The BranchNumber is provided as part of a user's configuration in our back end system. To create a Quote Request a user must be authorised to sell the product under the branch number you send in the request.

UseDefaults

v1: Please set UseDefaults to true. It sets some Answers to their sensible default or calculated value if you don't specify one.

v2: Not required - do not include this field in payload.

CallChannelType

Optional - your integration may require you to set this to get custom behaviour for your network. Speak to your PSL contact.

If omitted, defaults to "External".

IsIndicativeQuote

If set to true, the quotes are "indicative" prices only, and cannot be applied for.

If omitted, defaults to false. We recommend that you do not include this field.

CommissionSacrifice

The maximum amount of commission that can be sacrificed by a user is provided as part of a user's configuration in our back end system. The value sent in the CommissionSacrifice field must not exceed the maximum for the user/branch number combination.

If omitted, defaults to 0.

UserReference

You can pass an optional UserReference field in a quote request to allow you to identify the quote as per your own requirements. For example, a customer or fact find reference from your system.

The UserReference will be returned in the Quote Response and can be used to search for quotes using a GET Quotes request.

IsPartialQuote

Setting IsPartialQuote to true allows you to save quote progress:

• Validation is not attempted
• Quoting (getting prices) is not attempted
• The quote will remain in the INPROGRESS state, even if you answered all mandatory questions. This allows you to add non-mandatory answers before requesting the full quote response.

If omitted, defaults to false.

See also Create Partial Quote.

v2: If IsPartialQuote is true, we do not fill in the Default answers.

Answers

This is the main substance of your request. Each Answer is a struct of InterfaceKey, Value, and perhaps RepeatingQuestionSetIndex (if the answer is part of a list). Each product has a certain number of mandatory answers that must be provided to get a quote. You can submit an incomplete quote if you set the IsPartialQuote flag to false. See Create Partial Quote.

Repeating/multi-part Answers

Example request with multi-part answers

{
  "ProductId": 1015,
  "BranchNumber": "AB000000",
  "UseDefaults": true,
  "IsIndicativeQuote": false,
  "CommissionSacrifice": 0,
  "Answers": [
    ...
    {
      "Value": "true",
      "InterfaceKey": "ContentsItemsToSpecify"
    },
    {
      "Value": "ComputerEquipment",
      "InterfaceKey": "SpecifiedItemType",
      "RepeatingQuestionSetIndex": 0
    },
    {
      "Value": "High Performance PC",
      "InterfaceKey": "SpecifiedItemDescription",
      "RepeatingQuestionSetIndex": 0
    },
    {
      "Value": "3000",
      "InterfaceKey": "SpecifiedItemValue",
      "RepeatingQuestionSetIndex": 0
    },
    {
      "Value": "JewelleryOrWatches",
      "InterfaceKey": "SpecifiedItemType",
      "RepeatingQuestionSetIndex": 1
    },
    {
      "Value": "Watch",
      "InterfaceKey": "SpecifiedItemDescription",
      "RepeatingQuestionSetIndex": 1
    },
    {
      "Value": "3000",
      "InterfaceKey": "SpecifiedItemValue",
      "RepeatingQuestionSetIndex": 1
    },
    ...
  ]
}

Some of our products have questions that allow repeating answers and have multiple parts to the answer. An example of this is ContentsItemsToSpecify, which, when set to true, requires at least one group of the following answers:

You must send all three answers for the specified item to be added to the quote.

To add a second specified item, you would include another group of answers to these three questions, marked with an incremented RepeatingQuestionSetIndex of 1.

Each set of multi-part answers, whether for specified items, personal possessions, or previous claims, must have a globally unique integer value for RepeatingQuestionSetIndex. For example, you should not use 0 to mark both a Personal Possession and a Previous Claim; they should have different indices:

Strategies for unique RepeatingQuestionSetIndex

Here are two strategies for setting correct values for RepeatingQuestionSetIndex in your integration:

1. You could keep a global count of repeating sections in your state store and apply it to the corresponding Answer nodes in your request
2. You could assume a maximum for each repeating group and treat it as an offset, so that all SpecifiedItems begin at 0, PersonalPossessions begin at 10, and PreviousClaims begin at 20, for example.

The numbering of RepeatingQuestionSetIndex in our response will always start at 0, even if your request started at 1 (or higher). Our numbering in the response will be contiguous (i.e. no gaps in numbering starting from 0) even if your request had gaps.

The example in the code pane shows how to add two specified items to a quote - in this case a PC and a Watch.

Quote Response

Example Quote Response

{
    "StatusCode": "OK",
    "Messages": [],
    "CallChannelType": "External",
    "BranchNumber": "AB102030",
    "CoverSelections": {
        "BuildingsAD": "Excluded",
        "ContentsAD": "Excluded"
    },
    "QuestionSetId": 167,
    "MaxCommissionSacrifice": 25.00,
    "QuoteRequestId": 5228480,
    "QuoteReference": "PSL-BCHI-5228480",
    "QuoteStatus": "QUOTESRETRIEVED",
    "ProductId": "1015",
    "QuoteSessionId": "3ac30f5e-096c-445e-8890-edda3eab76a6",
    "QuoteRequestContinuationUri": "https://uat-quote.paymentshieldadviserhub.co.uk/?userId=123456&token=5a862c13-a2b7-473e-8687-1f9a71bcf703&quoteRequestId=5228480",
    "QuoteDate": "2024-01-19T10:08:51+00:00",
    "QuoteExpiryDate": "2024-07-17T00:00:00+01:00",
    "IsMultiTier": true,
    "IsIndicativeQuote": false,
    "CommissionSacrifice": 0.0,
    "IptRate": 0.120,
    "LinkedQuotes": [],
    "Quotes": [
        {
            "QuoteId": "01f860b2-18e8-42dd-935b-ba7a76d3f7d1",
            "InsurerName": "ABC",
            "ProductName": "Home Insurance",
            "QuoteExpiryDate": "2024-07-17T00:00:00+01:00",
            "Cover": {
                "IsRequested": true,
                "BuildingsAD": "Excluded",
                "ContentsAD": "Excluded",
                "BuildingsCoverLevel": 1000000.0,
                "ContentsCoverLevel": 75000.0
            },
            "Premiums": [
                {
                    "PaymentMethod": "DirectDebit",
                    "PaymentFrequency": "Annual",
                    "PaymentFrequencyDescription": "Annually",
                    "PriceID": "8ec4f88a"
                },
                {
                    "PaymentMethod": "CreditCard",
                    "PaymentFrequency": "Annual",
                    "PaymentFrequencyDescription": "Annually",
                    "PriceID": "8ec4f88a"
                },
                {
                    "PaymentMethod": "DebitCard",
                    "PaymentFrequency": "Annual",
                    "PaymentFrequencyDescription": "Annually",
                    "PriceID": "8ec4f88a"
                },
                {
                    "PaymentMethod": "DirectDebit",
                    "PaymentFrequency": "Monthly3MonthsDeferred",
                    "PaymentFrequencyDescription": "Monthly",
                    "CreditDetails": {
                        "Apr": 23.70,
                        "CreditCharge": 69.16,
                        "FixedInterestRate": 15.11,
                        "InitialPayment": 58.52,
                        "NumberOfSubsequentPayments": 8,
                        "SubsequentPayments": 58.54
                    },
                    "PriceID": "e6846f35"
                },
                {
                    "PaymentMethod": "DirectDebit",
                    "PaymentFrequency": "Monthly",
                    "PaymentFrequencyDescription": "Monthly",
                    "CreditDetails": {
                        "Apr": 23.70,
                        "CreditCharge": 54.92,
                        "FixedInterestRate": 12.00,
                        "InitialPayment": 42.68,
                        "NumberOfSubsequentPayments": 11,
                        "SubsequentPayments": 42.72
                    },
                    "PriceID": "b0380cf2"
                }
            ],
            "Endorsements": []
        },
        {
            "QuoteId": "3a8ee81e-a588-4be2-afd7-80bb716fb918",
            "InsurerName": "ABC",
            "ProductName": "Home Insurance",
            "QuoteExpiryDate": "2024-07-17T00:00:00+01:00",
            "Cover": {
                "IsRequested": false,
                "BuildingsAD": "Excluded",
                "ContentsAD": "Included",
                "BuildingsCoverLevel": 1000000.0,
                "ContentsCoverLevel": 75000.0
            },
            "Premiums": [
                ...
            ],
            "Endorsements": []
        },
        ...
    ],
    "Prices": [
        {
            "ID": "8ec4f88a",
            "Values": {
                "TotalCostPerPaymentPeriod": 457.68,
                "TotalPremiumIncludingIPT": 457.68,
                "TotalPremiumExcludingIPT": 412.50,
                "AdministrationCharge": 36.00,
                "InsurancePremiumTax": 45.18,
                "HouseholdInsurancePremiumExcludingIPT": 376.50,
                "HomeEmergencyPremiumExcludingIPT": 0.0,
                "LegalExpensesPremiumExcludingIPT": 0.0,
                "BuildingsCoverGrossExcludingIPT": 255.79,
                "ContentsCoverGrossExcludingIPT": 120.71,
                "PersonalCoverGrossExcludingIPT": 0.0,
                "TotalAmountPayable": 457.68
            }
        },
        {
            "ID": "e6846f35",
            "Values": {
                "TotalCostPerPaymentPeriod": 58.54,
                "TotalPremiumIncludingIPT": 457.68,
                "TotalPremiumExcludingIPT": 412.50,
                "AdministrationCharge": 36.00,
                "InsurancePremiumTax": 45.18,
                "HouseholdInsurancePremiumExcludingIPT": 376.50,
                "HomeEmergencyPremiumExcludingIPT": 0.0,
                "LegalExpensesPremiumExcludingIPT": 0.0,
                "BuildingsCoverGrossExcludingIPT": 255.79,
                "ContentsCoverGrossExcludingIPT": 120.71,
                "PersonalCoverGrossExcludingIPT": 0.0,
                "TotalAmountPayable": 526.84
            }
        },
        {
            "ID": "b0380cf2",
            "Values": {
                "TotalCostPerPaymentPeriod": 42.72,
                "TotalPremiumIncludingIPT": 457.68,
                "TotalPremiumExcludingIPT": 412.50,
                "AdministrationCharge": 36.00,
                "InsurancePremiumTax": 45.18,
                "HouseholdInsurancePremiumExcludingIPT": 376.50,
                "HomeEmergencyPremiumExcludingIPT": 0.0,
                "LegalExpensesPremiumExcludingIPT": 0.0,
                "BuildingsCoverGrossExcludingIPT": 255.79,
                "ContentsCoverGrossExcludingIPT": 120.71,
                "PersonalCoverGrossExcludingIPT": 0.0,
                "TotalAmountPayable": 512.60
            }
        },
        ...
    ],
    "Answers": [
        {
            "InterfaceKey": "SecondApplicantIncluded",
            "Value": "False",
            "Source": "User"
        },
        ...
        {
            "InterfaceKey": "PropertyType",
            "Value": "Terraced",
            "Source": "ThirdParty"
        },
        {
            "InterfaceKey": "NumberOfBedrooms",
            "Value": "Three",
            "Source": "ThirdParty"
        },
        {
            "InterfaceKey": "NumberOfBathrooms",
            "Value": "One",
            "Source": "ThirdParty"
        },
        {
            "InterfaceKey": "BuildYear",
            "Value": "1944",
            "Source": "ThirdParty"
        },
        ...
        {
            "InterfaceKey": "BuildingsCoverLevel",
            "Value": "OneMillion",
            "Source": "Default"
        },
        {
            "InterfaceKey": "AccidentalDamageBuildings",
            "Value": "False",
            "Source": "Default"
        },
        {
            "InterfaceKey": "ExcessBuildings",
            "Value": "TwoHundredAndFifty",
            "Source": "Default"
        },
        {
            "InterfaceKey": "AccidentalDamageContents",
            "Value": "False",
            "Source": "Default"
        },
        {
            "InterfaceKey": "ExcessContents",
            "Value": "TwoHundredAndFifty",
            "Source": "Default"
        },
        {
            "InterfaceKey": "PersonalPossessionsToSpecify",
            "Value": "False",
            "Source": "Default"
        },
        ...
    ]
}

A successful Quote response includes the following information:

Quotes array

For each insurer quote we receive, we return the following data:

Prices array

For each unique PriceId returned in Quotes, we provide a breakdown of values relevant to the product:

Answers array

We replay back to you the Answers which you submitted, and may include assumed (default) answers which we have filled in.

Continuation URI

For 'Partial Integrators', who wish to create a quote but transfer the user to our web journey to complete the Quote & Buy journey, we provide ContinuationUris in the Quotes response. As long as the User has activated their Adviser Hub account the URI provides a silent logon to our Quote & Buy application. You may encounter three types of ContinuationUris:

↓ Jump to next section

Create Partial Quote

JSON showing the IsPartialQuote parameter used to create a Partial Quote

{
  "ProductId": 1015,
  "BranchNumber": "AB102030",
  "IsPartialQuote": true,
  "CommissionSacrifice": 0,
  "Answers": [
    {
      "InterfaceKey": "CoverType",
      "Value": "BuildingsAndContents"
    }
  ]
}

There are two main reasons that you might build your integration to submit 'partial' quote requests:

1. If you want to start a quote with a small amount of information, save it, and update it with more information when available.
2. If you want to capture some information in your application, and transfer to our web frontend to complete the Quote & Buy journey.

If you set IsPartialQuote to true in a POST Quote request, then we skip part of the validation logic, so that the request is not refused, but instead returns a response where the QuoteStatus is INPROGRESS.

In the response, you will receive a QuoteRequestId and a QuoteSessionContinuationUri that you can use to transfer to our Quote & Buy journey to complete the remaining questions and obtain a full quote. When you transfer to our journey the answers you provided will be pre-populated.

See also IsPartialQuote parameter.

Update a Partial Quote

You can send updates to a Partial Quote by POSTing to the /Quote endpoint specifying the QuoteRequestId to be updated.

For example, to update the QuoteRequestId 641234, the endpoint is /Quote/641234.

You can use the update function to add more information to a QuoteRequest, or change answers previously sent. The update is not a differential; it will completely replace the existing answers for the QuoteRequest. If you exclude Answers from your update which were previously set, this will effectively remove them.

Create QuickQuote

Create a QuickQuote

POST https://apiuat.paymentshield.co.uk/QuickQuote/ HTTP/1.1
Content-Type: application/json
UserId: 123456
Token: 9c92d88f-d28f-4eb6-8e69-f96707113544
SystemId: 56cba828-1376-4ced-96d4-11a950e4afe8

{
  "ProductId": 1015,
  "BranchNumber": "AB000000",
  "UseDefaults": true,
  "UseThirdPartyData": true,
  "CommissionSacrifice": 0,
  "Answers": [
    {
      "Value": "Carrie",
      "InterfaceKey": "Applicant1Forename"
    },
    {
      "Value": "Palmer",
      "InterfaceKey": "Applicant1Surname"
    },
    {
      "Value": "29/01/1993",
      "InterfaceKey": "Applicant1DoB"
    },
    {
      "Value": "93 Normal Street",
      "InterfaceKey": "InsuredAddressStreet"
    },
    {
      "Value": "PR8 1AA",
      "InterfaceKey": "InsuredAddressPostcode"
    },
    {
      "Value": "Southport",
      "InterfaceKey": "InsuredAddressTown"
    }
  ]
}

A QuickQuote is an indicative price which you can get by submitting less information about the customer. You can allow your customer to pick up their QuickQuote journey in our frontend using the QuickQuoteContinuationUri.

Today, QuickQuote is only implemented for Home Insurance.

You must supply the following answers as a minimum:

• Applicant1Forename
• Applicant1Surname
• Applicant1DoB
• InsuredAddressPostCode
• InsuredAddressStreet
• InsuredAddressTown
• PropertyType*
• NumberOfBedrooms*
• BuildYear*

*See 'Third Party Property Data' below.

We add assumptions for all other mandatory questions in order to return a price. The assumptions we use are replayed back to you in the Quick Quote Response.

Please see the code pane for an example of QuickQuote request message.

Flexible Quick Quote

If you have more information available than the above list of minimum data requirements you can send additional answers. The more information you are able to provide in the quick quote request the more accurate the quote response will be.

Third Party Property Data

If you send the UseThirdPartyData parameter with a value of true in a POST QuickQuote request, you can omit the following three fields from the QuickQuote request:

• PropertyType
• NumberOfBedrooms
• BuildYear

We will use the address details sent in the request to call a third party data provider to source the property details which will then be added to the request.

If omitted, UseThirdPartyData defaults to false.

QuickQuotesResponse

We deliver a QuickQuotesResponse in response to both the 'Create' and 'Get' QuickQuote operations. This object has some differences from a normal QuotesResponse:

• It has a QuickQuoteContinuationUri instead of QuoteRequestContinuationUri or QuoteSessionContinuationUri.
• Only the cheapest Price is returned, instead of many prices.
• Each Answer has a Source field, containing:
  • 'User' if supplied in the request,
  • 'ThirdParty' if the value is from an external data provider,
  • 'Assumed' if the value is an assumption (v1 API),
  • 'Default' if the value is an assumption (v2 API).

Error returned when unable to source ThirdPartyData

{
    "StatusCode": "NoDataWarning",
    "Messages": [
        {
            "MessageType": "Error",
            "Summary": "Sorry, we couldn't find any information for that property"
        }
    ]
}

If you send the UseThirdPartyData parameter with a value of true and we are unable to source the property data we will return an error response as per the example provided.

Edit Quote

You can create a new version of a quote linked to an existing QuoteRequestId by POSTing to the /Quote endpoint specifying the QuoteRequestId to link the new quote to.

For example, to create a new QuoteRequestId that is linked to the existing QuoteRequestId 645678, the endpoint is /Quote/645678.

Use the edit function to create variants of a quote for a single customer. As the quotes are Linked it is only possible to apply for one of them. This removes the chance of inadvertently creating multiple policies for a single customer.

The edit function creates a totally new QuoteRequestId so the request should include all required information and not just the answers that have been changed from the original.

Retrieve Quote

Retrieve a set of Quotes by QuoteRequestId

GET https://apiuat.paymentshield.co.uk/Quote/{QuoteRequestId} HTTP/1.1
UserId: 123456
Token: 9c92d88f-d28f-4eb6-8e69-f96707113544
SystemId: 56cba828-1376-4ced-96d4-11a950e4afe8

Retrieve a fully-hydrated Quote Response from a previously created quote. This allows you to show your user up-to-date quote state and whatever values they filled in originally. You can use this feature to resume a journey. Because we store the full quote information associated with a QuoteRequestId, you don't have to store full quote information in your database; you can look it up with this operation.

Pass the integer QuoteRequestId from the original Quote Response.

Linked Quotes

Example of LinkedQuotes in a GET Quote Response

{
    "StatusCode": "OK",
    "Messages": [],
    "CallChannelType": "External",
    "BranchNumber": "PS180092",
    "CoverSelections": {
        "BuildingsAD": "Excluded",
        "ContentsAD": "Excluded"
    },
    ...
    "LinkedQuotes": [
        {
            "QuoteRequestId": 5228538,
            "Link": "https://apiuat.paymentshield.co.uk/v2/Quote/5228538",
            "QuoteStatus": "QUOTESRETRIEVED",
            "QuoteDate": "2024-01-19T11:50:32.52",
            "QuoteRequestContinuationUri": "https://uat-quote.paymentshieldadviserhub.co.uk/?userId=123456&token=4b862c13-a2b7-473e-8687-1f9a71aaf702&quoteRequestId=5228538",
            "IsApplied": false
        },
        {
            "QuoteRequestId": 5228539,
            "Link": "https://apiuat.paymentshield.co.uk/v2/Quote/5228539",
            "QuoteStatus": "QUOTESRETRIEVED",
            "QuoteDate": "2024-01-19T11:52:37.617",
            "QuoteRequestContinuationUri": "https://uat-quote.paymentshieldadviserhub.co.uk/?userId=123456&token=4b862c13-a2b7-473e-8687-1f9a71aaf702&quoteRequestId=5228539",
            "IsApplied": false
        }
    ],
    ...
}

There are two ways to create linked quotes:

1. When your user transfers to our Quote & Buy journey (using one of the above continuation URIs), it is possible for them to use features on our website to create variations of the quote.
2. Using the Edit Quote function to create a new variant of a quote linked to another QuoteRequestId.

In both cases, each quote variant is given its own unique QuoteRequestId. We will return details of all linked quotes when you next perform a Get Quote request. Please see the code pane for an example where the user has created three linked quotes and has applied for a quote within 640113. Note that each QuoteRequestId has its own QuoteStatus. Only one of the linked quotes can have a status of SUBMITTED.

QuoteStatus Codes

You may encounter the following QuoteStatus codes in a Get Quote response:

Retrieve QuickQuote

Retrieve a QuickQuote the same way you retrieve a Quote

GET https://apiuat.paymentshield.co.uk/Quote/{QuoteRequestId} HTTP/1.1
UserId: 123456
Token: 9c92d88f-d28f-4eb6-8e69-f96707113544
SystemId: 56cba828-1376-4ced-96d4-11a950e4afe8

You can retrieve a QuickQuote the same way you would Retrieve a quote, passing the integer QuoteRequestId from the original QuickQuote Response.

If the user has progressed a QuickQuote by adding information, so that it now has many prices, then we return a full QuotesResponse.

Search Quotes

Search for Quotes by UserReference

GET https://apiuat.paymentshield.co.uk/Quotes/?UserReference=YourRef_123 HTTP/1.1
UserId: 123456
Token: 9c92d88f-d28f-4eb6-8e69-f96707113544
SystemId: 56cba828-1376-4ced-96d4-11a950e4afe8

Example of GET Quotes response

{
    "StatusCode": "OK",
    "Messages": [
        {
            "MessageType": "ResultsLimited",
            "Summary": "We've limited the number of results to 100"
        }
    ],
    "Results": [
        {
            "QuoteRequestId": 634560,
            "Link": "https://apiuat.paymentshield.co.uk/Quote/634560",
            "QuoteStatus": "SUBMITTED",
            "QuoteDate": "2020-01-30T11:20:31.343",
            "Applicant1Surname": "Matip",
            "Applicant1DoB": "1970-05-01T00:00:00+01:00",
            "Postcode": "PR9 0SL",
            "ProductId": "1008",
            "ApplicationRef": "PSL-INT-9005780"
        },
        {
            "QuoteRequestId": 634562,
            "Link": "https://apiuat.paymentshield.co.uk/Quote/634562",
            "QuoteStatus": "SUBMITTED",
            "QuoteDate": "2020-01-30T11:20:59.373",
            "Applicant1Surname": "Robertson",
            "Applicant1DoB": "1989-05-01T00:00:00+01:00",
            "Postcode": "PR8 3AE",
            "ProductId": "1008",
            "ApplicationRef": "PSL-INT-9005782"
        },
        {
            "QuoteRequestId": 640753,
            "Link": "https://apiuat.paymentshield.co.uk/Quote/640753",
            "QuoteStatus": "QUOTESRETRIEVED",
            "QuoteDate": "2020-02-11T13:23:58.13",
            "Applicant1Surname": "Becker",
            "Applicant1DoB": "1986-05-01T00:00:00+01:00",
            "Postcode": "PR9 0SL",
            "ProductId": "1008",
            "QuoteRequestContinuationUri": "https://uat-quote.paymentshieldadviserhub.co.uk/?userId=123456&token=4b862c13-a2b7-473e-8687-1f9a71aaf702&quoteRequestId=640753"
        },
        ...
}

Use the GET Quotes (plural) endpoint to search for quotes based on different criteria. Pass the criteria in the querystring of the GET request (see example)

Supported Fields

Currently we support the following fields as search criteria:

Use the GET Quotes endpoint specifying a UserReference to get a list of quotes with a matching UserReference value. You must provide the full reference, not a fragment or wildcard.

We will return details of all quotes that have a UserReference matching the request. In the example provided, all quotes with a UserReference of 'YourRef_123' will be returned in the response.

Please see the code pane for an example of the JSON response. In the example used, the search has returned more than 100 results. We will only return the first 100 results in the response.

We return some key information about each QuoteRequest to help you to identify the quote required. You can use the Link returned in the response to make a GET Quote request to retrieve the fully-hydrated quote response.

Apply

POST https://apiuat.paymentshield.co.uk/Quote/{QuoteId}/Apply HTTP/1.1
Content-Type: application/json
UserId: 123456
Token: 9c92d88f-d28f-4eb6-8e69-f96707113544
SystemId: 56cba828-1376-4ced-96d4-11a950e4afe8

{
  "UseDefaults": true,
  "CommissionSacrifice": 0.0,
  "Answers": [
    {
      "Value": "01/10/2019",
      "InterfaceKey": "PolicyStartDate"
    },
    {
      "Value": "01704555444",
      "InterfaceKey": "Applicant1TelNo"
    },
    {
      "Value": "Online",
      "InterfaceKey": "DocumentDeliveryPreference"
    },
    {
      "Value": "[email protected]",
      "InterfaceKey": "Applicant1EmailAddress"
    },
    {
      "Value": "Advised",
      "InterfaceKey": "BasisOfAdvice"
    },
    {
      "Value": "TCTest01",
      "InterfaceKey": "YourRef"
    },
    {
      "Value": "DirectDebit",
      "InterfaceKey": "PaymentMethod"
    },
    {
      "Value": "Annual",
      "InterfaceKey": "PaymentFrequency"
    },
    {
      "Value": "Mr T Tester",
      "InterfaceKey": "BankAccountName"
    },
    {
      "Value": "101010",
      "InterfaceKey": "BankSortCode"
    },
    {
      "Value": "12345678",
      "InterfaceKey": "BankAccountNo"
    },
    {
      "Value": "First",
      "InterfaceKey": "DirectDebitDate"
    }
  ]
}

You can apply for an existing Quote by POSTing to the Apply action on the quote resource, passing answers for the 'Application Stage' questions.

v1

To apply for the quote with QuoteId cbf8196c-7757-49a9-8511-c5abf6b4b1c6, the endpoint would be /Quote/cbf8196c-7757-49a9-8511-c5abf6b4b1c6/Apply

There are fewer fields on the Apply Request than the Quote Request because you are already in the scope of a single quote. The fields are:

• UseDefaults - acts the same as on Quote; recommended value is true.
• CommissionSacrifice - the final value for Commission Sacrifice percent, as a decimal (e.g. 0.08 for 8%). The policy will be submitted with this and you can't change it again, so make sure it's right.
• Answers - answers to the 'Application Stage' questions of the question set. Same format as on Quote Request.

v2

To apply for the quote with QuoteId cbf8196c-7757-49a9-8511-c5abf6b4b1c6, the endpoint would be /v2/Quote/cbf8196c-7757-49a9-8511-c5abf6b4b1c6/Apply

Fields:

• CommissionSacrifice - same as v1, above
• IsPartialApply - like IsPartialQuote, when set to true, this allows you to save some answers onto the Quote Request without us moving it forward.
• Answers - same as v1, above

The UseDefaults field was removed for v2. It is always active.

Apply Response

The Apply Response resembles the Quote Response, with many of the same fields.

On successful application, the QuoteStatus will be SUBMITTED. If the request fails, the status will stay at QUOTESRETRIEVED.

An example is given in the Apply Webhook section.

Document Service

You can use the Document Service to get a list of the Documents available for a customer's Quote (or QuoteRequest), and to retrieve the individual documents themselves. Documents are always PDFs but you can choose to receive them as either a Base64 stream or raw PDF bytes (with an application/pdf content-type).

Use GET when requesting lists and documents from the Document Service.

Get Documents List

Get a list of Documents by QuoteRequestId

GET https://apiuat.paymentshield.co.uk/Documents/{QuoteRequestId} HTTP/1.1
UserId: 123456
Token: 9c92d88f-d28f-4eb6-8e69-f96707113544
SystemId: 56cba828-1376-4ced-96d4-11a950e4afe8

Get a list of Documents by QuoteId

GET https://apiuat.paymentshield.co.uk/Documents/?quoteId={QuoteId:GUID} HTTP/1.1
UserId: 123456
Token: 9c92d88f-d28f-4eb6-8e69-f96707113544
SystemId: 56cba828-1376-4ced-96d4-11a950e4afe8

Returns a list of documents for the given QuoteRequestId or QuoteId

Example response

{
  "StatusCode": "OK",
  "Messages": [],
  "Documents": [
    {
      "QuoteRequestId": 633360,
      "Name": "Policy Booklet",
      "Code": "terms",
      "Type": "static",
      "Link": "https://apiuat.paymentshield.co.uk/Document/terms/633360.pdf"
    },
    {
      "QuoteRequestId": 633360,
      "Name": "Insurance Product Information Document",
      "Code": "ipid",
      "Type": "static",
      "Link": "https://apiuat.paymentshield.co.uk/Document/ipid/633360.pdf"
    },
    {
      "QuoteRequestId": 633360,
      "Name": "All Quotes Summary",
      "Code": "multiquote",
      "Type": "dynamic",
      "Criteria": {
        "BuildingsCoverLevel": 500000,
        "ContentsCoverLevel": 50000,
        "BuildingsAD": "Excluded",
        "ContentsAD": "Excluded"
      },
      "Link": "https://apiuat.paymentshield.co.uk/Document/multiquote/633360.pdf?adb=excluded&adc=excluded&bcl=500000&ccl=50000"
    },
    ...
    {
      "QuoteRequestId": 633360,
      "Name": "All Quotes Summary",
      "Code": "multiquote",
      "Type": "dynamic",
      "Criteria": {
        "BuildingsCoverLevel": 1000000,
        "ContentsCoverLevel": 75000,
        "BuildingsAD": "Included",
        "ContentsAD": "Included"
      },
      "Link": "https://apiuat.paymentshield.co.uk/Document/multiquote/633360.pdf?adb=included&adc=included&bcl=1000000&ccl=75000"
    },
    {
      "QuoteId": "37b322f5-8240-48a5-b362-000bddb544b3",
      "QuoteRequestId": 633360,
      "Name": "Quote and Application Summary",
      "Code": "qas",
      "Type": "dynamic",
      "Link": "https://apiuat.paymentshield.co.uk/Document/qas/37b322f5-8240-48a5-b362-000bddb544b3.pdf"
    },
    {
      "QuoteId": "37b322f5-8240-48a5-b362-000bddb544b3",
      "QuoteRequestId": 633360,
      "Name": "Statement of Demands and Needs",
      "Code": "sdn",
      "Type": "dynamic",
      "Link": "https://apiuat.paymentshield.co.uk/Document/sdn/37b322f5-8240-48a5-b362-000bddb544b3.pdf"
    },
    {
      "QuoteId": "37b322f5-8240-48a5-b362-000bddb544b3",
      "QuoteRequestId": 633360,
      "Name": "Quote Summary",
      "Code": "quote",
      "Type": "dynamic",
      "Criteria": {
        "PaymentFrequency": "monthly"
      },
      "Link": "https://apiuat.paymentshield.co.uk/Document/quote/monthly/37b322f5-8240-48a5-b362-000bddb544b3.pdf"
    },
    {
      "QuoteId": "37b322f5-8240-48a5-b362-000bddb544b3",
      "QuoteRequestId": 633360,
      "Name": "Quote Summary",
      "Code": "quote",
      "Type": "dynamic",
      "Criteria": {
        "PaymentFrequency": "annual"
      },
      "Link": "https://apiuat.paymentshield.co.uk/Document/quote/annual/37b322f5-8240-48a5-b362-000bddb544b3.pdf"
    },
    ...
    {
      "QuoteId": "b6cfed8a-b9ce-4035-98a8-f5d0da449c3e",
      "QuoteRequestId": 633360,
      "Name": "Quote Summary",
      "Code": "quote",
      "Type": "dynamic",
      "Criteria": {
        "PaymentFrequency": "annual"
      },
      "Link": "https://apiuat.paymentshield.co.uk/Document/quote/annual/b6cfed8a-b9ce-4035-98a8-f5d0da449c3e.pdf"
    }
  ]
}

To get the documents list by QuoteRequestId, make a GET request to /Documents/{QuoteRequestId}, like /Documents/4812345.

A quote request has many quotes. To get the documents for an individual quote, make a GET request to /Documents/?quoteId={QuoteId} where the QuoteId is the long GUID of a quote, like /Documents/?quoteId=ebff7102-0fb7-4856-b8ae-caf208834bdf

Response fields

Like all other response types from our API, there will be StatusCode and Messages array at the top of the response.

Within each entry in the documents list:

• There is always a QuoteRequestId
• There may be a QuoteId if this document is specific to a quote
• There is always a Name which is a user-facing description of the document
• There is always a Code which is a predictable machine-readable code identifying the document type (see table below)
• There is always a Type field which is a predictable machine-readable string to let you know if this is a static document (always the same), or dynamic (generated from user selections)
• There may be a Criteria block which allows you to filter down a set of documents of the same Code based on their payment type or coverage
• There is always a Link which is the hyperlink reference to download the document itself

Document Codes

The valid options for document Code are listed below:

Differences in retrieving docs by QuoteRequest or Quote

A QuoteRequest may have many quotes. This means there could be more entries of certain document types when you get the list for an entire QuoteRequest compared to that for an individual QuoteId. This is summarised in the table below:

Get Document

Your primary way to discover Get Document links is to follow those returned in a Documents list response.

GET https://apiuat.paymentshield.co.uk/Document/quote/monthly/37b322f5-8240-48a5-b362-000bddb544b3.pdf HTTP/1.1
UserId: 123456
Token: 9c92d88f-d28f-4eb6-8e69-f96707113544
SystemId: 56cba828-1376-4ced-96d4-11a950e4afe8

You can use the Link returned for each document to retrieve the document as a PDF, which will load with content-disposition:attachment. You can request the document as a base64 string by removing .pdf from the Link.

You can also construct a Get Document request string if you know the QuoteRequestId or QuoteId and you know which document you want to retrieve:

PaymentFrequency

Please note that there are payment frequencies named Monthly2MonthsFree and Monthly3MonthsDeferred. One is a 10-month payment plan, and the other is a 9-month payment plan. "Deferred" is the correct language as the total amount paid is still the same as if it were paid in 12 months. The word 'Free' is retained due to internal implementation, but both should be considered as "deferred" payment plans.

Build SDN

Build an SDN

POST https://apiuat.paymentshield.co.uk/SDN/4786184 HTTP/1.1
Content-Type: application/json
UserId: 123456
Token: 9c92d88f-d28f-4eb6-8e69-f96707113544
SystemId: 56cba828-1376-4ced-96d4-11a950e4afe8

{
  "Sections" : [
    {
      "InterfaceKey" : "YourDemandsAndNeeds",
      "Statements" : [
        "Allows you to utilise your no claims discount",
        "Covers your home from loss or damage"
        ]
    },
    {
      "InterfaceKey" : "SuitabilityReasons",
      "Statements" : [
        "Is competitively priced",
        "Includes Personal Possessions cover"
        ]
    }
  ]
}

A Statement of Demands and Needs (SDN) document contains a number of statements about the suitability of the product to the customer.

If your API login is an Advised user, you must build SDN documents by selecting statements appropriate for the customer before you can download the document.

When creating an SDN using our API, it's your choice as to what free text goes into these demands and needs, but for reference and feature parity with Adviser Hub, you can use the /Catalogue/SdnTemplate endpoint to get the default list of statements used by Paymentshield.

POST to /SDN/{QuoteRequestId} with a list of Sections as shown in the code pane example. The InterfaceKey elements must match with those from the SdnTemplate request for the product. Looking at the SdnTemplate response will also help you as the developer to understand what sentences are being finished by the bullets you submit. I.E. "YourDemandsAndNeeds" statements complete the sentence beginning "Find insurance that:..."

The Statements element is a simple array of strings, and you can submit any strings here that accurately describe your customers needs.

If you POST more than once to the SDN for a QuoteRequestId, it will have act as a complete overwrite of all statements in all sections, as though the most recent POST were the only one you submitted.

After you have built the SDN with this function, you will be able to see it in the GET /Documents/ list and will be able to download it from GET /Document/SDN/{QuoteRequestId}.

Catalogue Service

You can use the Catalogue Service to retrieve industry and occupation lists. You can also retrieve lists of valid Branch Number and associated maximum commission sacrifice levels for a user.

Industries

Example industry request without filter

GET https://apiuat.paymentshield.co.uk/industries HTTP/1.1
UserId: 123456
Token: 9c92d88f-d28f-4eb6-8e69-f96707113544
SystemId: 56cba828-1376-4ced-96d4-11a950e4afe8

Example industry request with filter

GET https://apiuat.paymentshield.co.uk/industries/get?filter=fish HTTP/1.1
UserId: 123456
Token: 9c92d88f-d28f-4eb6-8e69-f96707113544
SystemId: 56cba828-1376-4ced-96d4-11a950e4afe8

When a question set includes a question for industry you must send the correct ABI code.

You can use the Get Industries endpoint to return a list of valid industry codes and associated descriptions.

You can add a filter to the request.

Please see the code pane for example requests. Note that in the second request we will return all industries that include the word 'Fish' in the description.

Occupations

Example occupations request without filter

GET https://apiuat.paymentshield.co.uk/occupations HTTP/1.1
UserId: 123456
Token: 9c92d88f-d28f-4eb6-8e69-f96707113544
SystemId: 56cba828-1376-4ced-96d4-11a950e4afe8

Example Occupations request with filter

GET https://apiuat.paymentshield.co.uk/occupations/get?filter=carpet HTTP/1.1
UserId: 123456
Token: 9c92d88f-d28f-4eb6-8e69-f96707113544
SystemId: 56cba828-1376-4ced-96d4-11a950e4afe8

When a question set includes a question for occupation you must send the correct ABI code.

You can use the Get Occupations endpoint to return a list of valid occupation codes.

You can add a filter to the request.

Please see the code pane for example requests. Note that in the second request we will return all occupations that include the word 'Carpet' in the description.

Products

You can use the Get Products request to return a list of valid Branch Numbers and associated maximum commission sacrifice values for a specified userId.

Example Products request

GET https://apiuat.paymentshield.co.uk/products HTTP/1.1
UserId: 123456
Token: 9c92d88f-d28f-4eb6-8e69-f96707113544
SystemId: 56cba828-1376-4ced-96d4-11a950e4afe8

Products Response

Example Products Response

[
    {
        "WebProductGroupId": 1015,
        "Branches": [
            {
                "BranchNo": "PS123456",
                "MaxSacrificeLevel": 0
            },
            {
                "BranchNo": "PS123457",
                "MaxSacrificeLevel": 25
            }
        ]
    },
    {
        "WebProductGroupId": 1014,
        "Branches": [
            {
                "BranchNo": "PS123456",
                "MaxSacrificeLevel": 0
            },
            {
                "BranchNo": "PS123457",
                "MaxSacrificeLevel": 25
            }
        ]
    }
]

You should use the GET Products request to return a list of products the UserId is authorised to sell and the Branch Numbers they can sell them under. We will also return the MaxSacrificeLevel for the UserId/Branch Number combination.

Please see the Code Pane for an example of a Products Response.

Note that the example response shows that UserId 123456 is authorised to sell ProductIds 1015 (Home Insurance) and 1014 (Tenants Contents) under two Branch Numbers. Under Branch Number PS123457 the user has a maximum commission sacrifice level of 25%

SDN Templates

Get SDN Templates for a submitted QuoteRequest

GET https://apiuat.paymentshield.co.uk/sdntemplate/6543211 HTTP/1.1
UserId: 123456
Token: 9c92d88f-d28f-4eb6-8e69-f96707113544
SystemId: 56cba828-1376-4ced-96d4-11a950e4afe8

A Statement of Demands and Needs (SDN) document contains a number of statements which users can choose to agree are important to them. When creating an SDN using our API, it's your choice as to what free text goes into these demands and needs, but for reference and feature parity with Adviser Hub, you can use the SdnTemplate endpoint to get the default list of statements used by Paymentshield.

Make a GET request to /SdnTemplate/{QuoteRequestId}

We require QuoteRequestId to fetch the appropriate SDN statements for that product, and to make sure that the quote you are talking about has really been submitted, as this is the only state where SDN generation is valid.

SdnTemplate Response

Example SdnTemplate response

{
    "StatusCode": "OK",
    "Messages": [],
    "WebProductGroupId": 1015,
    "Sections": [
        {
            "InterfaceKey": "YourDemandsAndNeeds",
            "Title": "YOUR DEMANDS AND NEEDS",
            "SubText": "Find insurance that:",
            "SortOrder": 1,
            "TemplateStatements": [
                {
                    "Text": "Allows you to utilise your no claims discount",
                    "SortOrder": 1
                },
                {
                    "Text": "Covers your home from loss or damage",
                    "SortOrder": 2
                },
                ...
            ]
        },
        ...
    ]
}

An example response is listed in the code pane.

The response consists mainly of a list of Sections. The InterfaceKey corresponds to what you will send to the POST /SDN/ endpoint, and the list of TemplateStatements are the texts used by Paymentshield. The SortOrder properties for this response are informational only and you can choose whether or not to use them. The SortOrder of the Sections is used on the final PDF document so it can be helpful to show users this order during document construction.

Referrals API

You can use the Referrals API to submit contact and property data for your customer as a 'Lead'. This means that we can send them an indicative price, and follow up by phone or email to complete a Quote & Buy journey.

The Referrals API follows our General API Principles and has the same responses for Error Handling.

Referrals Environments and URLs

The code samples on this page use the UAT environment, which you should use to develop your integration. When you go to production, use the Live environment, which will create real Leads and indicative quotes in our live system.

Referral Types

You can create a Referral with one of our two channels:

• Telephony - An adviser from Paymentshield will follow up with the customer at their chosen time. We will complete a fully compliant advised sale over the phone.
• Online - We will send the customer an email containing an indicative price (if available) and a link to complete their quote and application in our online D2C journey.

This string is submitted in the ReferralType field of the Create Lead request.

Overview

You will need:

• A "CRM Key" from your account manager, which is a GUID (e.g. "90D4DB2C-4195-4E9B-A97E-CC4BCED58B70").
• At least one six-character "Broker Code" (also known as "Introducer Code") which represents your referring branch in Paymentshield systems (e.g. "ABC123").
• Reference data of valid options for each of the Lead creation fields (see Reference Data below).
• Reference data of valid options for the Quote answers you want to submit in advance about the customer (see Answer Data below).

Process

• Call the reference data endpoints to get the latest valid times and cover types (this can be a scheduled job).
• Call the Create Lead endpoint to create the lead.
• Handle the response:
  • Handle client errors, especially PreferredContactTimes unavailable (for telephony leads).
  • Store the LeadId and/or QuoteReference (optional).

Reference Data

Preferred Contact Times Response

{
    "value": [
        {
            "id": 1,
            "from": "09:00:00",
            "to": "11:00:00",
            "maxCapacity": 32
        },
        // ...
        {
            "id": 4,
            "from": "15:00:00",
            "to": "17:00:00",
            "maxCapacity": 24
        }
    ],
    "statusCode": 200,
    "success": true,
    "message": null,
    "showMessageOnUI": false
}

You can fetch and cache this reference data. We recommend a cache duration of 24 hours.

GET PreferredContactTime

Your Create Lead request must contain one or more preferredContactTimes. This public API provides the valid options.

Make a GET request to /PreferredContactTime

When you submit a preferredContactTime on a Lead, you can use one of the objects from this array verbatim, although only the from and to properties are required.

GET CoverType

Cover Type Response

{
    "value": [
        {
            "id": 1,
            "name": "Home Insurance",
            "description": null,
            "productId": 1015
        },
        {
            "id": 2,
            "name": "Landlord's Insurance",
            "description": null,
            "productId": 1009
        }
    ],
    "statusCode": 200,
    "success": true,
    "message": null,
    "showMessageOnUI": false
}

Your Create Lead request must contain one or more coverTypeIds. This public API provides the valid options.

Make a GET request to /CoverType

When submitting a Lead, the coverTypeIds is an array of one or more integers from the id fields of CoverType entities. On our user interface, the name is used as checkbox text, and the id is used as the submitted value when selecting one or more products.

GET MortgageCategory

Mortgage Category Response

{
    "total": 5,
    "value": [
        {
            "id": 1,
            "name": "Remortgage"
        },
        {
            "id": 2,
            "name": "Home Mover"
        },
        {
            "id": 3,
            "name": "First-Time Buyer"
        },
        // ...
    ],
    "statusCode": 200,
    "success": true,
    "message": null,
    "showMessageOnUI": false
}

Your Create Lead request must contain a mortgageCategoryId. This public API provides the valid options.

Make a GET request to /MortgageCategory.

When submitting a Lead, the mortgageCategoryId must be set to one of the numeric IDs from this response.

↓ Jump to next section

Answer Data

When you create an Online lead, you can submit additional "answers" using the quickQuoteAnswers object.

All answers are optional and serve two purposes:

• Improve the Indicative Price accuracy,
• Pre-fill the customer's online Quote & Buy journey.

Create Lead Request (online, with QuickQuoteAnswers)

{
    "agreement": true,
    "introducerCode": "ABC123",
    "firstName": "Jack",
    "lastName": "Nguyen",
    "phoneNumber": "07712345678",
    "email": "[email protected]",
    "preferredContactMethodCode": "Email",
    "referralType": "Online",
    "quickQuoteAnswers": {
        "Applicant1DoB": "20/01/1990",
        "InsuredAddressPostCode": "PR81AA",
        "InsuredAddressStreet": "128 Lord Street",
        "InsuredAddressTown": "Southport"
    }
}

Answer fields - Home product

You can use our Question Set explorer tool to view validations and valid options:

Question Set 167

All answer values are submitted as JSON strings and converted to their data types by our platform.

Notes

*The answers marked "RFU" are accepted, but we are currently not able to pre-fill these answers onto the quote. They may be read by future developments.

Applicant1FirstName and Applicant1LastName are automatically filled with the FirstName and LastName values from the Lead, so you should not send answers to these questions.

OwnershipProperty is automatically set to 'OwnedMortgaged'.

ResidentialStatus is automatically set to the value indicated by the MortgageCategoryId on the Lead, so you should not send an answer to this question.

Create Lead

Create Lead request (telephony)

POST https://uat-referralsapi.paymentshield.co.uk/Lead/Crm/CreateLead HTTP/1.1
Content-Type: application/json
CrmKey: 90D4DB2C-4195-4E9B-A97E-CC4BCED58B70

{
    "agreement": true,
    "introducerCode": "ABC123",
    "firstName": "Ada",
    "lastName": "DeLancie",
    "phoneNumber": "07712345678",
    "email": "[email protected]",
    "coverTypeIds": [1],
    "referralType": "Telephony",
    "preferredContactDate": "2024-04-26",
    "preferredContactTimes": [
        {
            "from": "09:00:00",
            "to": "11:00:00"
        }
    ]
}

Make a POST request to /Lead/Crm/CreateLead

Headers

We require the CrmKey HTTP header to authenticate your request, and associate it with your integrating system. This is the secret GUID provided by your account manager. Treat it like a password. The header value is not case-sensitive.

Body

The body of your request should be a JSON object with the following fields:

*Currently required only on Telephony journey because Online journey is single product.

Create Lead Response

Telephony success response

{
    "contactTimes": [
        {
            "from": "09:00:00",
            "to": "11:00:00"
        }
    ],
    "leadId": 6088,
    "quoteReference": null,
    "statusCode": "OK",
    "messages": []
}

The response will always be a JSON object with a StatusCode and a Messages property. These conform to our general Error Handling across all APIs.

Success Response

The StatusCode will be "OK" and the response will contain a LeadId and QuoteReference.

The response does not contain the indicative quote price. This is sent privately by Email or SMS (whichever was selected as preferredContactMethod) to the customer.

Referrals Client Errors

Create Lead - Client error response

{
    "leadId": null,
    "quoteReference": null,
    "statusCode": "ClientError",
    "messages": [
        {
            "propertyName": "IntroducerCode",
            "errorMessage": "Introducer code must not be blank. Please contact your distributor to get this code."
        },
        {
            "propertyName": "PhoneNumber",
            "errorMessage": "Sorry, we can't store a phone number with less than 9 number characters."
        }
    ]
}

The message objects have propertyName and errorMessage fields. You will receive one of these objects for each error in your submitted request. See code pane for example.

PreferredContactTimes unavailable

Create Lead - error response with timeslot suggestions

{
    "leadId": null,
    "quoteReference": null,
    "statusCode": "ClientError",
    "messages": [
        {
            "propertyName": "PreferredContactTimes",
            "errorMessage": "Sorry, there are no appointments available at the times you selected. Please see the list of suggestions.",
            "sameDayAvailableTimes": [
                {
                    "from": "09:00:00",
                    "to": "11:00:00"
                },
                {
                    "from": "11:00:00",
                    "to": "13:00:00"
                },
                {
                    "from": "13:00:00",
                    "to": "15:00:00"
                },
                {
                    "from": "15:00:00",
                    "to": "17:00:00"
                }
            ],
            "otherDayAvailableTimes": [
                {
                    "date": "2024-03-06T00:00:00",
                    "times": [
                        {
                            "from": "17:00:00",
                            "to": "18:00:00"
                        }
                    ]
                },
                {
                    "date": "2024-03-07T00:00:00",
                    "times": [
                        {
                            "from": "17:00:00",
                            "to": "18:00:00"
                        }
                    ]
                },
                {
                    "date": "2024-03-08T00:00:00",
                    "times": [
                        {
                            "from": "17:00:00",
                            "to": "18:00:00"
                        }
                    ]
                }
            ]
        }
    ]
}

On a telephony lead, it's possible that your selected contact date and time is unavailable. In this case, we will return a special client error with two lists of suggested times. See code pane.

The format of the error is:

• StatusCode: 'ClientError'
• Messages: Contains an element with PropertyName of PreferredContactTimes:
  • sameDayAvailableTimes - an array of timeslots on the same day which have remaining capacity.
  • otherDayAvailableTimes - an array of other days with timeslots matching your preferred time of day, which have remaining capacity.

To correct the error, choose one of the sameDayAvailableTimes or otherDayAvailableTimes and re-submit your Create Lead request.

Webhooks

About our Webhooks

If you need to know when a quote has been submitted through Adviser Hub, you can ask to be included in our webhooks system.

Once you subscribe, we can notify your chosen server URL when certain events happen in our system. Currently the only notifiable event is when a policy is applied for (submitted).

Please get in touch with your technical contact to arrange this, and they will ask for your webhook URL, and a notification email address for when something goes wrong. These settings are scoped to your SystemId. We will send you a secret, which is a GUID specific to your integration.

Trust

Our webhook payloads include an additional header, X-Paymentshield-Secret which will contain the GUID secret shared with you earlier. You can use this as a security measure to make sure that the webhook payload is coming from us.

Apply Webhook

An example of an Apply Response that would be sent to your webhooks endpoint

{
    "StatusCode": "OK",
    "Messages": [],
    "QuoteRequestId": 5228576,
    "QuoteReference": "PSL-BCHI-5228576",
    "ApplicationReference": "PSL-INT-6021848",
    "QuoteStatus": "SUBMITTED",
    "ProductId": "1015",
    "QuoteSessionId": "a8cafcc8-8c35-44ab-b84d-21ce6b2401ca",
    "QuoteRequestContinuationUri": "https://uat-quote.paymentshieldadviserhub.co.uk/?userId=123456&token=12399b8f-db95-4091-b37f-d82e80a0290d&quoteRequestId=5228576",
    "QuoteDate": "2024-01-19T14:03:02+00:00",
    "QuoteExpiryDate": "2024-07-17T00:00:00+01:00",
    "CommissionSacrifice": 0.0,
    "LinkedQuotes": [
        {
            "QuoteRequestId": 5228575,
            "Link": "https://apiuat.paymentshield.co.uk/v2/Quote/5228575",
            "QuoteStatus": "QUOTESRETRIEVED",
            "QuoteDate": "2024-01-19T14:00:47.707",
            "IsApplied": false
        }
    ],
    "Quote": {
        "QuoteId": "9f1a6042-f2da-470c-bf08-2e8fe1737fcf",
        "InsurerName": "ABC",
        "ProductName": "Home Insurance",
        "QuoteExpiryDate": "2024-07-17T00:00:00",
        "Cover": {
            "IsRequested": true,
            "BuildingsAD": "Excluded",
            "ContentsAD": "Excluded",
            "BuildingsCoverLevel": 1000000.0,
            "ContentsCoverLevel": 75000.0
        },
        "Premiums": [
            {
                "PaymentMethod": "DirectDebit",
                "PaymentFrequency": "Annual",
                "PaymentFrequencyDescription": "Annually",
                "PriceID": "08074ef6"
            }
        ],
        "Endorsements": []
    },
    "Price": {
        "ID": "08074ef6",
        "Values": {
            "TotalCostPerPaymentPeriod": 416.37,
            "TotalPremiumIncludingIPT": 416.37,
            "TotalPremiumExcludingIPT": 375.62,
            "AdministrationCharge": 36.00,
            "InsurancePremiumTax": 40.75,
            "HouseholdInsurancePremiumExcludingIPT": 339.62,
            "HomeEmergencyPremiumExcludingIPT": 0.0,
            "LegalExpensesPremiumExcludingIPT": 0.0,
            "BuildingsCoverGrossExcludingIPT": 216.75,
            "ContentsCoverGrossExcludingIPT": 122.87,
            "PersonalCoverGrossExcludingIPT": 0.00,
            "TotalAmountPayable": 416.37
        }
    },
    "Answers": [
        ...
    ]
}

When you are subscribed to the Apply action and a policy for your SystemId is submitted, we will:

• Send an 'Apply Response' payload to your webhook URL, and
• Expect a reply with status 200 OK within 30 seconds.

If we don't receive the expected response, you should receive an error notification email, and the system will retry on a backing-off basis. The latter is a work in progress.

You can use the Apply Response to update the status of the quote in your system. You can also take it as notification that the final documents, such as QAS and SDN, are available to download.

Question Sets

Browse products and Question Sets with the following table and filters. Click on a QSID to go to our Question Set Explorer tool, which has information about the required Answers and their criteria.

Filters

Products: {{ labelFor(p.id) }}

Terms: {{ termsFor(t.isVc) }}

API Versions: {{ v.journey }}

Results

*Additional payment plans: Inclusion of a 9 or 10 month PaymentFrequency suitable for vulnerable customers (VC).

☙

Reduced Question Set Defaults

If you are using the Refreshed Home Product (1015) Question Set with the v2 API, and you get quotes without setting the following answers, they will use the following Default values:

Defaults and Rules for 166/167

Postman and Swagger/OpenAPI

Postman Collections

These collections are specific to a product but will have some value if you are implementing another product.

Usage

• Download and import the Postman Collection file.
• In Postman, click on the expanding tree header of the collection ("Paymentshield REST API - Home" or similar).
• Go to the Variables tab - see Defining Collection Variables.
• Set your integration variables: BrokerLogin, BrokerPassword, SystemId, BranchNumber.
• We recommend you run requests one at a time and observe the results.
• Run the POST Security/Login request:
  • This will automatically set the UserId and Token collection variables.
• Run the POST Quote v2 - Prices request:
  • This will automatically set the QuoteRequestId collection variable.
• To apply for a quote or get single quote docs, set the QuoteId collection variable yourself.

Swagger/OpenAPI Definition

Last updated: 2024-01-22

API version: 2024-01-28

PSL-REST-API-2024-01-28.openapi.json

☙