Skip to main content

Set integration credentials and configuration

You are able to specify what credentials and configuration options you want to receive from users of your integration through Maxsight.

These credentials and configurations will be sent in each request from Maxsight to your integration, so they can be used as required.

Tip

The credentials and configurations are specified in your Configuration endpoint.

When adding your integration in Maxsight, the user is able to add their credentials and any configuration options your integration has defined as required.

In Maxsight, this can look like the following example. You can see that this integration has specified one credentials field, labeled API token, and one configuration checkbox labeled Enable Enhanced Verification.

To add credentials and configuration to your integration through your Configuration endpoint:

  1. In the fields array of the credentials and config fields, specify the type, name, which is how it is visible to your integration in the API request, and the label, which is what it's called in Maxsight.

    {
  "pricing": {
    "supports_reselling": false,
    "maximum_cost": 0
  },
  "supported_countries": [
    "GBR"
  ],
  "credentials": {
    "fields": [
      {
        "type": "password",
        "name": "api_token",
        "label": "API Token"
      }
    ]
  },
  "config": {
    "fields": [
      {
        "type": "boolean",
        "name": "enable_enhanced",
        "label": "Enable Enhanced Verification",
        "default": false,
        "subtext": "Confirm if enhanced verification should be used."
      }
    ]
  },
  "check_type": "INDIVIDUAL_CUSTOM",
  "check_template": {
    "type": "ONE_TIME_SYNCHRONOUS",
    "timeout": 60
  }
}

  2. You must specify at least one credentials field.

    For credentials, the type can only be set to string or password. This determines how the input looks to Maxsight users as they add this information.

    For example, setting type to string looks like the following:

    Partner_Experience_setting_credentials_example_string.png

    Setting type to password looks like the following:

    Partner_Experience_setting_credentials_example_password.png

  3. Configuration works similarly to credentials, but offers more options. You don't need to specify any configuration options, but this is encouraged to make your integration configurable to as many customers as possible.

    For config, select the type as string, password, number, float, integer, boolean, set, MultiSelect, or list.

    For example, setting type to number looks like the following:

    Partner_Experience_setting_config_example_number.png

    Note that float and integer display in the same way, but with the applicable type. number allows input of both floats and integers.

    Setting type to boolean looks like the following:

    Partner_Experience_setting_config_example_boolean.png

    Setting type to MultiSelect looks like the following:

    Partner_Experience_setting_config_example_multiselect.png

    Note that when using MultiSelect, you must specify the options array with all the valid options.

    Setting type to set looks like the following:

    Partner_Experience_setting_config_example_set.png

    Note that when using set, you must specify the items object that contains the type and options array with all the valid options.

    "type": "set",
"items": {
  "type": "string",
  "name": "Categories"
  "options": [
    {
      "value": "jurisdiction",
      "label": "JURISDICTION"
    },
    {
      "value": "allegation",
      "label": "ALLEGATION"
    },
    {
      "value": "residence",
      "label": "RESIDENCE"
    },
    {
      "value": "citizenship",
      "label": "CITIZENSHIP"
    },
    {
      "value": "risk",
      "label": "RISK"
    }
  ]
},

    Setting type to list looks like the following:

    Partner_Experience_setting_config_example_list.png

    Note that when using list, you must specify the items object that contains the type and options array with all the valid options. If the list contains multiple types, you must use the composite type.

    "fields": [
      {
        "type": "boolean",
        "name": "use_custom_rules",
        "label": "Configure custom matching rules",
        "subtext": "This option is not compatible with some of the settings on this page and they will be automatically disabled once you select it."
      },
      {
        "type": "list",
        "name": "custom_matching_rules",
        "items": {
          "type": "composite",
          "label": "Custom rule",
          "fields": [
            {
              "name": "name",
              "type": "string",
              "label": "Name"
            },
            {
              "name": "result",
              "type": "string",
              "options": [
                {
                  "value": "Fail",
                  "label": "Fail"
                },
                {
                  "value": "1+1",
                  "label": "1+1"
                },
                {
                  "value": "2+2",
                  "label": "2+2"
                }
              ],
              "label": "Result"
            },
            {
              "name": "database_types",
              "type": "set",
              "items": {
                "type": "string",
                "options": [
                  {
                    "value": "CREDIT",
                    "label": "Credit"
                  },
                  {
                    "value": "CIVIL",
                    "label": "Civil"
                  },
                  {
                    "value": "MORTALITY",
                    "label": "Mortality"
                  },
                  {
                    "value": "ALERT",
                    "label": "Alert"
                  }
                ]
              },
              "label": "Database types"
            },
            {
              "name": "requires",
              "type": "list",
              "items": {
                "type": "set",
                "items": {
                  "type": "string",
                  "options": [
                    {
                      "value": "FORENAME",
                      "label": "Forename"
                    },
                    {
                      "value": "SURNAME",
                      "label": "Surname"
                    },
                    {
                      "value": "ADDRESS",
                      "label": "Address"
                    },
                    {
                      "value": "DOB",
                      "label": "DOB"
                    },
                    {
                      "value": "IDENTITY_NUMBER",
                      "label": "Identity number"
                    },
                    {
                      "value": "IDENTITY_NUMBER_SUFFIX",
                      "label": "Identity number suffix"
                    }
                  ]
                }
              },
              "label": "Requires"
            },
            {
              "name": "distinct_sources",
              "type": "boolean",
              "default": true,
              "label": "Distinct sources"
            }
          ]
        },
        "label": "Custom matching rules",
        "subtext": "Each rule is considered in turn, in the order in which they appear below. The first rule whose requirements are met will become the active rule.",
        "hide_when": {
          "not": "use_custom_rules"
        }

Example request to your integration with credentials and configuration

The credentials and configuration are sent to you within fields in the request labeled provider_credentials and provider_config respectively.

The following is an example of how this might look in a request to your integration:

{
  "id": "30823f29-1cb5-4afe-a278-1f293548e1ce",
  "demo_result": null,
  "commercial_relationship": "DIRECT",
  "check_input": {
    "entity_type": "INDIVIDUAL",
    "customer_ref": "john_smith_reference",
    "contact_details": {
      "email": "john_smith@example_not_real.com"
    }
  },
  "provider_config":  {
    "use_email": false
  },
  "provider_credentials": {
    "api_token": "123456test"
  }
}

Note that this would not be a valid request, but is here to show you how the provider_config and provider_credentials fields would be displayed in the request.

Additional information

In this section: