Skip to main content

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

check_type

CheckType enum (string)

Yes

A check type as listed in the enums. The check type determines the request and response data schemas for your integration.

check_template

object

Yes

The check template determines the workflow of your integration, such as the request schedule and required endpoints.

pricing

object

Yes

Maxsight no longer supports re-selling so this section can be set to static values.

supported_countries

array of Country enum (string)

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.

supported_features

array of SupportedFeatures enum (string)

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.

credentials

array of objects

Yes

The credentials field contains exactly one field, fields, which specify an array of single values needed for your integration to contact the data provider and authorize itself successfully. Customers will provide these as part of configuring your integration. For checks with reselling enabled, these credentials won't be sent.

You must provide at least one credentials field.

config

array of objects

Yes

Like credentials, the config field contains exactly one field, fields, which specify an array of configurable options for your integration that can be set up on individual provider configurations, and is provided to your integration on every check.

Field details

Details for the objects associated with the /config response.

Table 1. pricing response fields

Field

Type

Required?

Description

supports_reselling

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 false.

maximum_cost

number

No

Deprecated as reselling is no longer supported.



Table 2. credentials response fields

Field

Type

Required?

Description

type

One of "string", "password"

Yes

The type of the credential field. password is functionally identical to string, but is rendered as a password input in the UI.

name

string

Yes

The name of the field which is used when sent to your integration.

label

string

Yes

The name that's displayed for this field in Maxsight.



Table 3. config response fields

Field

Type

Required?

Description

type

One of "string", "number", "float", "integer", "boolean', "set", "MultiSelect"

Yes

The type of the configuration field.

name

string

Yes

The name of the field which is used when sent to your integration.

label

string

Yes

The name that's displayed for this field in Maxsight.

subtext

string

No

A short description that is displayed using a tooltip with the configuration item in Maxsight.

options

array of objects

No

An array of options which may be chosen; used for both display name and value.

Only applicable to (and required for) the MultiSelect and set field types.

default

A valid value allowed by the type specified in type

Yes

The default value for this configuration field. For MultiSelect and set fields, this value may also be null. Otherwise, it must be a valid value for the field's type; for example, a boolean field may only have a default of either true or false.

required

boolean

No

Specify whether this config field is required.

max_value

A valid value allowed by the type specified in type

No

The maximum value allowed for the config field.

This is only applicable to number, float, and integer types.

min_value

A valid value allowed by the type specified in type

No

The minimum value allowed for the config field.

This is only applicable to number, float, and integer types.

step_value

A valid value allowed by the type specified in type

No

The increment value with which users change the value of this field.

This is only applicable to number, float, and integer types.



Table 4. options response fields

Field

Type

Required?

Description

label

string

Yes

The name that's displayed for this option in the options field in Maxsight.

value

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.

Table 5. Metadata endpoint response fields

Field

Type

Required?

Description

protocol_version

number

Yes

An integer representing the version of the version of the Integration API to use. Currently, this is always 1.

provider_name

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

errors

array

Yes

If your integration does not recognize the reference in the request, you can use the errors array to specify errors. This means Maxsight retries the request.

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.

Add a new entity dialog displaying Orbis search results for a company.

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

ONE_TIME_CALLBACK

  • Production endpoint: https://api.eu.maxsight.com/integrations/v1/callbacks

  • Staging endpoint: https://api.stg-eu.maxsight.com/integrations/v1/callbacks

  • Production endpoint: https://api.us.maxsight.com/integrations/v1/callbacks

  • Staging endpoint: N/A

  • Production endpoint: https://api.ae.maxsight.com/integrations/v1/callbacks

  • Staging endpoint: https://api.stg-ae.maxsight.com/integrations/v1/callbacks

MONITORED_CALLBACK

  • Production endpoint: https://api.eu.maxsight.com/integrations/v1/monitored_notify

  • Staging endpoint: https://api.stg-eu.maxsight.com/integrations/v1/monitored_notify

  • Production endpoint: https://api.us.maxsight.com/integrations/v1/monitored_notify

  • Staging endpoint: N/A

  • Production endpoint: https://api.ae.maxsight.com/integrations/v1/monitored_notify

  • Staging endpoint: https://api.stg-ae.maxsight.com/integrations/v1/monitored_notify

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"
}

Additional information