Skip to content

MeasureOne Integration Guide

MeasureOne API allows you to interact with key resources such as Individual, DataRequest, Item, and Services. The consumer-permissioned data workflow is driven by the DataRequest resource, which ties together the essential elements of the workflow:

  • The Individual
  • The type of data being requested
  • The associated data services
  • The MeasureOne Link experience
  • Optional communication and messaging with the Individual

Below is an overview of the integration flow and details on each step.

TL;DR: Just the Basics

To just get your bearings, here is a brief description of how a typical API implementation is performed.

First, you create an "Individual". This is your user. With that individual, you create a "Data Request". The Data Request configures the data you are looking to receive and how you will receive it. Once the Data Request is created, you initiate our M1-Link widget in your application, configured with this data request. Your user is then directed by your application towards this widget instance. Our widget takes your user through a flow that results in them sharing the requested data with us. Once we have the data, we parse, extract, digitize and deliver it to you to your configured webhook endpoint. In addition to getting access to the raw data, you can request us to generate one or more of a set of reports -- we call then "Services" -- that we maintain. These could be anything from a simple summary of the data, to insights based on heuristics and other proprietary capabilities.

The entire process is asynchronous and is designed to be as seamless and pain-free for you and your users.

Ok, now for a bit more of the details....

The Details

Integrating with MeasureOne involves both server-side and client-side components. Here is the step-by-step process:

1. Create an Individual

Use the /v3/individuals/new API endpoint to create a new Individual. This step initializes the consumer's identity within MeasureOne.

Required Fields
  • first_name
  • last_name
  • email
Optional Field
  • external_id: Your unique identifier for mapping MeasureOne Individuals to your records.

Example Request

let individual = {
  first_name: "John",
  last_name: "Doe",
  email: "john.doe@example.com",
  external_id: "12345",
};

const headers = {
  Authorization: `Bearer <<YOUR_ACCESS_TOKEN>>`,
  "Content-Type": "application/json",
};

axios
  .post(`<<M1_API_URL>>/v3/individuals/new`, individual, { headers })
  .then((response) => {
    // Handle success
    console.log(response.data);
  })
  .catch((error) => {
    // Handle error
    console.error(error);
  });

2. Create a Data Request

Once an Individual is created, call the /v3/datarequests/new API endpoint to create a DataRequest. This specifies the type of data being requested and binds it to the Individual.

To check the types of data requests you can create, refer to our Data Requests API Documentation.

In the example below, we are creating an INCOME_EMPLOYMENT_DETAILS data request:

Example Request
let dataRequest = {
  individual_id: "<<INDIVIDUAL_ID>>",
  type: "INCOME_EMPLOYMENT_DETAILS",
  // Additional optional parameters
};

const headers = {
  Authorization: `Bearer <<YOUR_ACCESS_TOKEN>>`,
  "Content-Type": "application/json",
};

axios
  .post(`<<M1_API_URL>>/v3/datarequests/new`, dataRequest, { headers })
  .then((response) => {
    // Handle success
    console.log(response.data);
  })
  .catch((error) => {
    // Handle error
    console.error(error);
  });

3. Direct Consumer to the Widget

After creating the data request, redirect the consumer to the MeasureOne Link Widget, where they can complete their part of the workflow. The example below illustrates a sample integration flow to initiate the widget.

<html lang="en">
  <head>
      <meta charset="UTF-8">
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <meta http-equiv="X-UA-Compatible" content="ie=edge">
      <title> Test Widget flow</title>
      <script src="https://api-stg.measureone.com/v3/js/m1-link-2021042000.js"></script> 
  </head>
  <body>
    <h1>YOUR TITLE HERE</h1>
    <div>
      <m1-link></m1-link>
    
    <script>
      var config = {
          access_key: "<<YOUR_ACCESS_TOKEN>>",
          host_name: "api-stg.measureone.com",
          datarequest_id: "<<YOUR_DATAREQUEST_ID>",
          branding: {
              styles: {
                  primary_dark: "#186793",
                  primary_light: "#2e9ccb",
                  secondary_color: "#ffffff",
                  min_height: "700px"
              }
          },
          options: {
              "display_profile": false
          }
      }
              
      // Take reference to widget
      const m1_widget = document.querySelector("m1-link");
      
      // Add configuration
      m1_widget.setAttribute("config", JSON.stringify(config));

      // Add event listeners
      m1_widget.addEventListener('datasourceConnected',(event)=>{
          // Perform operation on datasourceConnected event. 
          console.log(event);
          //hide or destroy the widget once connected
      });
    </script>
  </body>
</html>

4. Listen for Events on the Front-end

Integrate event listeners in your front-end application to detect when the widget process completes. Based on these events, you can hide or remove the widget from the UI. Read more about MeasureOne Link Events

Example
m1_widget.addEventListener("datasource.connected", (event) => {
  // Hide the widget
  // update your backend with the details of the connection
  
});

5. Listen for Webhooks

MeasureOne sends webhooks from its backend to notify you about events such as data availability or workflow completion. Configure your server to handle these webhook events.

Example Webhook Listener
app.post("/webhooks/measureone", (req, res) => {
  const event = req.body;

  // Handle the event
  switch (event.type) {
    case "datasource.connected":
      console.log(
        `Datasource connected for request ID: ${event.data.datarequest_id}`
      );
      break;
    case "datarequest.items_available":
      console.log(
        `Items available for request ID: ${event.data.datarequest_id}`
      );
      break;
    case "datarequest.no_items":
      console.log(
        `No Items found for request ID: ${event.data.datarequest_id}`
      );
      break;
    case "datarequest.report_available":
      console.log(
        `Data is available for request ID: ${event.data.datarequest_id}`
      );
      break;
     case "session.rejected":
      console.log(
        `Session rejected request ID: ${event.data.datarequest_id}`
      );
      break;
    // Handle other event types
  }

  res.status(200).send("Webhook received");
});

5. Call Service APIs

Service APIs allow access to an Individual's Items and provide relevant information to your application. These APIs are categorized by domain. For detailed guidance on how to interact with the service, refer to our Service API Documentation.

Summary

The MeasureOne workflow begins by creating an Individual, followed by creating a DataRequest. Consumers interact with the MeasureOne widget to complete the process, while your application listens for events and webhooks to handle data and status updates.

For more detailed API documentation and parameter options, refer to the official MeasureOne API Documentation.

Previous page