Overview
The SchemeServe API enables third-party platforms to integrate with SchemeServe to automate a wide range of business processes.
Whether you're building a broker portal, integrating with third-party systems or automating back-office processes, the API allows you to securely exchange data with SchemeServe.
Typical use cases include:
- External quotation journeys
- Broker portal integrations
- Claims integrations
- Report automation
- External underwriting and rating services
- Policy administration
- Document retrieval
You can find our full developer documentation here: https://api.schemeserve.com/docs
Our legacy API has been deprecated and is no longer accessible for new connections.
Authentication
All SchemeServe APIs require authentication to ensure requests are secure and authorised. The authentication method used depends on the API being accessed and the type of integration being built.
SchemeServe supports multiple authentication methods, including Machine-to-Machine (API Key) authentication for server-to-server integrations and Bearer (JWT) authentication for authenticated user sessions. Some APIs may also require additional headers, such as Site ID or Origin.
| Authentication method | Description | Typical use cases | Technical notes |
|---|---|---|---|
| Machine-to-Machine (M2M) |
Recommended for server-to-server integrations Machine-to-Machine (M2M) authentication uses an API key (also referred to as a Machine Key) to authenticate requests from trusted applications without requiring a user to log in. |
Recommended authentication method for: • External integrations • Backend services • Broker portals • Customer portals • Automated processes • Scheduled jobs |
The Machine Key should be sent in the request header. Example: x-api-key: YOUR_MACHINE_KEY
|
| Bearer Token (JWT) |
Used for authenticated user sessions Bearer authentication uses a JSON Web Token (JWT) issued after a successful user authentication. The token represents an authenticated SchemeServe user and allows API requests to be performed on behalf of that user. |
• User-facing applications • Internal tools • Browser-based applications • Authenticated user sessions |
Example:Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
|
| Site ID | Some APIs require the target SchemeServe Site ID to identify which SchemeServe environment the request relates to. | The Site ID is not an authentication method on its own - it simply identifies the SchemeServe site being accessed. |
This is supplied as an additional header alongside the chosen authentication method. Example: Site-Id: myscheme
|
| Origin |
Certain browser-based integrations may require an Origin header. This allows SchemeServe to validate where requests are coming from and supports Cross-Origin Resource Sharing (CORS). |
This header is generally only required for browser-based applications and is not normally needed for server-to-server integrations. |
The Origin header is typically added automatically by modern web browsers. Example: Origin: <https://portal.company.com> |
Common Integration Patterns
| Process | Supported | Overview | Example flow | Relevant capabilities |
|---|---|---|---|---|
| Question Set Mapping | ✅ Yes | Use the Question Set API to retrieve the structure, question identifiers and data format required to map their external quotation journey to a SchemeServe product. |
1. Retrieve the product's Question Set using the Question Set API. 2. Review the returned JSON structure and question definitions. 3. Map fields from the external application to the corresponding SchemeServe questions. 4. Submit the structured answers through the Quote API. |
Every SchemeServe product has its own Question Set, which defines the information required to complete a quotation. The Question Set API returns: • Question identifiers • Question types • Available answer options • Expected data structures • Validation rules (where applicable) This provides the information needed to map an external quotation journey to SchemeServe and submit quotes successfully. |
| New Business Quote | ✅ Yes | A client can build their own website, broker portal, mobile application or internal sales journey while using SchemeServe to perform the underlying quotation, rating and underwriting process. |
1. The user enters their risk details into the client’s external journey. 2. The external application maps its data to the relevant SchemeServe Question Set. 3. The application submits the information through the Quote API. 4. SchemeServe validates the answers and runs the configured rating and underwriting rules. 5. The application receives the quote outcome, such as quoted, referred or declined. 6. Any generated documents can then be retrieved separately. |
A quote can be requested using a single API call when a Machine Key is used. • Quote validation • Pricing response • Quote outcome • Case identifiers • Document retrieval Endpoint: POST /quote
|
| AI-assisted data ingestion in the quotation journey | 🟡 Supported through external solutions | An external AI service can read unstructured broker submissions and convert the information into structured data that can be submitted to SchemeServe. |
The first four steps are handled by the client or external AI provider. 1. A broker sends an email, PDF, spreadsheet or proposal form. 2. The AI service extracts the relevant risk information. 3. The extracted information is mapped to the SchemeServe Question Set. 4. The AI solution submits the structured answers through the Quote API. 5. SchemeServe validates the submission and returns a quote, referral or decline. 6. A human reviews the result where required. |
SchemeServe provides: • Question Set structure • Quote validation • Rating and underwriting processing • Pricing and quote outcomes The external AI provider is responsible for: • Document interpretation • Data extraction • Field mapping • Confidence checks and human review workflows |
| External data and underwriting services | ✅ Yes | SchemeServe can call external APIs during the quotation process to obtain additional information required before producing a price or underwriting decision. |
1. A quote is submitted with the relevant risk details, such as an address. 2. SchemeServe calls an external service during the quotation process. 3. The external service returns additional risk information. 4. SchemeServe uses the response within its rating or underwriting rules. 5. The quote is priced, referred or declined accordingly. |
Typical uses include: • Flood-risk checks • Subsidence information • Property enrichment • Geocoding • Credit or sanctions checks • External pricing services The external endpoint must use an authentication method supported by SchemeServe. Where complex authentication is required, such as MFA, TOTP generation or specialist token refresh, middleware may be needed: SchemeServe → Client middleware → External service
|
| Document retrieval | ✅ Yes | An external system can retrieve documents generated during quotation or case processing and display or store them within its own portal or application. |
1. A case transaction is completed. 2. SchemeServe generates the relevant documents. 3. The external system requests the documents using the case identifier. 4. The documents are downloaded, stored or displayed in the external portal. |
Documents are retrieved separately from the quotation response. Endpoints: GET /documents?caseid={caseid}Or GET /documents?caserecordid={caserecordid}to only get the ones attached to that case record. |
| Payment integration (Opayo) via custom Quotation journey | 🟡 Partial | A customer may manage payment through an external payment provider and pass the relevant payment outcome or transaction details into SchemeServe. |
1. A quote is produced through SchemeServe. 2. The customer completes payment through an external payment provider. 3. The provider or client application confirms the payment outcome. 4. The relevant payment information is submitted to SchemeServe. 5. The case is progressed or placed on cover where appropriate. |
• External payment submission • External payment method support • Case placement • Payment status processing Payment collection is normally managed externally. Binding and payment should be treated as separate integration processes unless otherwise confirmed for the specific implementation. |
| Mid-Term Adjustment (MTA) | 🟠 In progress | An external system will be able to submit changes to an existing case, such as changes to the risk, address, cover or case details. |
1. The broker or customer selects an existing case. 2. The external system submits the updated information. 3. SchemeServe creates and processes the MTA record. 4. SchemeServe validates the change and recalculates the premium. 5. The external system receives the revised pricing and outcome. 6. The adjustment is confirmed and updated documents are generated. |
Planned capabilities include: • MTA creation • Updating case answers • Validation • Revised pricing • Status progression • Document generation The exact supported transaction types, actions and release scope will be confirmed when the MTA endpoints are released. Cancellation should not be assumed to be supported unless it is explicitly included as an MTA transaction type. |
| Renewal | 🟠 In progress | A client will be able to connect their own renewal journey to SchemeServe so that policies can be reviewed, repriced and renewed externally. |
1. The external platform identifies a case approaching renewal. 2. The latest case information is submitted or retrieved. 3. SchemeServe calculates the renewal terms. 4. The broker or customer reviews the renewal offer. 5. The renewal is accepted and placed on cover. 6. Updated documents are generated. |
Planned capabilities include: • Renewal creation • Updating answers • Validation and pricing • Status progression • Document generation The final release scope will confirm whether all renewal actions can be completed entirely through the API. |
| Case synchronisation | 🟡 Partial | Connect SchemeServe to their own CRM, data platform or policy administration system and keep relevant quotation, case information synchronised. |
1. A case is created or updated in SchemeServe. 2. The external system retrieves the associated case or record details. 3. Relevant identifiers, statuses and case information are stored externally. 4. The client periodically retrieves changes to keep both systems aligned. |
Relevant capabilities may include: • Cases API • Case Records API • Record identifiers • Policy identifiers, where available • Status retrieval • Updating answers Important consideration: a single case may contain multiple records, including New Business, MTAs, Renewals and Cancellations. Each record can 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 case record ID.The availability of case-level status, changed-since queries and retrieval of all records by Case ID should be confirmed for the client’s specific requirements. |
| Refer status check | ✅ Yes | An external system can check whether an individual quotation has been referred following the rating or underwriting process. |
1. A quotation is submitted. 2. SchemeServe processes the quote. 3. The external application receives or retrieves the quote outcome. 4. If the quote is referred, the application can notify the user or route the case for manual review. |
• Quote outcome • Referred status on individual case records • Case status lookup Current limitation: the API does not currently support querying or filtering all referred cases as a list. |
| Document import | ✅ Yes | Upload documents generated or received outside SchemeServe and associate them with a selected case. |
1. An external system generates or receives a document. 2. The client uploads the file content to SchemeServe using the File Upload API. 3. SchemeServe stores the file and returns the upload identifiers. 4. The client associates the uploaded file with the relevant case 5. The document becomes available within SchemeServe. |
• Upload files directly to SchemeServe storage • Support for externally generated documents • Associate uploaded files with SchemeServe records • Secure API-based document management |
| Document import from URL | 🟠 In progress | Provide the location of a file hosted by an external service and allow SchemeServe to retrieve, store and attach it automatically. |
1. An external service generates a document and exposes it via a URL. 2. The client submits the document URL to SchemeServe. 3. SchemeServe retrieves the file from the external service. 4. The file is stored within SchemeServe. 5. The document is associated with the relevant case. |
Planned capabilities include: • Upload documents using a URL rather than file content • Automatic retrieval of externally hosted files • Support for protected endpoints using supported authentication methods • Automatic storage and association with SchemeServe records |
| Data and Reporting | ✅ Yes | Extract SchemeServe data and use it within personal reporting, data warehouse or Business Intelligence environment. |
Option 1: API-based reporting 1. The external system requests data from SchemeServe. 2. The data is returned in real time. 3. The client stores, combines or visualises the information in its own systems. Option 2: Scheduled SFTP delivery 1. SchemeServe generates scheduled report files. 2. Reports are delivered to a client-managed SFTP server. 3. The client’s reporting or data platform processes the files. |
Typical uses include: • Power BI dashboards • Broker performance reporting • Underwriting MI • Product governance • Consumer Duty reporting • Fair-value monitoring • Operational reporting • Finance reconciliation API data is real time. The current rate limit is 100 requests per rolling minute. Integrations should avoid repeatedly requesting unchanged data where possible. |
| Claims integration | ✅ Yes | Third-party claims administrators can use the Claims API to connect external claims processes with SchemeServe. |
1. A claim is created or updated in an external claims system. 2. The external system sends or retrieves the relevant claim details. 3. SchemeServe stores or exposes the claim information. 4. Internal teams and external systems remain aligned. |
• Claims API • Claim creation and retrieval, where supported • Claim updates • Claims reporting The current documentation should be reviewed against the client’s exact requirements. |
Known Limitations
The following limitations currently apply:
- API user permissions cannot currently be managed for hidden/shared schemes.
- Sites still using CustomJS or CSS cannot access the API user permissions interface.
- Certain API functions aren’t supported yet, to better understand what endpoints exist, please refer to our API documentation.
- Post-quote questions are not currently supported via the API.
- Querying a list of all referred cases directly via the API is not currently supported, but the referral status of individual case records using the appropriate case identifier.
Frequently Asked Questions
Which API should I use?
The New API should be used wherever possible as the legacy API has already been deprecated: https://api.schemeserve.com/docs/#description/introduction
Do you support OAuth 2.0 authentication method?
In addition to Machine-to-Machine (API Key) authentication, SchemeServe supports JWT Bearer Token authentication for user-authenticated scenarios. While OAuth 2.0 is not currently supported as the authorisation framework, SchemeServe provides secure token-based authentication using short-lived JWT access tokens and refresh tokens to maintain authenticated sessions.
How do I map my quotation journey to SchemeServe?
The easiest way to map your quotation journey is by using the Question Set API, which returns the structure, question identifiers and expected data format for a SchemeServe product. This allows your application to correctly map its fields before submitting quotations via the Quote API.
You can also manually export the scheme's question set from SchemeServe in JSON format. This contains the question identifiers and expected data structure required for mapping your fields.
Is quoting a single API request?
es. When using a machine key, obtaining a quote requires a single request:
POST /quote
If documents are generated, these are retrieved separately using:
GET /documents?caseid={caseid}
Can SchemeServe call external APIs during the quote process?
Yes. External API calls can be incorporated into the rating process where additional data is required before producing a quote.
How are documents retrieved?
Documents generated during the quote process can be retrieved using the Documents endpoint.
Additional implementation may be required where documents originate from external third-party APIs.
Can I query all referred cases via the API?
The /cases/caserecords endpoint exposes a referred boolean on individual case records, however the API does not currently support filtering or querying records based on this field.
Can I automate reports?
Yes. Reports can either be:
Generated and retrieved using the API.
Delivered automatically via SFTP (find more information here)
Can we replicate raw SchemeServe data into our own database?
Yes, data can be extracted either via the open API or through the report export feature. You can find what API endpoints are available in our API docs.
Data in the API is real-time and the rate limits are currently 100 requests per rolling minute. For best practices, it highly depends on your requirements and setup; this is usually assessed and determined by your engineers, but we're here to advise and support where needed.
How can I retrieve automatically calculated refund values via the API following an MTA or policy cancellation?
Refund values are available on any Question object that includes the CancellationCalculation property. These values can be accessed through the Question Sets API.
More information is available here: https://api.schemeserve.com/questionsets/openapi/index.html#/QuestionSets/QuestionSets_Post
Are document download responses returned as Base64 encoded content?
No. The Documents API does not return document content as Base64-encoded data.
Can we cancel a policy via API?
Cancelling via API isn’t supported yet, but it’s already in our plans.
What format are the documents returned in by the API response?
The Documents API returns a download URL rather than embedding the document content directly in the API response. Your integration can then make a subsequent HTTP request to that URL to download the document programmatically - this way no manual user interaction would be required.
.png)
