SCHEMESERVE API BUILDER
Connecting SchemeServe to External Services
The API Builder lets SchemeServe send data to and receive data from external systems without writing custom integration code.
|
SEND Pass SchemeServe policy, customer or question data to another service. |
RECEIVE Receive values such as payment links, references, statuses and validation results. |
USE Store returned data in SchemeServe and use it elsewhere in the customer journey. |
Common integrations include payment providers, sanctions services, CRMs, document services and other third-party applications.
AT A GLANCE
Building an API in SchemeServe
| 1. Prepare | 2. Configure | 3. Map Data | 4. Test | 5. Trigger |
STEP 1
Before You Begin
Before recreating an integration in SchemeServe, make sure you have:
| ✓ Third-party API documentation | ✓ The API endpoint / URL |
| ✓ Authentication details | ✓ A successful test in Postman or similar |
| ✓ An understanding of the data being sent and the data expected back | |
Always confirm the API works successfully outside SchemeServe before recreating the request in the API Builder.
STEP 2
Create the API
Admin → Jump in any policy → Find API Builder in the bottom-right.
Each API is made up of five main areas:
| Request | Authentication | Headers | Body | Response |
Request Configuration
The request tells SchemeServe how to communicate with the external service. The values should match the provider's API documentation.
| Method | GET, POST, PUT, PATCH or DELETE. |
| URL | The endpoint supplied by the third-party provider. |
| Headers | Additional information such as authentication credentials or content type. |
| Body | The information being sent to the external service. |
STEP 3
Add Dynamic SchemeServe Data
Rather than sending the same fixed value every time, API Builder formulas can insert information from the current SchemeServe policy or case into the request.
| Customer name | Premium | Policy reference |
| Agent information | Question answers | System fields |
URL Encoding Dynamic Values
Some APIs require values used inside URLs to be URL encoded. This converts characters such as spaces, & and / into a format that can safely be transmitted.
Policy reference:
ABC 123/01 Use:
##[UrlEncode([Policy.Reference])]## Result:
ABC%20123%2F01
##[UrlEncode([Customer.Email])]## |
|
| Customer name | ##[UrlEncode([Customer.FullName])]## |
| Hidden question | ##[UrlEncode([PaymentReference])]## |
Use URL encoding when required by the API documentation or when a dynamic value forms part of a URL or query string. Values inside a JSON request body should generally not be URL encoded unless the provider specifically requires it.
Test Your Formulas First
Admin → Jump in any policy → Find Formula Tester in the bottom-right.
Use it to confirm:
✓ The formula is valid
✓ The expected value is returned
✓ The correct SchemeServe field is being referenced
REQUEST SECURITY
Authentication
Many external APIs require authentication. The method you use must match the provider's documentation.
| API Key | Bearer Token | Basic Auth | OAuth |
Store authentication information securely and avoid unnecessarily exposing API keys, tokens or other sensitive credentials.
Request Body
The request body contains the information SchemeServe sends to the external service. Depending on the provider, this may use:
| JSON | XML | Form Data |
It is often easier to make the request work using hardcoded test values first. Once successful, replace those values with SchemeServe formulas.
STEP 4
Map the Response
When the external API responds, you can choose which returned values should be stored in SchemeServe.
| Payment links | Quote references |
| Customer IDs | Status codes |
| Validation results | |
STEP 5
Trigger the API
It must be triggered from elsewhere within the SchemeServe scheme.
| Rule | Rating File | Workflow Action | Supported Process |
BEFORE GOING LIVE
Testing Your API
Troubleshooting
Most API problems come down to four areas:
| Authentication | Formulas | Headers | Request Body |
Troubleshooting checklist
If the API is not working as expected:
• Confirm the request still works in Postman.
• Check the endpoint URL.
• Verify authentication credentials.
• Confirm all required headers are present.
• Test dynamic formulas individually.
• Review the request body format.
• Check response mappings against the actual returned data.
GOOD API BUILDER HABITS
Best Practices
| ✓ Build and test externally first. |
| ✓ Use Formula Tester before adding dynamic values. |
| ✓ Start with hardcoded test values, then replace them with formulas. |
| ✓ Map only the response fields you actually need. |
| ✓ Give APIs and hidden questions meaningful names. |
| ✓ Test thoroughly outside production before deployment. |
Test the API externally → recreate the working request → add SchemeServe formulas → map the response → choose the correct trigger → test the complete journey.
Need help with an API Builder integration?
Check the external provider's API documentation first, then review the request, formulas, authentication and response mapping in SchemeServe.
.png)
