Integration endpoints
In order for your integration to meet the specifications of a Maxsight integration, you must implement a number of required endpoints so that Maxsight and your integration can communicate correctly.
The required endpoints are determined by the integration check type and check template.
Core endpoints required for all integrations
Checks endpoint
The checks endpoint is where initial requests are sent. The request and response payloads are determined by the integration check_type and check_template.
All integrations regardless of type must serve up this endpoint.
Implementation
The endpoint is implemented using a /checks
from the base URL of your integration.
https://your-integration.example.com/checks
HTTP request
POST https://your-integration.example.com/checks
Maxsight request to endpoint example: INDIVIDUAL_CUSTOM
check type
{ "id": "4e496b20-d256-444e-a329-d20c7298e842", "demo_result": null, "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" } } ], "contact_details": { "email": "someone@somewhere.com", "phone_number": "0131 496 0007" }, "personal_details": { "dob": "1990-01-01", "name": { "family_name": "Smith", "given_names": [ "John" ] } } }, "provider_config": {}, "provider_credentials": { "api_token": "x123456" } }
Response example: INDIVIDUAL_CUSTOM
check type
{ "errors": [], "warnings": [], "result": { "decision": "PASS", "summary": "The entity was found and verified in our system." } }
Associated check templates
All integrations must implement this endpoint.
Configuration endpoint
The configuration endpoint defines several important properties about your integration. Most parts of the configuration are common to all integrations, but the check_type and check_template are specific to each type of integration.
All integrations regardless of type must serve up this endpoint.
Implementation
The endpoint is implemented using a /config
from the base URL of your integration.
https://your-integration.example.com/config
HTTP request
GET https://your-integration.example.com/config
Response fields
The following fields are available for the endpoint response:
Field | Type | Required? | Description |
---|---|---|---|
|
| Yes | A check type as listed in the enums. The check type determines the request and response data schemas for your integration. |
| object | Yes | The check template determines the workflow of your integration, such as the request schedule and required endpoints. |
object | Yes | Maxsight no longer supports re-selling so this section can be set to static values. | |
| array of | Yes | Defines which countries your integration is able to support. The exact interpretation of this field varies depending on the check type, but it typically reflects country of residence for individuals and the country of incorporation for companies. This field is an array of strings, which should be the ISO3 country code for the country. At least one country must be specified. |
| array of | No | Allows your integration to declare support for additional features. The absence of this field from your integration's config implies that no additional features are supported. |
array of objects | Yes | The credentials field contains exactly one field, You must provide at least one | |
array of objects | Yes | Like |
Field details
Details for the objects associated with the /config
response.
pricing
response fieldsField | Type | Required? | Description |
---|---|---|---|
| boolean - only false allowed | Yes | Whether your integration supports being configured for reselling. Maxsight no longer supports reselling and so this should always be set to |
| number | No | Deprecated as reselling is no longer supported. |
credentials
response fieldsField | Type | Required? | Description |
---|---|---|---|
| One of " | Yes | The type of the credential field. |
| string | Yes | The name of the field which is used when sent to your integration. |
| string | Yes | The name that's displayed for this field in Maxsight. |
config
response fieldsField | Type | Required? | Description |
---|---|---|---|
type | One of | Yes | The type of the configuration field. |
| string | Yes | The name of the field which is used when sent to your integration. |
| string | Yes | The name that's displayed for this field in Maxsight. |
| string | No | A short description that is displayed using a tooltip with the configuration item in Maxsight. |
array of objects | No | An Only applicable to (and required for) the | |
| A valid value allowed by the type specified in | Yes | The default value for this configuration field. For |
| boolean | No | Specify whether this config field is required. |
| A valid value allowed by the type specified in | No | The maximum value allowed for the config field. This is only applicable to |
| A valid value allowed by the type specified in | No | The minimum value allowed for the config field. This is only applicable to |
| A valid value allowed by the type specified in | No | The increment value with which users change the value of this field. This is only applicable to |
options
response fieldsField | Type | Required? | Description |
---|---|---|---|
| string | Yes | The name that's displayed for this option in the |
| string | Yes | The value of the field which is used when sent to your integration. |
Response example
{
"check_type": "IDENTITY_CHECK",
"check_template": {
"type": "ONE_TIME_SYNCHRONOUS",
"timeout": 60
},
"pricing": {
"supports_reselling": false,
"maximum_cost": 0
},
"supported_countries": ["GBR", "USA", "CAN"],
"credentials": {
"fields": [
{
"type": "string",
"name": "username",
"label": "Username"
},
{
"type": "password",
"name": "password",
"label": "Password"
}
]
},
"config": {
"fields": [
{
"type": "boolean",
"name": "boolean_config",
"label": "Boolean config field",
"subtext": "A description of the option",
"default": false
},
{
"type": "MultiSelect",
"name": "multiselect_config",
"label": "Config field with dropdown options",
"subtext": "A description of the option",
"options": [
{"label": "Option 1", "value": "option_1"},
{"label": "Option 2", "value": "option_2"},
{"label": "Option 3", "value": "option_3"}
],
"default": null
}
]
}
}
Associated check templates
All integrations must implement this endpoint.
Metadata endpoint
This endpoint defines the basic properties of all integrations, which version of the Maxsight Partner API Protocol is being used, and the name of the provider this integration connects to, which is used for display and branding purposes within Maxsight. Currently, the only API Protocol version is 1. This endpoint is unauthenticated to allow future API versions to use different authentication methods.
All integrations regardless of type must serve up this endpoint.
Note
Requests made to this endpoint must not require authentication.
Implementation
The endpoint is implemented at the base URL of your integration.
https://your-integration.example.com/
HTTP request
GET https://your-integration.example.com/
Response fields
The following fields are available for the endpoint response.
Field | Type | Required? | Description |
---|---|---|---|
| number | Yes | An integer representing the version of the version of the Integration API to use. Currently, this is always |
| string | Yes | The integration name. Currently, the name must be at least 6 characters in length, and no greater than 49 characters. |
Response example
{
"protocol_version": 1,
"provider_name": "Your integration name"
}
Associated check templates
All integrations must implement this endpoint.
Callback specific endpoints
Ready endpoint
The ready endpoint is used by Maxsight to inform your integration that it is ready to receive callbacks for a particular reference
.
Implementation
https://your-integration.example.com/checks/<check-id>/ready
HTTP request
POST https://your-integration.example.com/<check-id>/ready
Response fields
The following fields are available for the endpoint response.
Field | Type | Required? | Description |
---|---|---|---|
| array | Yes | If your integration does not recognize the The response is the standard platform error response. |
Response example
{
"errors": []
}
Associated check templates
This endpoint is only required for the check templates:
ONE_TIME_CALLBACK
MONITORED_CALLBACK
Complete endpoint
If implemented, the complete endpoint is where the final request from Maxsight goes to your integration in response to a notification to the Maxsight callback endpoints. This is also where the final check data should be returned in the response.
Requests and response examples depend on the check type and check template.
The complete endpoint is only called when your integration has notified the Maxsight callbacks endpoint that the check has been completed and your integration is ready to provide the response.
Implementation
https://your-integration.example.com/checks/<check-id>/complete
HTTP request
POST https://your-integration.example.com/checks/<check-id>/complete
Maxsight request to endpoint example
{ "id": "2741ba22-ed86-419b-8bb2-3db7162cb0c6", "provider_id": "d1d2dc88-2947-4dd4-a9a8-c3ee047b9183", "reference": "a59c8eb3-f48c-45f1-8366-ec55f1b9c25d", "commercial_relationship": "DIRECT", "provider_config": {}, "provider_credentials": { "api_token": "x12345"}, "custom_data": {} }
Response example
{ "provider_data": {}, "warnings": [], "errors": [], "provider_id": "d1d2dc88-2947-4dd4-a9a8-c3ee047b9183", "reference": "a59c8eb3-f48c-45f1-8366-ec55f1b9c25d", "external_resources": [ { "type": "LINK", "url": "https://caa6-208-127-43-45.ngrok-free.app/api/external_resource/1", "id": "2741ba22-ed86-419b-8bb2-3db7162cb0c6", "label": "Check Result" } ], "check_output": { "entity_type": "INDIVIDUAL", "documents": [ { "category": "PROOF_OF_IDENTITY", "document_type": "PASSPORT", "id": "07b4d550-b7e6-4d2f-a4ff-32fde9c77a3b", "images": [ { "id": "c43bbeba-12b6-4868-80bc-4bd324dbe4e1" } ], "extracted_data": { "address_history": [], "expiry": "2030-01-01", "issued": "2020-01-01", "issuer": "United Kingdom", "issuing_country": "GBR", "number": "904060458", "personal_details": { "dob": "1915-10-26", "name": { "family_name": "Smith", "given_names": [ "John" ] }, "nationality": "GBR" } }, "verification_result": { "all_passed": true, "image_checks": [ { "category": "Image Quality", "type": "Image resolution", "result": "PARTIAL" }, { "category": "Image Quality", "type": "Image sharpness", "result": "PARTIAL" } ], "image_checks_passed": true, "forgery_checks": [ { "category": "Document Fonts", "type": "Title uses correct font", "result": "PARTIAL" }, { "category": "Checksum", "type": "MRZ has a valid checksum", "result": "PARTIAL" } ], "forgery_checks_passed": true, "document_type_passed": true } } ] } }
Associated check templates
This endpoint is only required for the check templates:
ONE_TIME_CALLBACK
Get result endpoint
If implemented, the get result endpoint is where the final request from Maxsight goes to your integration in response to a notification to the Maxsight callback endpoints. This allows your integration to provide a new update on monitored entities.
Requests and response examples depend on the check type and check template.
The complete endpoint is only called when your integration has notified the Maxsight callbacks endpoint that the check has an update for a monitored entity and your integration is ready to provide the response containing that update.
Implementation
https://your-integration.example.com/checks/<check-id>/get_result
HTTP request
POST https://your-integration.example.com/checks/<check-id>/get_result
Maxsight request to endpoint example
{ "id": "2741ba22-ed86-419b-8bb2-3db7162cb0c6", "provider_id": "d1d2dc88-2947-4dd4-a9a8-c3ee047b9183", "reference": "a59c8eb3-f48c-45f1-8366-ec55f1b9c25d", "commercial_relationship": "DIRECT", "provider_config": {}, "provider_credentials": { "api_token": "x12345"}, "custom_data": {} }
Response example
{ "provider_id": "d1d2dc88-2947-4dd4-a9a8-c3ee047b9183", "reference": "a59c8eb3-f48c-45f1-8366-ec55f1b9c25d", "errors": [], "warnings": [], "external_resources": [ { "type": "LINK", "url": "https://www.example-url-greid.lp/made-up", "id": "f675514a-195a-4c5e-b671-d958015a56bc", "label": "avBfcg" } ], "check_output": { "entity_type": "INDIVIDUAL", "screening_hits": [ { "id": "a2318a8b-ac45-4dfe-8f0e-a9c021cede86", "provider": { "name": "Data provider", "label": "Label", "hit_id": "334545233454" }, "flags": [ { "type": "PEP", "label": "PEP Match" } ], "data": { "name": "Name of hit", "addresses": [ { "type": "UNKNOWN", "label": "Unknown address" } ], "confidence_score": 0.6418837218202788, "gender": "M", "sources": [ { "name": "Source name", "description": "Source desc" } ], "pep": { "roles": [ { "name": "PEP Role", "tier": 3, "tenure": { "start": "1939-01-13", "tenure_type": "CURRENT" } } ], "rating": "Rating", "tier": 2 }, "created_at": "2002-08-02 20:37:58" }} ] }, "update_id": "0Nqhdu2M4uSs", "occurred_at": "1952-01-23T07:37:19Z" }
Associated check templates
This endpoint is only required for the check templates:
MONITORED_CALLBACK
Cancel checks endpoint
If implemented, the cancel checks endpoint is where Maxsight can inform your integration that an entity should no longer be monitored.
Requests and response examples depend on the check type and check template.
Implementation
https://your-integration.example.com/cancel_checks
HTTP request
POST https://your-integration.example.com/cancel_checks
Maxsight request to endpoint example
The request uses the references that would have been generated and monitored by your integration to instruct your integration to cancel the monitoring of these entities.
{ "provider_id": "3d3b040a-a4a1-49f6-b47e-abaff4ff3210", "commercial_relationship": "DIRECT", "provider_config": {}, "provider_credentials": { "api_token": "x123456" }, "references": [ "2d0c0972-1067-429b-9fea-996954ac1f78", "dfc348a8-e0b7-4c68-83c9-e0c6e1c12393" ] }
Response example
You can use the response to inform Maxsight of any issues with the cancellation request. This is done using the standard error response structures.
{ "errors": [], "warnings": [] }
Associated check templates
This endpoint is only required for the check templates:
MONITORED_CALLBACK
Document fetch specific endpoints
Download file endpoint
If implemented, the download file endpoint is used for DOCUMENT_FETCH
check types, where the document was collected by your integration. This endpoint allows Maxsight to download the document that your integration collected during the check, and display it to users in the interface.
Requests and response examples depend on the check type and check template.
Implementation
https://your-integration.example.com/download_file
HTTP request
POST https://your-integration.example.com/download_file
Maxsight request to endpoint example
{ "check_id": "89780c53-2ff4-4a07-82e2-e8cb1af46fe3", "file_reference": "109c7916-908c-4533-b1a8-3178f449d96f", "download_info": { "download_type": "FILE", "file_type": "VIDEO_FRAME" }, "commercial_relationship": "DIRECT", "provider_config": {}, "provider_credentials": { "api_token": "x123456" }, "custom_data": {} }
Response example
In this instance, the response would be the image in raw bytes format.
Associated check templates
This endpoint is only required for the check templates:
ONE_TIME_CALLBACK
ONE_TIME_POLLING
MONITORED_CALLBACK
Company data-specific endpoints
Search endpoint
If implemented, the search endpoint allows your integration to be used to pre-populate a company entity in Maxsight. This endpoint is only required for COMPANY_DATA
check types when the Configuration endpoint specifies support for COMPANY_SEARCH
in the supported_features
array.
The query
field contains whatever text the user has input into the company name while creating the company entity.

The query field in the above example would be Aerial and the matched companies returned by the search endpoint would be shown to the user, who can select the correct company.
Implementation
https://your-integration.example.com/search
HTTP request
POST https://your-integration.example.com/search
Maxsight request to endpoint example
{ "id": "2741ba22-ed86-419b-8bb2-3db7162cb0c6", "demo_result": null, "commercial_relationship": "DIRECT", "search_input":{ "query":"Moody's" "country_of_incorporation":"USA" "state_of_incorporation":"CA" }, "provider_config": {}, "provider_credentials": { "api_token": "x12345"} }
Response example
{ "search_output": [ { "name": "Moody's Corporation", "number": "123456", "country_of_incorporation": "USA", "addresses": [ { "type": "head_office_address", "address": { "type": "FREEFORM", "country": "USA", "text": "Moody's head office" } } ], "contact": { "url": "https://www.example-url-tk.tn/made-up" }, "structure_type": { "is_limited": true, "ownership_type": "PUBLIC" }, "lei": "BAWXXX1234", "bvd_id": "XX9060155" } ], "errors": [], "warnings": [] }
Associated check templates
This endpoint is only required for the check templates:
ONE_TIME_SYNCHRONOUS
MONITORED_CALLBACK
Polling endpoints
Poll endpoint
If implemented, the poll endpoint is used by Maxsight to check for updates on a particular check. Maxsight polls your integration on a set schedule until a valid completed response is received.
The response is considered complete once the pending
field is returned with a value of false
. If not complete, the pending
field should return with a value of true
.
Requests and response examples depend on the check type and check template.
Implementation
https://your-integration.example.com/checks/<check_id>/poll
HTTP request
POST https://your-integration.example.com/checks/<check_id>/poll
Maxsight request to endpoint example
{ "id": "820012fc-17fd-4ce3-9ddf-27d9a301241b", "demo_result": null, "commercial_relationship": "DIRECT", "provider_config": {}, "provider_credentials": { "api_token": "x12345" }, "provider_id": "e94511ec-3a80-4e40-bdec-74ebd7ab7256", "reference": "1b2c27d6-05f7-478c-b2da-2b8a6c43aae5", "custom_data": {} }
Response example: In-progress poll response
Note the pending
field has a value of true
.
{ "errors": [], "warnings": [], "provider_id": "e94511ec-3a80-4e40-bdec-74ebd7ab7256", "reference": "1b2c27d6-05f7-478c-b2da-2b8a6c43aae5", "custom_data": {}, "pending": true }
Response example: Completed poll response
Note the pending
field has a value of false
.
{ "provider_data": {}, "warnings": [], "errors": [], "provider_id": "e94511ec-3a80-4e40-bdec-74ebd7ab7256", "reference": "1b2c27d6-05f7-478c-b2da-2b8a6c43aae5", "pending": false, "external_resources": [ { "type": "LINK", "url": "https://caa6-208-127-43-45.ngrok-free.app/api/external_resource/1", "id": "2741ba22-ed86-419b-8bb2-3db7162cb0c6", "label": "Check Result" } ], "check_output": { "entity_type": "INDIVIDUAL", "documents": [ { "category": "PROOF_OF_IDENTITY", "document_type": "PASSPORT", "id": "07b4d550-b7e6-4d2f-a4ff-32fde9c77a3b", "images": [ { "id": "c43bbeba-12b6-4868-80bc-4bd324dbe4e1" } ], "extracted_data": { "address_history": [], "expiry": "2030-01-01", "issued": "2020-01-01", "issuer": "United Kingdom", "issuing_country": "GBR", "number": "904060458", "personal_details": { "dob": "1915-10-26", "name": { "family_name": "Smith", "given_names": [ "John" ] }, "nationality": "GBR" } }, "verification_result": { "all_passed": true, "image_checks": [ { "category": "Image Quality", "type": "Image resolution", "result": "PARTIAL" }, { "category": "Image Quality", "type": "Image sharpness", "result": "PARTIAL" } ], "image_checks_passed": true, "forgery_checks": [ { "category": "Document Fonts", "type": "Title uses correct font", "result": "PARTIAL" }, { "category": "Checksum", "type": "MRZ has a valid checksum", "result": "PARTIAL" } ], "forgery_checks_passed": true, "document_type_passed": true } } ] } }
Associated check templates
This endpoint is only required for the check templates:
ONE_TIME_POLLING
Maxsight callback endpoints
When using the ONE_TIME_CALLBACK
or MONITORED_CALLBACK
check templates, you must also use the Maxsight callback endpoints for notifying Maxsight of updates or completion. These are defined in the following table for each environment.
You should implement each one of these endpoints in your integration so that users in each Maxsight environment can use your integration.
Check template | EU environment | US environment | UAE environment |
---|---|---|---|
|
|
|
|
|
|
|
|
Integration request to the Maxsight ONE_TIME_CALLBACK endpoint example:
{ "provider_id": "d387578f-883c-4327-8992-df4092a78de3", "reference": "ref-12938" }
Response example:
{ "callback_id": "7220e5c5-6a36-43cd-b175-e981c3e6e0aa" }
Integration request to the Maxsight MONITORED_CALLBACK endpoint example:
{ "provider_id": "b148734a-c966-4f86-a7bb-ac37b801bd09", "reference": "ref-3937820", "update_id": "updated-38372933" }
Response example:
{ "notification_id": "44f2d0a9-2800-448c-8f92-dbf26bc8ee02" }