The API Builder allows SchemeServe to communicate with external systems by sending and receiving data via APIs. This enables integrations with payment providers, sanctions checking services, CRMs, document services, and many other third-party applications.

The API Builder provides a graphical interface for creating API requests without writing code, allowing you to configure the request, pass SchemeServe data dynamically, and process the response.

Before You Begin

Before creating an API, you should have:

• API documentation from the third-party provider.
• The API endpoint (URL).
• Authentication details (API Key, Bearer Token, OAuth etc.).
• A successful test request in Postman or another API testing tool.
• An understanding of what data needs to be sent and what data will be returned.

Best Practice: Always confirm the API works outside of SchemeServe before recreating it in the API Builder.

Creating an API

Navigate to:

Admin → Jump in any policy → Find API builder in the bottom right

From here you can create a new API and configure its request.

An API consists of several sections:

• Request
• Authentication
• Headers
• Body
• Response Mapping

Each section controls a different part of the communication between SchemeServe and the external service.

Request Configuration

The request defines how SchemeServe communicates with the external system.

Typical settings include:

The values entered here should match the API provider's documentation.

Using Dynamic Data

One of the key features of the API Builder is the ability to insert SchemeServe data into the request.

Rather than sending fixed values, you can reference information from the current policy, case or answers using formulas.

Examples include:

• Customer name
• Premium
• Policy reference
• Agent information
• Answers to questions
• System fields

Dynamic values are evaluated when the API runs, ensuring each request contains the correct data.

Encoding System IDs

Some APIs require values to be URL encoded before they are sent. URL encoding replaces special characters (such as spaces, & and /) with a format that can be safely transmitted in a URL.

If your API documentation specifies that a parameter should be URL encoded, you can use the UrlEncode() function within your formula.

Example

Suppose you want to pass the policy reference in a URL.

Without encoding:

https://api.example.com/payment?reference=##[Policy.Reference]##

If the policy reference is:

ABC 123/01

The generated URL would be:

https://api.example.com/payment?reference=ABC 123/01

This may not be accepted by the API because of the space and / character.

Instead, encode the value:

https://api.example.com/payment?reference=##[UrlEncode([Policy.Reference])]##

The generated URL becomes:

https://api.example.com/payment?reference=ABC%20123%2F01

This encoded value can be safely transmitted to the external API.

Encoding Other System IDs

The same approach can be used with any system ID or question value.

For example:

Encode an email address:

##[UrlEncode([Customer.Email])]##

Encode a customer name:

##[UrlEncode([Customer.FullName])]##

Encode a hidden question:

##[UrlEncode([PaymentReference])]##

Best Practice

Only encode values when the API documentation requires it, or when they are being passed as part of a URL (such as query string parameters). Values sent within a JSON request body should generally not be URL encoded unless explicitly required by the API provider.

Formula Testing

Before using a formula within an API, it is recommended to test it using the Formula Tester.

Admin → Jump in any policy → Find the formula tester in the bottom right

This allows you to confirm that:

• the formula is valid
• the correct value is returned
• the correct system field is being referenced

Testing formulas before adding them to an API can significantly reduce troubleshooting later.

Authentication

Many APIs require authentication before requests are accepted.

Common methods include:

• API Key
• Bearer Token
• Basic Authentication
• OAuth

The authentication method and required headers will be defined in the provider's documentation.

Store authentication values securely and avoid exposing sensitive credentials unnecessarily.

Request Body

The request body contains the information being sent to the external service.

Depending on the API, this may be:

• JSON
• XML
• Form Data

Initially, it is often easier to build the request using hardcoded values.

Once the request is working, replace those values with dynamic SchemeServe formulas.

Response Mapping

After the API executes, the external system returns a response.

The API Builder allows you to decide which values should be stored within SchemeServe.

Common examples include:

• Payment links
• Quote references
• Customer IDs
• Status codes
• Validation results

These values can be mapped into hidden questions or other SchemeServe fields for use elsewhere in the customer journey.

Running an API

An API does not execute automatically simply because it has been created.

It must be triggered from elsewhere within the scheme, for example:

• A Rule
• A Rating File
• A workflow action
• Another supported process

Choose the trigger that best suits your business process.

Testing Your API

Before deploying an API into production:

• Confirm the endpoint is correct.
• Verify authentication is working.
• Test with realistic policy data.
• Confirm dynamic formulas return the expected values.
• Check the response is successfully mapped into SchemeServe.
• Validate any downstream processes that use the returned data.

Troubleshooting

If an API is not working as expected:

• Confirm the API works in Postman.
• Check the endpoint URL.
• Verify authentication credentials.
• Ensure all required headers are present.
• Test each dynamic formula individually.
• Review the request body for formatting issues.
• Check that response mappings match the returned data.

Most API issues are caused by incorrect authentication, invalid formulas, missing headers or incorrectly formatted request bodies.

Best Practices

• Build and test the API in Postman before using SchemeServe.
• Use the Formula Tester to validate dynamic values.
• Replace hardcoded values only after confirming the request works.
• Map only the response fields you need.
• Use meaningful names for APIs and hidden questions.
• Test thoroughly in a non-production environment before deployment.