New Business, MTA and Renewal API endpoints
SchemeServe's modern Quote APIs allow you to build your own quotation and policy servicing journeys while SchemeServe handles the underlying insurance processing.
Whether you're developing a broker portal, customer-facing application or integrating with an external system, you can use the APIs to create New Business quotations, submit Mid-Term Adjustments (MTAs), process Renewals and cancel policies.
This guide explains how to approach each journey, retrieve existing policy information and manage answers when submitting policy changes.
Ready to explore the technical detail? For endpoint specifications, schemas and implementation examples, visit the SchemeServe API documentation
Can't see the relevant functionality? Please submit your feedback here and explain what additional endpoints would be useful.
01 · UNDERSTANDING THE POLICY LIFECYCLE
Before implementing the APIs, it's important to understand how SchemeServe manages cases and case records.
A Case represents the overall policy lifecycle, while Case Records represent individual transactions within that lifecycle, such as New Business, MTAs and Renewals.
A single Case can therefore contain multiple Case Records.
For example:
| Transaction | Case ID | Case Record ID |
|---|---|---|
| New Business | 12345 | 1001 |
| First MTA | 12345 | 1002 |
| Second MTA | 12345 | 1003 |
| Renewal | 12345 | 1004 |
These IDs are illustrative.
The Case ID remains the same in this example, while each transaction has its own Case Record ID.
02 · IMPLEMENTING NEW BUSINESS QUOTATIONS
Use the New Business Quote API when you want to create a new quotation from an external application.
Recommended implementation flow:
Before building your New Business quotation journey, retrieve the relevant scheme's published Question Set using the Question Sets API:
GET /questionsets/scheme/{id}/publishedThe Question Set provides the questions, System IDs, answer options and validation settings needed to build your integration.
Use the
showOnFirstPremiumQuote property to identify which questions are applicable to New Business quotations.Use this information to build your quotation form, ensuring your application collects the relevant answers and maps them to the correct SchemeServe question identifiers before submitting the quotation.
Map the information collected in your own application to the corresponding SchemeServe question identifiers and expected answer formats.
Before submitting the quotation, you can use the Validation APIs to check the information collected through your external application. This helps identify validation errors earlier, allowing customers to correct their answers before proceeding to quotation.
Submit the quotation data and answers using the request structure defined in the Quote API documentation.
POST /quote
SchemeServe processes the submitted information against the product configuration, including rating and underwriting rules.
Your integration can use the returned quotation outcome and relevant identifiers to continue the customer journey.
Where required, retrieve associated documents through the Documents API and use the relevant supported lifecycle operations to progress the quotation.
Customer completes your quotation form → Application validates the submitted data → Any validation errors are presented to the user → Your application submits valid information → SchemeServe further validates and rates the risk → Quotation outcome returned → Your application displays the result.
03 · IMPLEMENTING MID-TERM ADJUSTMENTS (MTAs)
The MTA API allows you to submit changes to an existing policy without requiring users to start a new quotation journey.
For example, a customer might need to update their address, change a risk detail or amend information already held against their policy.
Recommended implementation flow:
Identify the Case Record representing the policy information you want to amend.
You can retrieve its details using:
GET /cases/caserecords/{id}This allows your integration to retrieve information about the selected Case Record.
To build your MTA journey, you'll need both the existing policy answers and the scheme's published Question Set.
Retrieve the existing answers: Use
GET /cases/caserecords/{id}/answers to retrieve the answers already stored against the relevant Case Record. This allows your application to pre-populate the customer's existing policy information.Retrieve the Question Set: Use the Question Sets API to retrieve the scheme's published Question Set:
GET /questionsets/scheme/{id}/publishedThe Question Set provides the questions, System IDs, answer options and validation settings needed to build your integration.
Check the
showOnMtaQuote property to identify questions configured for MTAs, including any additional questions that may not have been presented during New Business.Use both together to determine which information the customer needs to review, update or provide before submitting the MTA.
Allow the user to update the relevant information in your application.
For example:
| Question | Existing answer | Updated answer |
|---|---|---|
| Property postcode | AB1 2CD | AB1 3EF |
| Business activity | Retail | Retail |
| Number of employees | 5 | 5 |
Before submitting the MTA, you can use the Validation APIs to check the updated policy information. This helps identify potential issues with the changed answers before submitting the adjustment
You only need to submit the changed answers using
POST /quote/adjustmentUnlike a full quotation journey, the MTA endpoint does not require all the existing policy answers to be submitted again.
In the example above, your integration would submit the updated postcode answer, rather than resending the unchanged business activity and employee information.
You must still include any other mandatory fields required by the MTA request schema.
SchemeServe processes the adjustment using the relevant product configuration.
Your application can then handle the updated pricing, validation or underwriting outcome, including any referral that requires further review.
Where applicable, retrieve the documents associated with the resulting Case Record and use the relevant lifecycle operations to progress the adjustment.
Customer opens existing policy → Application retrieves Case Record and existing answers → Application retrieves Question Set and identifies MTA questions → Customer updates information → Application validates answers (optional) → Application submits changed or new answers through MTA API → SchemeServe processes adjustment → Updated outcome returned.
The ability to submit only changed answers is particularly useful when building self-service portals and external policy administration journeys as it reduces the amount of information your integration needs to send and avoids unnecessarily resubmitting answers that have not changed.
When building your integration, we recommend comparing the updated information against the original answers and identifying which values need to be included in the MTA request
04 · IMPLEMENTING RENEWALS
The Renewal API allows you to create a renewal transaction for an existing policy through your external application.
It can be used to build broker renewal journeys, customer renewal portals or integrations with other policy management systems.
Recommended implementation flow:
Locate the relevant Case and Case Record for the existing policy using
GET /cases/caserecords/{id}To build your Renewal journey, you'll need both the existing policy answers and the scheme's published Question Set.
Retrieve the existing answers: Use
GET /cases/caserecords/{id}/answers to retrieve the answers already stored against the relevant Case Record. This allows your application to pre-populate the customer's existing policy information for review.Retrieve the Question Set: Use the Question Sets API to retrieve the scheme's published Question Set:
GET /questionsets/scheme/{id}/publishedThe Question Set provides the questions, System IDs, answer options and validation settings needed to build your integration.
Check the
showOnRenewalQuote property to identify questions configured for Renewals, including any additional questions that may not have been presented during the previous policy period.Use both together to determine which information the customer needs to review, update or provide before submitting the Renewal.
Allow the customer to review their existing policy information, make any necessary changes and answer any additional questions required for the Renewal.
Your integration should use the Question Set configuration and Renewal API request schema to determine which information needs to be collected and submitted.
Before submitting the renewal, you can use the Validation APIs to check the information being submitted for the next policy period.
This helps identify potential validation errors before the renewal is processed, allowing your application to address any issues earlier in the journey.
Submit the renewal using
POST /quote/renewal.Similar to the MTA endpoint, you only need to submit changed or new answers, rather than resending all existing policy information.
You must still include the required policy identifiers and any other mandatory fields defined in the Renewal API request schema.
SchemeServe processes the renewal using the relevant product configuration, including validation, rating and underwriting rules.
Your application can then display the renewal outcome, handle referrals where applicable and progress the transaction using supported operations.
Where generated, retrieve associated renewal documents using the Documents API.
Existing policy identified → Application retrieves policy answers → Application retrieves Question Set and identifies Renewal questions → Customer reviews and updates information → Application validates updated information (optional) → Application submits changed or new answers through Renewal API → SchemeServe calculates renewal outcome → Application presents renewal details.
You only need to submit the changed or new answers using
POST /quote/renewal.Similar to the MTA endpoint, the Renewal API does not require all existing policy answers to be submitted again.
For example, if a customer reviews their existing policy information and only updates their annual turnover, your integration would submit the updated turnover answer rather than resending all unchanged information.
You must still include any other mandatory fields required by the Renewal request schema.
05 · POLICY CANCELLATION
The Cancellation API allows you to cancel existing policies through your own applications and external systems.
Using POST /quote/cancel, SchemeServe creates a Cancellation Case Record, treated as an Adjustment, and cancels the associated policy.
Recommended implementation flow:
Identify the relevant policy using its SchemeServe
caseId.This is the identifier required by the Cancellation API to locate the policy and create the associated Cancellation Case Record. If your integration already stores the Case ID, no additional API call is required.
Allow the user to confirm the cancellation and provide the effective cancellation date.
The API accepts two request fields:
caseId - The identifier of the Case to cancel.cancellationDate - The effective cancellation date.
Submit the cancellation request using:
POST /quote/cancelExample request body:
{
"caseId": 12345,
"cancellationDate": "2026-11-06T00:00:00Z"
}
SchemeServe creates a Cancellation Case Record, treated as an Adjustment, and cancels the associated policy.
Refer to the Cancellation API documentation for the full technical specification.
The API returns the Cancellation Case Record details, including relevant premium information and any validation errors.
Your application should handle the response, confirm the cancellation outcome and display the relevant information to the user.
Existing policy identified → User confirms cancellation and effective date → Application submits cancellation request → SchemeServe creates Cancellation Case Record and cancels the policy → Application receives and displays the outcome.
06 · API endpoint summary
| API endpoint | Purpose |
|---|---|
GET /questionsets/scheme/{id}/published |
Retrieve the published Question Set for a product |
POST /quote |
Create a New Business quotation |
GET /cases/caserecords/{id} |
Retrieve Case Record details |
GET /cases/caserecords/{id}/answers |
Retrieve existing answers for a Case Record |
POST /quote/adjustment |
Submit a Mid-Term Adjustment |
POST /quote/renewal |
Submit a Renewal |
|
Submit a Cancellation |
07 · ADDITIONAL IMPLEMENTATION CONSIDERATIONS
| Authentication |
For most server-to-server integrations, SchemeServe recommends Machine Keys.
Admin → Settings → API Keys
|
|
Managing Case and Case Record IDs |
Store the identifiers returned by SchemeServe and make sure your integration can distinguish between the overall Case and its individual transactions. An MTA or Renewal may have a different Case Record ID from the original New Business quotation. |
|
Pre-populating your external application |
For MTAs and Renewals, retrieving existing answers can improve the user experience significantly. Rather than asking users to re-enter information SchemeServe already holds, your application can present their existing details and allow them to make the necessary updates. |
| Handling underwriting outcomes |
Not every quotation, adjustment or renewal will result in an immediately acceptable outcome. Your integration should be designed to handle validation errors, referrals and declines where applicable. |
|
Retrieving documents |
Generated documents are retrieved separately through the Documents API. For example:
|
|
Payments and policy placement |
If your integration includes payment collection, this may be handled through an external payment provider. Payment collection and placing a policy on cover are separate operations. Completing a payment does not automatically mean the policy has been placed on cover in SchemeServe. The appropriate workflow should be confirmed as part of your integration design. |
| API rate limits |
SchemeServe's general API guide specifies a limit of 100 requests per rolling minute. Avoid repeatedly retrieving unchanged information unnecessarily and account for this limit when designing your integration. |
08 · KNOWN LIMITATIONS
Current limitations to be aware of
09 · FAQ
Common integration questions
Do I need to retrieve all existing answers before submitting an MTA?
Not necessarily. If your integration already has the correct existing information, you may be able to identify the changes without retrieving the answers again.
However, retrieving the latest answers is recommended when you need to display existing policy information or ensure your application is working with current data.
Do I need to resubmit all answers when creating an MTA?
No. The MTA endpoint only requires changed answers, alongside the mandatory request fields.
Can I pre-populate my own MTA and Renewal journey with existing policy information?
Yes. Use the Case Record details and answers endpoints to retrieve information that can be displayed in your own application.
Can I use the same Case Record ID for New Business, MTAs and Renewals?
You should not assume so. A single Case can contain multiple Case Records, each representing a different transaction.
Can I retrieve documents through the Quote API response?
Documents should be retrieved separately through the Documents API.
Can I build a fully branded customer or broker portal using these APIs?
Yes. Your application can manage the customer-facing experience while SchemeServe handles the supported quotation, underwriting and policy processing operations.
Ready to start your SchemeServe integration?
Review the current API documentation for available APIs, endpoints, schemas and implementation details.
.png)
