How to run the validation suite against your integration
You must run Maxsight's validation suite before your integration can be added to Maxsight. The validation suite tests your integration’s response against a number of scenarios to ensure the appropriate responses are provided to particular requests. You can think of this as a number of unit tests for your integration before it gets into Maxsight.
The validation suite runs at least 20 tests, and possibly more, depending on your check type/template. These happen in rapid succession and should be treated as independent requests as these occur asynchronously.
Note
It's important to know that the validation suite tests against your integration’s demo responses. This is how your integration responds to requests with a demo_result value.
This therefore means the validation suite doesn't test your integration’s live responses, so these must be tested accordingly.
To run the validation suite against your integration:
Log in to your Maxsight institution.
Select Policy Builder and then Data provider.
Select + New data provider and choose if your integration is for individual or company entities.
Select the associated custom check type of your integration.
You must select an integration that begins with the word Custom as these are the check types on which you are allowed to run the validation suite manually.
For example, if you’re adding a new custom check for individuals, you would select Custom individual custom check.
Add your integration URL and secret key and select Run validation.
How validation tests are performed
Every request from Maxsight contains the field demo_result. This is the field that indicates whether a demo response is required or not. In a live production environment, the demo_result is null. If the demo_result value is null, a live check should be run. In all other circumstances where demo_result isn't null, demo or “dummy“ responses should be returned.
For example, in the following example the demo_result value is set to ERROR_INVALID_CREDENTIALS, which indicates a particular demo error response is expected.
{
"id": "96ab8cdd-07f9-46ae-93e5-2fa63d2e9f43",
"demo_result": "ERROR_INVALID_CREDENTIALS",
"commercial_relationship": "DIRECT",
"check_input": {
"entity_type": "INDIVIDUAL",
"address_history": [
{
"address": {
"type": "STRUCTURED",
"country": "CAN",
"postal_code": "A1 1AA",
"postal_town": "Somewhereville",
"route": "Somewhere St",
"street_number": "1"
}
}
],
"personal_details": {
"dob": "1990-01-01",
"name": {
"family_name": "Smith",
"given_names": [
"John"
]
}
}
},
"provider_config": {},
"provider_credentials": null
}Even when returning error responses to error demo_result values, a 200 status code should be returned. This is so Maxsight knows that your integration correctly handled errors and the integration itself hasn't errored.
The provider_credentials field is always null in requests from the validation suite, so any logic requiring provider_credentials should be ignored during requests with a demo_result value that is not null.
The content of the request can be ignored. Any responses are tested to ensure the correct fields and data values are returned, and don't have to be related to the request. This means hard-coded values can be used, and are encouraged, when responding to requests with demo_result value that is not null.
If you are building an integration that uses callbacks, be aware that /checks and /checks/<id>/complete are both used by the validation suite. Any responses to the error demo_result values should still be returned as normal from the /checks endpoint and don't need to be implemented to the /checks/<id>/complete or /checks/<id>/get_result endpoints. However, the UNSUPPORTED_DEMO_RESULT error response should only be returned from the /checks/<id>/complete or /checks/<id>/get_result endpoints.
The validation suite expects responses within a couple of seconds, so avoid applying any actual live logic or making requests to external APIs during the validation suite, in other words requests with a demo_result value that is not null. If your integration takes more than a few seconds to respond, this can cause issues and likely fails the validation suite without warning.
For requests that are incorrectly signed and/or have an invalid secret key, use 4xx status codes in your responses, as outlined previously. For all other errors that are handled by your integration and use the standard error responses, use a 200 status code. To learn more, see Validation suite tests for error responses.
Validation suite tests
The following links provide more information about the validation suite tests: