Integrating with SchemeServe
The SchemeServe API gives you the flexibility to connect SchemeServe with your wider technology ecosystem and create digital journeys that work for your business.
This guide is designed to give you a high-level overview of what’s possible. It covers common integration scenarios, available capabilities and frequently asked questions to help you explore how the API could support your business before getting into the technical detail.
Use it as a starting point for ideas, then involve your technical team and explore our developer documentation when you're ready to design your integration.
Ready to explore the technical detail? For endpoint specifications, schemas and implementation examples, visit the SchemeServe API documentation
01 · SUMMARY OF CORE CAPABILITIES
What can I do with the SchemeServe API?
| Question Set mapping |
Retrieve question IDs, types, answer options, structures and validation information. ✓ Available |
| New Business quotations |
Build an external quotation journey while SchemeServe handles validation, rating and underwriting. ✓ Available |
| External underwriting data |
Call external data or rating services during quotation. ✓ Available |
| Document retrieval and upload |
Retrieve, upload and attach documents to SchemeServe records, including importing files from external URLs. ✓ Available |
| Claims |
Connect external claims processes to SchemeServe using the Claims API. ✓ Available |
| Reporting & data |
Retrieve real-time data or use scheduled SFTP report delivery. ✓ Available |
| External payment journeys |
External payment providers can be incorporated into a custom quotation journey. ◐ Partial |
| Case synchronisation |
Cases and records can be retrieved for CRM or external policy administration use. ◐ Partial |
| Mid-Term Adjustments |
API support for submitting changes to existing policies is being developed. → In development |
| Renewals |
API support for external renewal journeys is being developed. → In development |
02 · AUTHENTICATION
How should my integration connect securely?
Before diving into workflows, it helps to know how requests are authenticated. Which method you use depends on the kind of integration you're building:
-
Machine-to-Machine (API Key) - the recommended approach for most integrations: broker portals, backend services, scheduled jobs, and other server-to-server connections. You send a machine key with each request, and no user login is required.
-
Bearer Token (JWT) - used when a request needs to represent a specific logged-in SchemeServe user, such as in browser-based or internal tools.
-
Site ID - an extra header some APIs need to identify which SchemeServe environment you're talking to. It's not an authentication method by itself, just an identifier.
-
Origin - occasionally required for browser-based apps, usually added automatically by the browser.
You can create your API Machine keys on your SchemeServe site by going to Admin → Settings → API keys.
03 · CUSTOM QUOTATION JOURNEYS
Building your own quotation experience
A client can build its own website, broker portal, mobile app or internal sales journey while SchemeServe performs the underlying quotation, validation, rating and underwriting.
A typical flow looks like this:
Use the Question Set API to understand the questions, identifiers, answer options and data structure required for the product.
Map the information captured in your external journey to the corresponding SchemeServe questions.
Send the mapped answers to SchemeServe through the Quote API to create the quotation.
SchemeServe validates the submitted answers and applies the product’s configured rating and underwriting rules.
Your application receives the result, such as a price, referral or decline, along with the relevant case identifiers.
Where documents are generated as part of the quotation process, retrieve them separately through the Documents API.
POST/quote
Data enrichment
SchemeServe can call an external API during quotation when additional information is required before producing a price or underwriting decision. Check out our guide here.
04 · DOCUMENTS
Retrieving, uploading and importing files
SchemeServe's APIs can be used to retrieve documents from SchemeServe or bring externally generated documents into SchemeServe. This makes it possible to include document management within broker portals, customer journeys and integrations with other systems.
|
Retrieve documents
|
Documents generated or stored against a case can be retrieved by an external application. For example, a broker portal could automatically display policy schedules and certificates to the broker without requiring them to log into SchemeServe. Retrieve documents for a specific case record:
|
|
Upload documents
|
Documents created or received outside SchemeServe can be uploaded through the File Upload API and associated with the relevant case.
|
|
Import documents from a URL
|
If another service hosts the document, your integration can provide its URL instead of first downloading the file and uploading it to SchemeServe.
For example: External service generates document → Returns document URL → URL sent to SchemeServe → SchemeServe retrieves + stores file → Document associated with case
This can also support protected endpoints where a supported authentication method is available.
API endpoints:
|
The Documents API returns a secure download URL containing a temporary SAS token rather than returning the document itself as Base64 data. Your application can use this URL to download the file programmatically. If the token expires, query the API again to generate a fresh one.
05 · PAYMENTS & BINDING
Using an external payment journey
If you're building your own quotation journey, broker portal or customer-facing application, payment can be handled outside SchemeServe, giving you control over the customer-facing checkout experience.
Your chosen payment provider processes the payment, the relevant outcome is passed back into SchemeServe and the quotation, payment and policy placement processes can be connected to create a more automated end-to-end journey.
A flow may look like this:
Submit the customer's information through the SchemeServe Quote API to create and price the quotation.
Direct the customer to your chosen payment journey, such as an externally integrated payment provider. The payment process takes place outside SchemeServe.
Once payment has been completed, your application receives the result from the payment provider and submits the relevant payment or transaction information to SchemeServe.
Once the required payment and policy information has been recorded, the case can be progressed or placed on cover where appropriate.
📍Availability:
The exact payment and placement flow may depend on the implementation, so requirements should be confirmed before building the integration.
Payment collection and binding should be treated as separate parts of the integration. Completing a payment does not necessarily mean the SchemeServe case has automatically been placed on cover - your integration should manage the appropriate policy lifecycle action separately.
06 · POLICY LIFECYCLE
Cases, records, MTAs, renewals and referrals
SchemeServe’s APIs can support integrations throughout the policy lifecycle, allowing external applications to track cases, retrieve policy and transaction information, identify referrals and keep other systems synchronised with SchemeServe.
Support for Mid-Term Adjustments (MTAs) and Renewals is also being developed, extending these capabilities so clients can eventually manage more policy changes directly from their own broker portals, customer journeys and internal systems.
A single SchemeServe case can contain multiple records, including New Business, MTAs, Renewals and Cancellations. Each record will have a different
recordId. Integrations should therefore be designed around the overall case lifecycle and stable Case ID rather than relying only on the original record ID.
6.1. Mid-Term Adjustments & Renewals endpoints → In development
SchemeServe is expanding its modern APIs to support Mid-Term Adjustments (MTAs) and Renewals, allowing clients to manage more of the policy lifecycle through their own broker portals, customer journeys and external applications.
Once released, integrations will be able to submit policy changes and renewals to SchemeServe, update answers, validate information, receive revised pricing and progress the resulting transaction.
This means a client could, for example, allow a broker to change a policy or complete a renewal entirely within their own portal, while SchemeServe handles the underlying rating, underwriting and policy processing.
1. Creating MTAs and Renewals
2. Updating policy information and answers
3. Validation and pricing
4. Progressing transactions
5. Generating associated documents
The exact actions and transaction types supported will be confirmed as the new endpoints progress towards release.
6.2. Checking for referrals
External applications can identify when an individual quotation or case record has been referred following SchemeServe's rating or underwriting process.
This allows an integration to create journeys such as:
The API can be used to work with the outcome and status of individual case records.
Querying or filtering all referred cases as a single list is not currently supported through the API. Integrations requiring a referral work queue should take this limitation into account when designing their workflow.
6.3. Case synchronisation ◐ Partial
SchemeServe can be connected with CRMs, data platforms, policy administration systems and other applications so relevant case and policy information can also be maintained externally.
A common pattern is:
Relevant capabilities may include Cases API, Case Records API, Record identifiers, Policy identifiers where available.
Because a Case ID can contain multiple records, integrations should not assume that the original Record ID will always represent the latest state of the policy. For example, an MTA, Renewal or Cancellation may create a new record with a different Record ID.
Requirements such as identifying changes, retrieving records by Case ID and determining the latest policy state should be considered when designing the integration.
07 · DATA & REPORTING
Getting SchemeServe data into your reporting environment
SchemeServe data can be used within your own reporting tools, data warehouses and Business Intelligence platforms, helping you combine SchemeServe information with data from across your business.
Typical uses include Power BI dashboards, broker performance reporting, underwriting MI, product governance, Consumer Duty reporting, fair-value monitoring, operational reporting and finance reconciliation.
There are two common ways to access reporting data:
| API-based reporting | Retrieve SchemeServe data in real time for use within your own applications, databases or reporting tools. Your external system requests the required data through the API, then stores, combines or visualises it within your own environment - for example, in a Power BI dashboard or data warehouse. |
|
Scheduled report delivery (SFTP) |
SchemeServe can generate scheduled report files for delivery to a client-managed SFTP server. The client's reporting and data platform processes the files. Click here for more information on SFTP reports |
API data is available in real time, with a current rate limit of 100 requests per rolling minute. Integrations should be designed to avoid repeatedly requesting unchanged data where possible.
08 · CLAIMS
Connecting external claims processes
The Claims API allows SchemeServe to connect with external claims systems and third-party claims administrators, helping clients keep claims information flowing between SchemeServe and their wider claims processes.
For example, where claims are managed in a separate platform, the integration can send or retrieve relevant claim information so both systems remain aligned without relying on manual data entry.
How it may work:
A claim is managed within the client's or third-party administrator's external claims system.
The external system uses the Claims API to send, retrieve or update the relevant claim details in SchemeServe.
Claim information can remain accessible across SchemeServe and the external claims process, supporting operational workflows and reporting.
Claims processes can vary considerably between organisations, so the available Claims API capabilities should be reviewed against the specific information and workflow your integration needs to support.
09 · KNOWN LIMITATIONS
Current limitations to be aware of
10 · FAQ
Common integration questions
Which API should I use?
Use the current SchemeServe API (v2) wherever possible. The legacy API has been deprecated and is no longer available for new connections.
Does SchemeServe support OAuth 2.0?
OAuth 2.0 is not currently supported as the authorisation framework. SchemeServe supports Machine-to-Machine API Key authentication and JWT Bearer Token authentication for user-authenticated scenarios.
Can API Machine Keys be rotated?
Yes. Machine Keys can be rotated at any time and SchemeServe does not enforce a fixed rotation schedule.
Clients can manage and rotate their own Machine Keys without requiring SchemeServe Support. Rotation can also be automated — for example, create a new key, begin using it and then invalidate the previous key.
For direct system-to-system integrations, Machine Keys are the recommended authentication method.
How do I map my quotation journey to SchemeServe?
Use the Question Set API to retrieve the structure, question identifiers and expected data format for the SchemeServe product.
You can also manually export a scheme's Question Set from SchemeServe in JSON format.
Is quoting a single API request?
Yes. When using a Machine Key, obtaining a quote requires a single POST /quote request.
Any generated documents are retrieved separately using the Documents API.
Can SchemeServe call external APIs during quotation?
Yes. External API calls can be incorporated into the rating process where additional information is required before SchemeServe produces a quotation.
Can I query all referred cases?
Not currently. Individual case records expose referral information, but the API does not currently support filtering or querying all records by referral status.
How can refund values be retrieved?
Refund values are available on Question objects that include the CancellationCalculation property and can be accessed through the Question Sets API. For implementation details, see the Question Sets API documentation.
Are document responses returned as Base64?
No. The Documents API returns a download URL containing a temporary SAS token rather than embedding Base64 document content in the response.
Can reports be automated?
Yes. Data can be retrieved through the API or reports can be delivered automatically using scheduled SFTP.
Can we replicate SchemeServe data into our database?
Yes. Data can be extracted through the API or report exports. API data is real time and is subject to the current limit of 100 requests per rolling minute.
How do I create my API keys
You can create your API keys via Admin → Settings → API Keys provided you have the relevant permission levels.
Can a policy be cancelled through the API?
Not currently. API-based policy cancellation is planned but is not supported at present.
Ready to start your SchemeServe integration?
Review the current API documentation for available APIs, endpoints, schemas and implementation details.
.png)
