MeasureOne offers a secure, API-based platform to power consumer-permissioned data sharing, providing a safe and transparent way for consumers to share data with third-party applications.

The MeasureOne platform acts as a bridge between data sources containing the consumer's personal data and data recipients. Data sources are online systems that house the data to be shared and that are accessible to the consumer. Example data sources are academic institutions, payroll processors, utility providers government systems and others. Data recipients are any third-party that the consumer wishes to share information with, often in return for a product or service that the data recipient is offering. Example recipients are lenders, marketeers, background check companies, employers, recruiters, and others.

The MeasureOne API allows you as a data recipient to integrate consumer-permissioned data into your workflows. It does so by facilitating consent, access, acquisition, and delivery of your users' permissioned data. In the basic workflow of consumer-permissioned sharing is as follows. First, your users provide their consent to Measure one to share specific personal information with you. They then share their credentials with MeasureOne providing access to data -- called "source data" -- that provides the information that they have consented to share with you. MeasureOne uses these credentials to connect that data source to its platform, access and acquire the source data. MeasureOne then provides access to this source data through a set of service APIs.

There are several benefits to using the MeasureOne API. Our API hides the complexity involved in the consumer-permissioning workflow behind a simple straighforward API so that you can focus on your application and customer experience. We handle user credentials so you don't have to. We handle consents from the user and ensure that you only receive access to the consented information, freeing you from the need to worry about accessing consumer information improperly. We also provide guarantees to your user that we will not share information outside the scope of their consent. This provides you with the opportunity to have your users share information with you that otherwise would not be accessible. Finally, MeasureOne ensures the provenance of the shared data. The data is shared by the user, with their explicit consent, but without any ability to modify or tamper with it.

The current 3.0 version is not backward compatible with version 2.0. If you are a 2.0 user, please see our Migration Guide.

This section gives you some brief use cases for using the API in your workflow. For complete details, please see the full documentation.

Income or Employment Verification

Extracting income information from paystubs, 1099 or other income-related documents provides you with a comprehensive solution to assessing your user's income.

Home and Auto Insurance Policy Verification or Quoting

By facilitating the sharing of home and auto insurance policies, MeasureOne enables customers to verify insurance information during auto and home transactions or provide detailed policy information for comparative quoting purposes.

Academic qualification, history or enrollment status assessment

MeasureOne supports acquisition and processing of academic documents. By connecting the user's academic institution to our platform, MeasureOne uses the shared transcripts and other educational data to provide an assessment or verification of educational data. This includes academic history, degree verification, student enrollment status or other similar data.

Identity and Fraud Detection

By leveraging multiple items of consumer-permissioned data, MeasureOne provides unique opportunities to customers to establish identity and protect against fraud.

Alternative Data Financial Underwriting

MeasureOne's MeritScore is a proprietary predictive analytic that correlates credit performance with academic data. Using consumer-permissioned transcripts, MeasureOne provides a score that correlates the user's academic performance to credit default risk. This both reduces risk for the lender while opening up new credit opportunities for young borrowers.

Protocols & Header Parameters

Unless specified otherwise, the MeasureOne API uses POST requests to communicate and HTTP response codes to indicate status and errors. Unless explicitly specified, all responses come in standard JSON, and all requests must include a Content-Type of application/json with a valid JSON body.

Environments

MeasureOne provides two API environments:

MeasureOne authenticates your API requests using access tokens. If you do not include the access_token when making a request, MeasureOne returns an authentication error. To gain access to the MeasureOne API, reach out to us on sales@measureone.com. Once you’ve completed the signup process, we’ll provide a live client_id & secret for use in our API.

You can access our APIs using Access Tokens Or Public Tokens. The Public Tokens are short lived with limited scope while Access Tokens are long lived.

Access Tokens are long-lived tokens that give you access to the MeasureOne infrastructure for your account.

Access tokens should be used only from your own server side applications.

Public tokens are short-lived tokens with defined scope and policy. The scope indicates the resources and endpoints you can access using these tokens while policy indicates the data you can access using the APIs.

MeasureOne APIs will return a 401 error if the public token is used for scope or policy that is different from the token's scope and policy.

For example, if you create a public token for policy having individual_id idv_293241AAjy2EZt3R and if you try to invoke /individuals/get_by_id for another individual, it will return a 401 error.

The table below defines the currently supported scope.

The current major version of the MeasureOne API is 3.0, and is passed in the API path as a /v3 prefix. The current 3.0 API version is 20210117 and is passed as a request header while calling the API. If no version number is specified in the request header, the API will default to the version that was live when you first signed up for MeasureOne API keys. We periodically release changes to our APIs. While we try to remain backward compatible, changes in our API may result in changes to the data or schema structures exposed in the current version.

MeasureOne has four core resources. These resources help you seamlessly integrate consumer-permissioned-data workflow into your applications.

Individual

The Individual is your end user/consumer whom you are requesting to share data or information with you as part of your application. In a typical implementation, ths Individual is directed to MeasureOne through an invitation initiated from your application or the MeasureOne Dashboard. MeasureOne then interacts with the Individual to complete the consumers-permissioned data sharing workflow and shares the accessed Individual data with you, either directly with your application or through the MeasureOne Dashboard.

Data Requests

A consumer-permissioned data workflow is initiated and defined by the Data Request resource. A Data Request specifies or bind together the various elements of a consumer-permissioned data workflow, in particular: the Individual, the set of actions - writing or acquiring data - to be performed, optional reports to be generated, the Link experience, optional schedule to auto-refresh data, optional Individual communication and messaging.
MeasureOne supports pre-configured types of data requests catering to different use cases, as well as CUSTOM data requests that allow you to request custom data. All services accept datarequest_id as a reference.

The following table specifies the supported Data Request types. Based on the Data Request type, MeasureOne tailors the consumer-permissioned workflow to satisfy the indicated request for data.

Items

Individuals permission access to documents online for your stated business purpose. The permissioned documents that MeasureOne accesses and acquires are called Items. Items can be in any format -- HTML, PDF, XML, JSON, etc. Once the Item is acquired, it is parsed stored. To enforce the permissions on the Item data, access to the information in the Items is available solely through Service APIs. This separation of the Item data from the Service APIs limits the scope of information to just what the Individual has authorized to share, independent of the underlying Item data used to generate it. This ensures that you receive only the permissioned data and that the Individual's privacy is protected.

Datasources

The online location of Items is called a Data Source. Data Sources are typically online accounts that are owned by the Individual. The Individual gives explicit consent to MeasureOne to access their Data Source account and retrieve the Items necessary to fulfill your Data Request.

The diagram below depicts a simple integration flow with MeasureOne.

This section gives you the list of all endpoints exposed by MeasureOne to integrate into your application workflow. For complete details, please see the full documentation. Unless specified otherwise, all the endpoints require access_token in the header for authorization.

2xx Success

A 2xx status code indicates the request was received and processed successfully.

4xx Client Errors

A 4xx status code indicates that the request failed due to a client error. The response body generally includes more details about the failure.

5xx Server Errors

A 5xx status codes is returned if something goes wrong on MeasureOne's end

Many of MeasureOne APIs are asynchronous in nature. Client applications integrating MeasureOne API are required to expose endpoints for MeasureOne to send the Webhook Notifications. The diagram below depicts how the asynchronous communication will work. APIs having Asynchronous communication may also send a synchronous response if the response is readily available.

The table below depicts the APIs that require clients to provision endpoints for asynchronous communication.

MeasureOne Link is a front-end component that provides you all the capabilities necessary to initiate the the consumer-permissioning workflow for your users. It enables your users to permit your application to access their data in a consumer-permissioned manner.

Link handles the consent, the data source identification, the credential collection, and the integration with the MeasureOne platform to access and acquire the consumer-permissioned data. It handles a variety of authentication mechanisms including multi-factor authentication and offers various configuration options to tailor the UI to your application.

As an alternative to the embedded widget, MeasureOne supports hosted solutions of Link, providing no-code options for your integrations. Please login to the Dashboard for more details.

Integration of Link is done using a small snippet of javascript that can be displayed in any part of your application.

Widget integration requires the m1-link tag and a set of configuration options as shown in the sample configuration JSON.

Link raises events for various user actions that your application can subscribe to. In addition to these events, the MeasureOne platform communicates with the client application via webhooks.

The LINK javascript is available at the links below

The source code sample below shows how to integrate MeasureOne Link widget into your front-end using plain vanilla javascript

Integrating MeasureOne Link 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> YOUR TITLE HERE </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: "dr_1faOM8Q4efEWIjzdE2SBM2kLq4O",
          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>

The configuration attribute of the LINK Widget is a JSON Object as described below

Events are triggered based on user activity in the widget. These events provide information to you to enhance the experience within your application. The following table provides the details of supported Action Events. Each Action Event may have additional data that provides additional context for the event. The following sections describe various events generated by the MeasureOne Link widget

The Individual is a core resource that represents your user. At the start of the workflow an Individual representing the user must be created. Retrieved Items are associated with the Individual. Almost all Service APIs take the Individual ID as a reference.