SCHEMESERVE API GUIDE
Integrating with SchemeServe
Use the SchemeServe API to connect external applications, broker portals, customer journeys and business systems to SchemeServe.
|
BUILD Create broker portals, customer journeys, mobile applications and internal tools. |
CONNECT Exchange data between SchemeServe and CRMs, claims systems, rating services and other applications. |
AUTOMATE Automate quotations, documents, reporting, claims and back-office processes. |
For endpoint specifications, schemas and technical examples, use the SchemeServe API documentation .
The legacy SchemeServe API has been deprecated and is no longer available for new integrations.
01 · 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 | Retrieve documents generated against a case or specific case record. ✓ Available |
| Document upload | Upload externally generated documents and associate them with SchemeServe records. ✓ Available |
| Document import from URL | Allow SchemeServe to retrieve and attach a file hosted by an external service. ✓ 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?
The authentication method depends on the type of integration you are building.
|
Machine-to-Machine (API Key) Recommended for most direct system-to-system integrations where no SchemeServe user needs to sign in. Typical uses: x-api-key: YOUR_MACHINE_KEY |
Bearer Token (JWT) Used when API requests need to represent a specific authenticated SchemeServe user. Typical uses: Authorization: Bearer YOUR_TOKEN |
Machine Keys can be rotated at any time and SchemeServe does not enforce a fixed rotation schedule. Clients can manage and rotate 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.
User-based JWT authentication uses short-lived access tokens that rotate approximately every 15 minutes, with refresh tokens used to maintain authenticated sessions.
For direct system-to-system integrations, Machine Keys are generally recommended instead.
Some APIs require a SchemeServe Site ID to identify the SchemeServe environment the request relates to. It is an additional identifier rather than an authentication method.
Site-Id: myscheme
Certain browser-based integrations may require an Origin header for Cross-Origin Resource Sharing (CORS). Browsers will normally add this automatically.
Origin: https://portal.company.com
03 · 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.
Understand the questions, identifiers and data structure required for the product.
Map fields from your external journey to the corresponding SchemeServe questions.
Send the structured answers through the Quote API.
SchemeServe validates the answers and runs the configured rating and underwriting rules.
Your application receives the result, such as quoted, referred or declined.
Any documents generated during the process are retrieved separately using the Documents API.
|
The Question Set API provides • Question identifiers • Question types • Available answer options • Expected data structures • Validation rules where applicable |
Why it matters Every SchemeServe product has its own Question Set. Your external application must map its data to the correct structure before submitting quotations. |
When using a Machine Key, a quotation can be requested using a single API call:
POST /quote
AI-assisted quotation submissions
An external AI service can read an email, PDF, spreadsheet or proposal form and convert the information into structured data for SchemeServe.
1. A broker sends an email, PDF, spreadsheet or proposal form.
2. The AI service extracts the relevant risk information.
3. The information is mapped to the SchemeServe Question Set.
4. The AI solution submits the structured answers through the Quote API.
5. SchemeServe validates, rates and underwrites the submission.
6. A human reviews the result where required.
|
SchemeServe provides • Question Set structure • Quote validation • Rating and underwriting • Pricing and quote outcomes |
The external AI provider handles • Document interpretation • Data extraction • Field mapping • Confidence checks • Human-review workflows |
External data and underwriting services
SchemeServe can call an external API during quotation when additional information is required before producing a price or underwriting decision.
| Flood-risk checks | Subsidence information |
| Property enrichment | Geocoding |
| Credit or sanctions checks | External pricing services |
The external endpoint must use an authentication mechanism supported by SchemeServe. Where specialist authentication is required, such as MFA, TOTP generation or complex token refresh, middleware may be needed.
SchemeServe → Client middleware → External service
04 · DOCUMENTS
Retrieving, uploading and importing files
|
Retrieve documents Documents generated by SchemeServe can be retrieved after a case transaction completes. GET /documents?caseid={caseid} To retrieve documents attached only to a specific record: GET /documents?caserecordid={caserecordid}
|
Upload documents External documents can be uploaded using the File Upload API and associated with the relevant SchemeServe case. This can be used for supporting evidence, externally generated documents or files received through another application. |
The Documents API returns a fully qualified download URL containing a temporary SAS access token rather than returning the document as Base64 data.
The integration can use that URL to download the document programmatically.
The underlying document URL remains the same, but the SAS token is temporary. If it expires, query the Documents API again to receive a fresh token and download URL.
Document URLs are not IP-whitelisted. Access is controlled by the temporary SAS token.
SchemeServe can retrieve a file hosted by an external service, store it and associate it with the relevant case.
This can also support protected endpoints where a supported authentication method is available.
FileUploadsApi - fileuploads/uploadurl
05 · PAYMENTS & BINDING
Using an external payment journey
A custom quotation journey can use an external payment provider and pass the relevant payment outcome or transaction details into SchemeServe.
1. SchemeServe produces the quotation.
2. The customer completes payment through the external 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.
Payment collection is normally handled externally. Binding and payment should be treated as separate integration processes unless otherwise confirmed for the specific implementation.
06 · POLICY LIFECYCLE
Cases, records, MTAs, renewals and referrals
A single SchemeServe case can 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 record ID.
|
Mid-Term Adjustments In development Planned capabilities include: • MTA creation • Updating case answers • Validation • Revised pricing • Status progression • Document generation |
Renewals In development Planned capabilities include: • Renewal creation • Updating answers • Validation and 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.
The final renewal release scope will confirm whether all renewal actions can be completed entirely through the API.
Case synchronisation
SchemeServe can be connected to a CRM, data platform or policy administration system so quotation, case and record information can be stored externally.
Relevant capabilities may include Cases API, Case Records API, record identifiers, policy identifiers where available, status retrieval and updating answers.
Availability of case-level status, changed-since queries and retrieval of all records by Case ID should be confirmed against the specific integration requirements.
Referral status
An external application can identify whether an individual case record has been referred following rating or underwriting and route the case for manual review where required.
The API does not currently support querying or filtering all referred cases as a single list.
07 · DATA & REPORTING
Getting SchemeServe data into your reporting environment
|
API reporting Request SchemeServe data in real time and store, combine or visualise it within your own reporting environment. |
Scheduled SFTP SchemeServe can generate scheduled report files for delivery to a client-managed SFTP server. |
Typical uses include Power BI dashboards, broker performance reporting, underwriting MI, product governance, Consumer Duty reporting, fair-value monitoring, operational reporting and 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.
08 · CLAIMS
Connecting external claims processes
Clients and third-party claims administrators can use the Claims API to connect external claims processes with SchemeServe.
1. A claim is created or updated in the 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.
Available claims capabilities should be reviewed against the current API documentation and the exact requirements of the integration.
09 · BEFORE YOU BUILD
Current limitations to be aware of
10 · FAQ
Common integration questions
Which API should I use?
Use the current SchemeServe API 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.
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 Admin user level.
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)
