Skip to main content

Customer communication integration guides

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

Customer request integration guide

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

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

The following steps will guide you through the process of adding a customer 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

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

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

Choose the task configuration

First, choose which document types you'll request from customers 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 customer request. Learn more about Passfort'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 Passfort.

To see a preview of the document request flow and test your configuration options, visit this site: https://collection.passfort.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 customers 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 your customers 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 customer email. 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 customer requests and not registration flows, we recommend using the static loader because it's simpler.

If you're using registration flows in addition to customer requests, we recommend using the dynamic loader because Passfort does not send a customer email 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 customers 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 customer. 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 customer. 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 applicants register for your product, you can ask them to complete a series of forms in an order, known as a customer request flow, as part of the registration process.

Passfort can take the data from the forms to set up the applicant's profile and begin running checks immediately - even before the applicant 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 a customer 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 ma_kyc_support@moodys.com.

Choose the form configuration

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

This collection of forms is known as the customer 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 product application should be added to the applicant's profile once the registration is complete.

Customize the form theme

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

To see a preview of the document request flow and test your configuration options, visit this site: https://collection.passfort.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 customers 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 your customers 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 customer email. 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 customer requests and not registration flows, we recommend using the static loader because it's simpler.

If you're using registration flows in addition to customer requests, we recommend using the dynamic loader because Passfort does not send a customer email 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 applicant 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 a customer request

See examples of the correct API calls.

  1. Create a stub profile on Passfort for that applicant using the POST /4.0/profiles endpoint. The role field should be set to “INDIVIDIUAL_CUSTOMER” or “COMPANY_CUSTOMER” based on whether the applicant is an individual or company; other fields will be filled by the customer 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 of the customer request and the apikey of the customer 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 applicant 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 a customer request in future will just require step 3.

Completing a customer request

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

Customer request statuses

A customer 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 customer request at one time.

A customer request can be in one of the following states: SENT, COMPLETED, or EXPIRED. Forms within a customer request can be in progress as sent, canceled, completed, or expired. A customer request’s status will be SENT until all the forms are in one of the three terminal states. The overall status of the customer 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 customer request will be marked as EXPIRED.

We send webhooks that will allow you to distinguish between SENT, COMPLETED, and EXPIRED customer requests. Details of the webhook can be found here.

Calling GET /4.0/forms/profile/profile_id/customer_request will return the most recently created customer request on the profile, 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 customer request is EXPIRED.

Additional information

In this section:

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

The automated processes that can be used to complete or assist in passing tasks.

The due diligence measures that must be taken to onboard a profile successfully. Tasks are displayed on the profile’s product application.