Skip to main content

External communication integration guides

Use the information in this section to set up communications with external parties.

External information request integration guide

External information requests are used to ask external parties to complete one or more forms. These forms can be used to gather information or collect a document to run a check. 

External information requests are added to tasks. When a task is configured with an external information request, a button is displayed that enables users to send an email to an external party with a link to the request forms.

The following steps will guide you through the process of adding an external information request to one or more tasks on your account.

It will show you how to:

  • Choose the task configuration

  • Customize the form theme

  • Configure the URL

  • Customize the email theme

Once you've provided us with the requested information, we'll implement the changes and complete the configuration.

If you have any questions, you can contact our Client Service team at clientservices@moodys.com.

Choose the task configuration

First, choose which document types you'll request from external parties and which tasks they'll be associated with.

We'll need the following information:

  1. The names of the tasks that you would like to configure with the external information request. Learn more about Maxsight's tasks.

  2. For each task, provide the document types that can be accepted for the request, such as driving licenses, passports, and so on.

  3. For each document type, indicate which of the following elements make up the type:

    • Document front

    • Document back

    • Selfie

Customize the form theme

Next, choose a style for the form and send it to Maxsight.

To see a preview of the document request flow and test your configuration options, visit this site: https://collection.eu.maxsight.com/theme?token=0577D35F-9452-4E79-8676-EB56BAF90603&apikey=sample&request_id=sample

Learn more about how to customize the form theme.

Configure the form URL

Let us know which URL you want to use for the form, such as www.yourdomain.com/onboarding.

The request email that external parties receive will contain a link to this URL, and when they follow the link, they'll see your chosen URL in the address bar.

We recommend choosing a URL that will be familiar to the external parties in order to help maintain their trust.

On the page for that URL, serve one of these HTML loaders which are used to embed the form into an iframe:

  • Dynamic loader: When the form is initialized, your webpage passes the request ID and API key as variables to the loader. Get the dynamic_loader.html.

  • Static loader: This loader reads the request ID and API key from the link sent in the email to the external party. After it loads the forms on the web page, the static loader removes the request ID and API key from the address bar and history, keeping this information secure. Get the static_loader.html.

If you're only using external information requests and not registration flows, we recommend using the static loader because it's simpler.

If you're using registration flows in addition to external information requests, we recommend using the dynamic loader because Maxsight does not send an email to the external party during the registration flow process.

Ultimately, the choice between the static loader and the dynamic loader is up to you. Both options are equally secure and effective.

Note

The loader only needs to be embedded on one page.

Customize the email theme

Finally, choose the theme for the request email that external parties receive. It contains the link to your form.

We'll need the following information:

  1. Subject line

  2. Sender name. For example, the name of your company.

  3. Sender email address. For example, support@yourdomain.com.

  4. Email template. You can use the out-of-the-box template or a custom HTML template described in the next section.

  5. Name of your DNS provider

After you provide these details, we'll implement the changes and send you CNAME records that you can add to your DNS.

Out-of-the-box email template

If you have limited design resources, you can use our template as a starting point.

Send us the following information, and we'll set it up for you:

  • Your company logo

  • Editable text: Before sending the email request, your users can change this to add a bespoke message for the external party. Note that this can only be a single line or paragraph of text; in other words, no bullet points, paragraph breaks, or other styling.

  • Color and format for the button: This is the button that links to the form.

  • Footer text: You might want to include information like your address and any legal text or copyright information.

Custom HTML email template

You can also send us a fully customized HTML template.

The required style elements are:

  • Your company logo

  • Editable text: Before sending the email request, your users can change this to add a bespoke message for the external party. Note that this can only be a single line or paragraph of text; in other words, no bullet points, paragraph breaks, or other styling.

  • Button: This is the button that links to the form.

  • Footer: You might want to include information like your address and any legal text or copyright information.

Your template can also contain these elements:

  • Title

  • Fixed text: This is displayed before and/or after the editable text; you might choose to add a greeting such as Dear customer, a closing such as Kind regards, a signature, or contact details.

HTML loader details

Static loader

<!DOCTYPE html>
<html>
    <head>
        <title>Customer</title>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <base href="/" />
    </head>
    <body>
        <script src="https://collection.passfort.com/embed.js"></script>
        <script>            window.onload = function() {
                PassFortCollect.initFromUrl()
            }
        </script>
        <div id="collection-wrapper"></div>
    </body>
</html>

Dynamic loader

<!DOCTYPE html>
<html>
  <head>      
      <title>Customer</title>      
      <meta charset="utf-8" />      
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <base href="/" />
  </head>
  <body>
      <script src="https://collection.passfort.com/embed.js"></script>
      <script>
          window.onload = function() {
              // The init function has this signature:
              // PassFortCollect.init({
              //   request_id,
              //   apikey,              // })
              PassFortCollect.init({
                  request_id: "<request_id>",
                  apikey: "<apikey>",
              })
          }
      </script>
      <div id="collection-wrapper"></div>
  </body>
</html>

Registration integration guide

When a third party starts a particular assessment, you can ask them to complete a series of forms in an order, known as an external information request flow, as part of the registration process.

Maxsight can take the data from the forms to set up the external party's entity and begin running checks immediately - even before the external party has completed all forms. 

This makes the onboarding process much faster and easier, plus it enables you to ask additional form questions based on the data returned from the checks. For example, if a Company data check returns information about company shareholders, you can configure the registration flow to ask additional questions about shareholders.

The following steps guide you through the process of setting up an external information request flow. The forms for the request flow are displayed at a URL that you control. Once you have it set up, you can incorporate it into your registration process.

If you have any questions, you can contact our Client Service team at clientservices@moodys.com.

Choose the form configuration

First, choose which forms the external party will need to complete during registration.

This collection of forms is known as the external information request.

Provide us with:

  • The forms you would like to add to the registration flow. Each form should have questions, which can optionally be grouped into sections.

  • Which assessment should be added to the entity once the registration is complete.

Customize the form theme

Next, choose a style for the form and send it to Maxsight.

To see a preview of the document request flow and test your configuration options, visit this site: https://collection.eu.maxsight.com/theme?token=0577D35F-9452-4E79-8676-EB56BAF90603&amp;apikey=sample&amp;request_id=sample

Learn more about how to customize the form theme.

Configure the form URL

Let us know which URL you want to use for the form, such as www.yourdomain.com/onboarding.

The request email that external parties receive will contain a link to this URL, and when they follow the link, they'll see your chosen URL in the address bar.

We recommend choosing a URL that will be familiar to the external parties in order to help maintain their trust.

On the page for that URL, serve one of these HTML loaders which are used to embed the form into an iframe:

  • Dynamic loader: When the form is initialized, your webpage passes the request ID and API key as variables to the loader. Get the dynamic_loader.html.

  • Static loader: This loader reads the request ID and API key from the link sent in the email to the external party. After it loads the forms on the web page, the static loader removes the request ID and API key from the address bar and history, keeping this information secure. Get the static_loader.html.

If you're only using external information requests and not registration flows, we recommend using the static loader because it's simpler.

If you're using registration flows in addition to external information requests, we recommend using the dynamic loader because Maxsight does not send an email to the external party during the registration flow process.

Ultimately, the choice between the static loader and the dynamic loader is up to you. Both options are equally secure and effective.

Note

The loader only needs to be embedded on one page.

Redirect the URL

Let us know what URL the external party should go to once they complete the registration flow.

Note that after the flow is completed, automation may still be running or manual work may be required.

Technical notes

Creating and loading an external information request

See examples of the correct API calls.

  1. Create a stub entity on Maxsight using the POST /4.0/profiles endpoint. The role field should be set to “INDIVIDIUAL_CUSTOMER” or “COMPANY_CUSTOMER” based on whether the entity is an individual or company; other fields will be filled by the external party as part of the registration flow. For example, for a new company, you would use the following request:

    { "role": "COMPANY_CUSTOMER",

    "collected_data": {"entity_type": "COMPANY"}

    Capture the id field in the result, which we will refer to as profile_id.

  2. Make a call to the POST /4.0/forms/profile/:profile_id/customer_request endpoint with your master API key in the headers of the request and with the profile_id from the response in the previous step.

    This endpoint will return the id and the apikey of the external information request associated with it. Store those values in your database. The request should be of the form:

    {
"type": "FLOW',
"flow_template": {"alias" : "template_alias"},
"theme": {"alias" : "theme_alias"}
}

    The values for flow_template and theme_id will be provided when the Flow config and Form theme are completed as discussed in the following integration guide.

  3. Send the signed-in external party to the page where the Javascript snippet is and call init() with the apikey and request_id as parameters once the page has loaded.

Reloading an external information request in future will just require step 3.

Completing an external information request

Once the external party completes the external information request, we will redirect them to a page of your choice. We can also send a customer_request_changed webhook to your system. See details of the webhook.

External information request statuses

An external information request contains a number of form requests. These forms may then be displayed on different tasks, or run a check. It is currently only possible to have one active external information request at one time.

An external information request can be in one of the following states: SENT, COMPLETED, or EXPIRED. Forms within a request can be in progress as sent, canceled, completed, or expired. An external information request’s status will be SENT until all the forms are in one of the three terminal states. The overall status of the external information request will correspond to the last form request to enter a terminal state. For example, if some forms are completed successfully, but then the remaining forms expire, the overall external information request will be marked as EXPIRED.

We send webhooks that will allow you to distinguish between SENT, COMPLETED, and EXPIRED external information requests. Learn more about webhooks.

Calling GET /4.0/forms/profile/profile_id/customer_request will return the most recently created external information request on the entity, since you can only have one active at a time.  The response will contain an is_completed property. This will be TRUE if the request is completed or if it is expired. It will be FALSE if there are forms that can still be edited. The API does not currently surface the detailed status, in other words, if the external information request is EXPIRED.

Additional information

In this section:

A form consists of one or more questions and can be used to gather information about an entity or to collect a document to run a check. Forms can be internal or external as part of an external request or registration flow.