MeasureOne API (3.0)

Download OpenAPI specification:Download

Introduction

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.

Sample Use cases

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.

API Host and Protocols

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.

Header Parameters Values
Authorization bearer
Content-Type application/json
version

Environments

MeasureOne provides two API environments:

Environment URL
Staging https://api-stg.measureone.com/v3/
Production https://api.measureone.com/v3/

API Keys and Access

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

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

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.

API Endpoint WIDGET GLOBAL
/individuals/new YES YES
/individuals/get_by_id YES YES
/individuals/get_items YES YES
/datarequests/new YES YES
/datarequests/update YES YES
/datarequests/get YES YES
/datarequests/get_by_id YES YES
/datarequests/generate_invitation_link YES YES
/datarequests/notify_user YES YES
/datarequests/get_invitation_link YES YES
/datarequests/expire_invitation_link YES YES
/datasources/get YES YES
/items/new YES YES
/items/upload YES YES
/items/get_by_id YES YES
/items/get_files YES YES
/items/get_pdf YES YES
/services/get_academic_summary NO YES
/services/get_enrollment_status NO YES
/services/gradscore NO YES
/services/meritscore NO YES
/services/get_digest_by_id NO YES
/services/get_employment_summary NO YES
/services/get_income_summary NO YES
/services/get_income_employment_details NO YES
/services/get_insurance_details NO YES
/services/get_realized_gains NO YES

Generate Access Token

This API returns the access token required for you to access the MeasureOne APIs.

The Authorization header should contain the word Basic word followed by a space and a base64-encoded string username:password. For example, to authorize as demo / p@55w0rd you should send

 Authorization: Basic ZGVtbzpwQDU1dzByZA==

This API does not require any request body

SecurityBasic
Request
header Parameters
Authorization
string <Basic <client_id>:<secret>>

Provide the Base64 representation of your client_id:secret e.g. "Basic <<BASE64>>".

Content-type
string <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

Request Body schema: application/json
object (EmptyBody)
Responses
200

Successful Response

400

Bad Request

401

Authentication with the API Failed

403

Forbidden

405

Method Not Allowed

500

Internal Server Error

post/v3/auth/generate_access_token
Request samples
application/json
{ }
Response samples
application/json

Response Access token

{
  • "access_token": "6fd5122a-9a91-4bd6-1219-d6e71fd123b0",
  • "token_type": "bearer",
  • "expires_in": 2128865176,
  • "expires_at": 3637805578000
}

Invalidate Access Token

This API invalidates the provided Access Token.

The Authorization header should contain the word Basic word followed by a space and a base64-encoded string client_id:secret. For example, to authorize as demo / p@55w0rd you should send

 Authorization: Basic ZGVtbzpwQDU1dzByZA==

This API does not require any request body

SecurityBasic
Request
header Parameters
Authorization
string <Basic <client_id>:<secret>>

Provide the Base64 representation of your client_id:secret e.g. "Basic <<BASE64>>".

Content-type
string <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

Request Body schema: application/json
access_token
required
string

Access token generated for you to access MeasureOne API

Responses
200

Successful Response

400

Bad Request

401

Authentication with the API Failed

403

Forbidden

405

Method Not Allowed

500

Internal Server Error

post/v3/auth/invalidate
Request samples
application/json
{
  • "access_token": "6fd5122a-9a91-4bd6-1219-d6e71fd123b0"
}
Response samples
application/json

Example payload Bad Requests

{
  • "timestamp": 1585747802495,
  • "error_code": "BAD_REQUEST",
  • "http_code": 400,
  • "error_message": "Invalid JSON"
}

Generate Public Token

This API returns the Public Token which are short lived tokens required for you to access MeasureOne APIs.

The Authorization header should contain the word Basic word followed by a space and a base64-encoded string username:password. For example, to authorize as demo / p@55w0rd you should send

Public Tokens

 Authorization: Basic ZGVtbzpwQDU1dzByZA==
SecurityBasic
Request
header Parameters
Authorization
string <Basic <client_id>:<secret>>

Provide the Base64 representation of your client_id:secret e.g. "Basic <<BASE64>>".

Content-type
string <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

Request Body schema: application/json
required
validity
number
Default: 900

Public token validity in seconds

scopes
Array of strings

List of scopes for the generated public token. Each scope defines the set of API endpoints that can be accessed using the token. See the table above for details

Compatibility note: An unspecified scope will default to WIDGET

Items Enum: "WIDGET" "GLOBAL"
object

A set of attributes for specifying data access rules associated with this token.

Responses
200

Successful Response

400

Bad Request

401

Authentication with the API Failed

403

Forbidden

405

Method Not Allowed

500

Internal Server Error

post/v3/auth/generate_public_token
Request samples
application/json

Example payload for generating a public token

{
  • "validity": 25600,
  • "scopes": [
    ],
  • "policy": {
    }
}
Response samples
application/json

Response Access token

{
  • "access_token": "6fd5122a-9a91-4bd6-1219-d6e71fd123b0",
  • "token_type": "bearer",
  • "expires_in": 25600,
  • "expires_at": 1681191048000
}

Versioning

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.

Core Resources

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 type of data requested, the reports to be generated, the Link experience, optional Individual communication and messaging.

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.

Data Request Type Description
ACADEMIC_SUMMARY Request the education summary of the Individual
ENROLLMENT_STATUS Request the enrollment status of the Individual
EMPLOYMENT_SUMMARY Request the employment summary of the Individual
INCOME_SUMMARY Request the income summary for the Individual
INCOME_EMPLOYMENT_DETAILS Request the VOIE details of the Individual
HOME_INSURANCE Request the Home Insurance policy of the Individual
AUTO_INSURANCE Request the Auto Insurance policy of the Individual
HOME_INSURANCE_DETAILS Request the Home insurance details of the individuals
AUTO_INSURANCE_DETAILS Request the Auto insurance details of the individuals
REALIZED_GAINS Request 1099-B information from the Individual's brokerage account

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.

How it works

The diagram below depicts a simple integration flow with MeasureOne.

Simple_Integration_Flow_Diagram

Endpoints

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.

Resource Endpoint Description
Authentication /auth/generate_access_token Generates an access token
Authentication /auth/invalidate Invalidates an access token
Authentication /auth/generate_public_token Generates a public token
Individuals /individuals/new Create a new individual
Individuals /individuals/get_by_id Get details of an Individual
Individuals /individuals/get_items Get list of items created for an Individual
Data Requests /datarequests/new Create a new Data Request
Data Requests /datarequests/update Update Data Request
Data Requests /datarequests/get Get or search Data Requests
Data Requests /datarequests/get_by_id Get details of a Data Request
Data Requests /datarequests/generate_invitation_link Generate an invitation link for Data Request
Data Requests /datarequests/notify_user Send invitation to the user to complete the Data Request
Data Requests /datarequests/get_invitation_link Get details of an invitation link generated for the Data Request
Data Requests /datarequests/expire_invitation_link Expire the invitation link for Data Request
Data Sources /datasources/get Get or search Data Sources
Items /items/new Create a new item
Items /items/upload Upload item document
Items /items/get_by_id Upload item document
Items /items/get_files Download the items uploaded via /items/upload API
Items /items/get_pdf Download the items as PDF document
Services /services/get_academic_summary Get the academic summary for an Individual
Services /services/get_enrollment_status Get the enrollment status for an Individual
Services /services/gradscore Get the Gradscore for a transcript
Services /services/meritscore Get the MeritScore for a transcript
Services /services/get_digest_by_id Get the Digest for a transcript
Services /services/get_employment_summary Get the employment summary for an Individual
Services /services/get_income_summary Get the income summary for an Individual
Services /services/get_income_employment_details Get the income employment details (VOIE) for an Individual
Services /services/get_insurance_details Get the insurance details for an Individual
Services /services/get_realized_gains Get the realized gains for a brokerage account

Status Codes

2xx Success

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

Status code Description
200 OK - The request is successful
201 ACCEPTED - The request is successful and has been accepted for further processing. You will receive a notification once the request has completed.

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.

Status code Description
400 Bad Request - The request failed. This will usually occur when validations fail. E.g Missing required fields or invalid JSON

5xx Server Errors

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

Status code Description
500 Internal Server Error - Something has gone wrong on MeasureOne's end while attempting to process the request. Our engineering team has been notified of the issue.

Asynchronous Communication

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.

AsynchronousProcessing

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

Resource Endpoint Asynchronous
Authentication /auth/generate_access_token No
Authentication /auth/invalidate No
Authentication /auth/generate_public_token No
Individuals /individuals/new No
Individuals /individuals/get_by_id No
Individuals /individuals/get_items No
Data Requests /datarequests/new No
Data Requests /datarequests/update No
Data Requests /datarequests/get No
Data Requests /datarequests/get_by_id No
Data Requests /datarequests/generate_invitation_link No
Data Requests /datarequests/notify_user No
Data Requests /datarequests/get_invitation_link No
Data Requests /datarequests/expire_invitation_link No
Data Sources /datasources/get No
Items /items/new No
Items /items/upload No
Items /items/get_by_id Yes
Items /items/get_files No
Items /items/get_pdf No
Services /services/get_academic_summary Yes
Services /services/get_enrollment_status Yes
Services /services/gradscore Yes
Services /services/meritscore Yes
Services /services/get_digest_by_id Yes
Services /services/get_employment_summary Yes
Services /services/get_income_summary Yes
Services /services/get_income_employment_details Yes
Services /services/get_insurance_details Yes
Services /services/get_realized_gains Yes

Introduction

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.

Link

Integration

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

Environment Link
Staging https://api-stg.measureone.com/v3/js/m1-link-2021042000.js
Production To enable the LINK widget in production, reach out to us at support@measureone.com

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

  <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>

Configuration

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

One of:
access_key
required
string

Your API Key

host_name
required
string

Host Name for the environment (staging - api-stg.measureone.com, production - api.measureone.com )

datarequest_id
required
string

Unique ID of the Data Request identified by MeasureOne

object

Your branding that can be applied on the widget

object

Options for the MeasureOne Link module.

{
  • "access_key": "string",
  • "host_name": "string",
  • "datarequest_id": "string",
  • "branding": {
    },
  • "options": {
    }
}

Events

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

individualCreated

Triggered when the Individual is created by MeasureOne Link. This event is deprecated. You must create an Individual before bringing up the Link experience

name
string

Name of the event

object

Additional data for the event

{
  • "name": "individualCreated",
  • "data": {
    }
}

individualUpdated

Triggered when the Individual is updated by MeasureOne Link.

name
string

Name of the event

object

Additional data for the event

{
  • "name": "individualUpdated",
  • "data": {
    }
}

consentStatusChanged

Triggered when the Individual accepts the MeasureOne Consumer Privacy Policy and agrees to give the Consent to MeasureOne

name
string

Name of the event

object

Additional data for the event

{
  • "name": "consentStatusChanged",
  • "data": {
    }
}

currentProgress

Triggered when the screen changes. Returns the value in percentage. If the screen is error, the value of the progress will be -1. The attributes in the data object of this event will vary depending on the screen transition

name
string

Name of the event

object

Additional data for the event.

{
  • "name": "currentProgress",
  • "data": {
    }
}

datasourceConnected

Triggered when the User submits the credentials successfully on the Widget. In case of MFA, this event will be triggered after the MFA is submitted successfully

name
string

Name of the event

object

Additional data for the event. You can use the data from this even to call the service APIs of MeasureOne

{
  • "name": "datasourceConnected",
  • "data": {
    }
}

itemsCreated

Triggered when one or more items are manually uploaded by the Individual

name
string

Name of the event

object

Additional data for the event. You can use the data from this even to call the service APIs of MeasureOne

{
  • "name": "itemsCreated",
  • "data": {
    }
}

tokenExpired

Triggered when the access_key expires. This event can be triggered at any stage in the widget. If you are using public_token, the default expiration time is 15 minutes.

name
string

Name of the event

object

Additional data for the event.

error_description
string

Description of error occurred in Link

{
  • "name": "tokenExpired",
  • "data": {
    },
  • "error_description": "Your session has expired, please refresh the page."
}

credentialsNotObtained

Triggered when the chooses to exit MeasureOne Link after being an attempt to reset their password

name
string

Name of the event

object

Additional data for the event.

{
  • "name": "credentialsNotObtained",
  • "data": {
    }
}

datasourceNotSupported

Triggered when the selected datasource by Individual is not supported by MeasureOne

Reason Codes

Reason Code Description
USER_LOGIN_NOT_SUPPORTED User login is not supported for the datasource selected by Individual
NO_MATCH_FOUND Could not find matching datasources for the information provided
name
string

Name of the event

object

Additional data for the event.

{
  • "name": "datasourceNotSupported",
  • "data": {
    }
}

exitRequested

Triggered when the user chooses to exit the MeasureOne Link experience.

name
string

Name of the event

object

Additional data for the event. You can use the data from this even to call the service APIs of MeasureOne

{
  • "name": "exitRequested",
  • "data": {
    }
}

Individuals

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.

Create a new Individual

Creates a new Individual. The returned ID is then used in subsequent API calls to reference Items and Services.

SecurityBearer
Request
header Parameters
version
number

Version number of the MeasureOne API you wish to integrate.

Authorization
string <bearer <API_KEY>>

Authorization API Key

Content-type
string <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

Request Body schema: application/json
external_id
string <= 45 characters

A customer generated unique identifier linked to the Individual

first_name
required
string <= 45 characters

First name of the Individual

middle_name
string <= 45 characters

Middle name of the Individual

last_name
required
string <= 45 characters

Last Name of the Individual

attending_name
string <= 45 characters

Attending name of the Individual

email
required
string <= 255 characters

Email address of the Individual

name_prefix
string <= 5 characters

Name prefix

name_suffix
string <= 5 characters

Name suffix

gender
string <= 1 characters

Gender of the Individual

date_of_birth
string <MM/DD/YYYY> /(0[1-9]|1[012])[- \/.](0[1-9]|[12][0-9]|3[01...

Date of birth of the Individual in MM/DD/YYYY format.

phone_number
string <= 15 characters

Phone number of the Individual

object

Address of the Individual

Responses
200

Successful Response

400

Bad Request

401

Authentication with the API Failed due to invalid token OR unauthorized scope / policy

403

Forbidden

405

Method Not Allowed

500

Internal Server Error

post/v3/individuals/new
Request samples
application/json

Example payload when creating an individual

{
  • "external_id": "ABCDEF",
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "john.doe@example.com",
  • "date_of_birth": "10/24/1992",
  • "name_prefix": "Mr.",
  • "name_suffix": "Jr.",
  • "gender": "M",
  • "address": {
    }
}
Response samples
application/json
{
  • "id": "idv_Cevp4Jw9CIsEeNjpgAAjy2EZt3R"
}

Get details of an Individual

Retrieve the details of the given Individual.

SecurityBearer
Request
header Parameters
version
number

Version number of the MeasureOne API you wish to integrate.

Authorization
string <bearer <API_KEY>>

Authorization API Key

Content-type
string <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

Request Body schema: application/json
id
string

Unique ID of the Individual identified by MeasureOne

Responses
200

Successful Response

400

Bad Request

401

Authentication with the API Failed due to invalid token OR unauthorized scope / policy

403

Forbidden

404

Not found

405

Method Not Allowed

500

Internal Server Error

post/v3/individuals/get_by_id
Request samples
application/json
{
  • "id": "idv_Cevp4Jw9CIsEeNjpgAAjy2EZt3R"
}
Response samples
application/json

Example payload when retrieving individual details by ID

{
  • "individual_id": "idv_Cevp4Jw9CIsEeNjpgAAjy2EZt3R",
  • "external_id": "ABCDEF",
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "john.doe@example.com",
  • "date_of_birth": "10/24/1992",
  • "name_prefix": "Mr.",
  • "name_suffix": "Jr.",
  • "gender": "M",
  • "address": {
    },
  • "last_activity_at": 9287384728347
}

Get Items for an individual

Retrieve the list of items created for an Individual

SecurityBearer
Request
header Parameters
version
number

Version number of the MeasureOne API you wish to integrate.

Authorization
string <bearer <API_KEY>>

Authorization API Key

Content-type
string <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

Request Body schema: application/json
One of:
required
object

Individual Details

Responses
200

Successful Response

400

Bad Request

401

Authentication with the API Failed due to invalid token OR unauthorized scope / policy

403

Forbidden

404

Not found

405

Method Not Allowed

500

Internal Server Error

post/v3/individuals/get_items
Request samples
application/json
{
  • "individual": {
    }
}
Response samples
application/json

Example payload

{
  • "individual": {
    },
  • "items": [
    ]
}

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 type of data requested, the reports to be generated, the Link experience, optional Individual communication and messaging. The consumer experience powered by MeasureOne Link is specified by the required datarequest_id. MeasureOne supports multiple types of data requests catering to different use cases. All services accept datarequest_id as a reference.

Create a new Data Request

Creates a new Data Request. The returned ID is then used in Link and in service calls to reference Items and services.

SecurityBearer
Request
header Parameters
version
number

Version number of the MeasureOne API you wish to integrate.

Authorization
required
string <bearer <API_KEY>>

Authorization API Key

Content-type
string <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

Request Body schema: application/json
required
individual_id
required
string

Unique ID of the Individual identified by MeasureOne

type
required
string

Type of the datarequest

Enum: "ACADEMIC_SUMMARY" "ENROLLMENT_STATUS" "EMPLOYMENT_SUMMARY" "INCOME_SUMMARY" "HOME_INSURANCE" "AUTO_INSURANCE" "HOME_INSURANCE_DETAILS" "AUTO_INSURANCE_DETAILS" "INCOME_EMPLOYMENT_DETAILS" "REALIZED_GAINS"
third_party_requester
string <= 1023 characters
Default: null

Optional name of the requester on behalf of which you are raising this Data Request. This is reflected in all communications to the Individual

requester_name
string <= 1023 characters

Your display name. This is reflected in all communications to the Individual. If not provided, the system will take your application display name set in your account preferences.

object
Default: null

Details of the data request that you can provide while creation. This helps in driving the the workflow and the end user experience on MeasureOne Link.

Array of objects

List of endpoints to which the webhooks should be delivered

object

Refresh Policy details to auto refresh data periodically

Responses
200

Successful Response

400

Bad Request

401

Authentication with the API Failed due to invalid token OR unauthorized scope / policy

403

Forbidden

404

Either individual_id or id not found

405

Method Not Allowed

500

Internal Server Error

post/v3/datarequests/new
Request samples
application/json

Example payload create a Data Request

{
  • "individual_id": "idv_Cevp4Jw9CIsEeNjpgAAjy2EZt3R",
  • "type": "ACADEMIC_SUMMARY",
  • "third_party_requester": "ABC Company's largest customer",
  • "requester_name": "ABC Company",
  • "request_details": {
    },
  • "delivery_details": [],
  • "refresh_policy": {
    }
}
Response samples
application/json
{
  • "id": "dr_1faOM8Q4efEWIjzdE2SBM2kLq4O"
}

Generate invitation link for the Data Request

Generate a shareable invitation link for the Data Request. You can share the invitation link with the Individual for them to complete the Data Request. The invitation link will direct the user to MeasureOne's hosted solution.

  • If there is a invitation link with status ACTIVE available, it will return the same invitation link. Generating a invitation link when there is already existing ACTIVE available. it will return the same invitation link with the expires_at updated as provided.
  • It will generate a new invitation link if there are no ACTIVE links available for the Data Request.
SecurityBearer
Request
header Parameters
version
number

Version number of the MeasureOne API you wish to integrate.

Authorization
string <bearer <API_KEY>>

Authorization API Key

Content-type
string <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

Request Body schema: application/json
required
id
required
string

Unique ID of the Data Request identified by MeasureOne

expires_at
number

Timestamp in milliseconds at which the link expires. If not provided, it will take system default i.e. now() + default expiration from your account preferences. The link status will remain ACTIVE till it is either COMPLETE OR 'EXPIRED'

Responses
200

Successful Response

400

Bad Request

401

Authentication with the API Failed due to invalid token OR unauthorized scope / policy

403

Forbidden

404

id not found

405

Method Not Allowed

500

Internal Server Error

post/v3/datarequests/generate_invitation_link
Request samples
application/json
{
  • "id": "dr_1faOM8Q4efEWIjzdE2SBM2kLq4O",
  • "expires_at": 1675605305012
}
Response samples
application/json
{}

Invite the Individual to complete the Data Request

Send a notification to the user to complete the data request. The API will return an error if the link is already EXPIRED. MeasureOne sends upto 3 reminders, 12 hours apart to notify the user. Call this API on an already active link for which notifications have been sent earlier will reset the counter.

SecurityBearer
Request
header Parameters
version
number

Version number of the MeasureOne API you wish to integrate.

Authorization
string <bearer <API_KEY>>

Authorization API Key

Content-type
string <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

Request Body schema: application/json
required
id
required
string

Unique ID of the Data Request identified by MeasureOne

required
Array of objects non-empty

Type of notifications to be sent to the user. At least one notification channel must be provided.

additional_message
string <= 1000 characters
Default: null

Additional message that you may want to pass to the Individual in the invitation email/sms

Responses
200

Successful Response

400

Bad Request

401

Authentication with the API Failed due to invalid token OR unauthorized scope / policy

403

Forbidden

404

Either individual_id or id not found

405

Method Not Allowed

500

Internal Server Error

post/v3/datarequests/notify_user
Request samples
application/json
{
  • "id": "dr_1faOM8Q4efEWIjzdE2SBM2kLq4O",
  • "notifications": [
    ],
  • "additional_message": null
}
Response samples
application/json

Example payload Bad Requests

{
  • "timestamp": 1585747802495,
  • "error_code": "BAD_REQUEST",
  • "http_code": 400,
  • "error_message": "Invalid JSON"
}

Get shareable invitation links for Data Request

Get the list of invitation links associated with a Data Request

SecurityBearer
Request
header Parameters
version
number

Version number of the MeasureOne API you wish to integrate.

Authorization
string <bearer <API_KEY>>

Authorization API Key

Content-type
string <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

Request Body schema: application/json
required
id
required
string

Unique ID of the Data Request identified by MeasureOne

Responses
200

Successful Response

400

Bad Request

401

Authentication with the API Failed due to invalid token OR unauthorized scope / policy

403

Forbidden

404

id not found

405

Method Not Allowed

500

Internal Server Error

post/v3/datarequests/get_invitation_link
Request samples
application/json
{
  • "id": "dr_1faOM8Q4efEWIjzdE2SBM2kLq4O"
}
Response samples
application/json
[]

Get the details of Data Request

Get the details of a Data Request. MeasureOne records various events for a Data Request. These events are summarized in the following table.

Data Request Events

event Description
DATAREQUEST_CREATED Data Request created
DATAREQUEST_UPDATED Updated the details of Data Request
DATAREQUEST_LINK_GENERATED Data Request link generated
NOTIFY_USER_REQUESTED Email and/or SMS notification sent to user
DATAREQUEST_LINK_EXTENDED Link expiry time extended
DATAREQUEST_LINK_EXPIRED Link for Data Request expired
DATAREQUEST_LINK_ACCESSED Data Request link accessed by user
WIDGET_INITIATED Widget initiated for Data Request
DATASOURCE_CLASSIFIED Individual landed on login screen
LOGIN_ATTEMPTED Individual tried to login
INVALID_CREDENTIALS Credentials provided by user are invalid
DATASOURCE_CONNECTED Individual entered valid credentials and the Data Source is connected
INSUFFICIENT_CREDENTIALS Individual was not able to provide credentials
ITEM_CREATED Item was downloaded and stored database
ITEM_PROCESSED Data extracted and formatted
ITEM_UNPROCESSABLE Unable to process an item
ITEMS_AVAILABLE Data Extraction is completed with some items
NO_ITEMS Data Extraction is completed without an item
USER_INTERVENTION_REQUIRED Individual re-login required
DATASOURCE_NOT_FOUND Individual was unable to find Data Source
PLAID_INITIATED Plaid flow initiated
PLAID_CONNECTION_SUCCESSFUL Plaid connection successful
PLAID_CONNECTION_UNSUCCESSFUL Plaid connection unsuccessful
REPORT_REQUESTED Report requested by customer
REPORT_AVAILABLE Report data is available
REPORT_ERROR Error occurred during generating report
UPDATES_AVAILABLE Updated data for Data Request is available
REFRESH_INITIATED A scheduled refresh is initiated for Data Request
REFRESH_FAILED A scheduled refresh is failed for Data Request
CONSENT_UPDATED Consent updated for Data Request
SecurityBearer
Request
header Parameters
version
number

Version number of the MeasureOne API you wish to integrate.

Authorization
string <bearer <API_KEY>>

Authorization API Key

Content-type
string <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

Request Body schema: application/json
required
id
required
string

Unique ID of the Data Request identified by MeasureOne

get_x_auth_token_credentials
boolean
Default: false

If this value is true, the response will contain x_auth_token_credentials object.

get_consent
boolean
Default: false

If this value is true, the response will contain consent object.

Responses
200

Successful Response

400

Bad Request

401

Authentication with the API Failed due to invalid token OR unauthorized scope / policy

403

Forbidden

404

id not found

405

Method Not Allowed

500

Internal Server Error

post/v3/datarequests/get_by_id
Request samples
application/json
{
  • "id": "dr_1faOM8Q4efEWIjzdE2SBM2kLq4O",
  • "get_x_auth_token_credentials": false,
  • "get_consent": false
}
Response samples
application/json

Example payload when retrieving Data Request details by ID

{
  • "id": "dr_1faOM8Q4efEWIjzdE2SBM2kLq4O",
  • "individual_id": "idv_Cevp4Jw9CIsEeNjpgasjy2EZt3R",
  • "type": "ACADEMIC_SUMMARY",
  • "autorun_services": true,
  • "created_at": 1673322103030,
  • "updated_at": 1673492103030,
  • "third_party_requester": "ABC Company's largest customer",
  • "requester_name": "ABC Company",
  • "requester_logo": "null",
  • "request_details": {
    },
  • "delivery_details": [],
  • "widget_id": "lnk_23JUuA89ikWQ3JVesPuO7KNZUfr",
  • "invitation_links": [],
  • "last_activity_type": "CREATED",
  • "last_activity_at": 1673322103030,
  • "refresh_policy": {
    },
  • "event_logs": [
    ]
}

Expire invitation link for Data Request

Expires the invitation link for a data request.

SecurityBearer
Request
header Parameters
version
number

Version number of the MeasureOne API you wish to integrate.

Authorization
string <bearer <API_KEY>>

Authorization API Key

Content-type
string <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

Request Body schema: application/json
required
id
required
string

MeasureOne recognized Unique ID of the Data Request

Responses
200

Successful Response

400

Bad Request

401

Authentication with the API Failed due to invalid token OR unauthorized scope / policy

403

Forbidden

404

id not found

405

Method Not Allowed

500

Internal Server Error

post/v3/datarequests/expire_invitation_link
Request samples
application/json

Example payload to expire an data request link

{
  • "id": "dr_1faOM8Q4efEWIjzdE2SBM2kLq4O",
  • "expiry_reason": {
    }
}
Response samples
application/json

Example payload Bad Requests

{
  • "timestamp": 1585747802495,
  • "error_code": "BAD_REQUEST",
  • "http_code": 400,
  • "error_message": "Invalid JSON"
}

Get the list of Data Requests

Get the list of Data Requests based on the filter criteria provided. If not filter criteria is provided, it will fetch the latest 200 data requests.

SecurityBearer
Request
header Parameters
version
number

Version number of the MeasureOne API you wish to integrate.

Authorization
string <bearer <API_KEY>>

Authorization API Key

Content-type
string <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

Request Body schema: application/json
required
object

Filters that can be applied to fetch the list of Data Requests

fields
Array of strings

Fields you want in response. The default fields will be id, individual_id, type, created_at, invitation_links, event_logs

Responses
200

Successful Response

400

Bad Request

401

Authentication with the API Failed due to invalid token OR unauthorized scope / policy

403

Forbidden

405

Method Not Allowed

500

Internal Server Error

post/v3/datarequests/get
Request samples
application/json

Example payload for datarequest/get

{
  • "filters": {
    },
  • "fields": [
    ]
}
Response samples
application/json

Example payload for getting list of Data Requests

[
  • {
    }
]

Update a Data Request

Update details of a Data Request

SecurityBearer
Request
header Parameters
version
number

Version number of the MeasureOne API you wish to integrate.

Authorization
string <bearer <API_KEY>>

Authorization API Key

Content-type
string <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

Request Body schema: application/json
required
id
string

Unique ID of the Data Request identified by MeasureOne

object
Default: null

Data request options provided during creation.

third_party_requester
string <= 1023 characters
Default: null

Name of the third party requester. This name will be reflected in the communications to the Individual.

requester_name
string <= 1023 characters

Display name of the requester. This name will be reflected in the communications to the Individual. If not provided, the system will take your application display name set in your account preferences.

Array of objects

List of endpoints to which the webhooks should be delivered

object

Refresh Policy details to auto refresh data periodically

Responses
200

Successful Response

400

Bad Request

401

Authentication with the API Failed due to invalid token OR unauthorized scope / policy

403

Forbidden

404

id not found

405

Method Not Allowed

500

Internal Server Error

post/v3/datarequests/update
Request samples
application/json

Example payload Update a data request

{
  • "id": "dr_1faOM8Q4efEWIjzdE2SBM2kLq4O",
  • "requester_name": "ABC screening",
  • "request_details": {
    },
  • "delivery_details": [],
  • "refresh_policy": {
    }
}
Response samples
application/json
{
  • "id": "dr_1faOM8Q4efEWIjzdE2SBM2kLq4O"
}

Refresh data on demand

Refresh data for a Data Request on demand.

SecurityBearer
Request
header Parameters
version
number

Version number of the MeasureOne API you wish to integrate.

Authorization
string <bearer <API_KEY>>

Authorization API Key

Content-type
string <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

Request Body schema: application/json
required
id
required
string

Unique ID of the DataRequest identified by MeasureOne

Responses
201

Successful Response

400

Bad Request

401

Authentication with the API Failed

403

Forbidden

404

id not found

405

Method Not Allowed

500

Internal Server Error

post/v3/datarequests/refresh_now
Request samples
application/json
{
  • "id": "dr_1faOM8Q4efEWIjzdE2SBM2kLq4O"
}
Response samples
application/json

Example payload Bad Requests

{
  • "timestamp": 1585747802495,
  • "error_code": "BAD_REQUEST",
  • "http_code": 400,
  • "error_message": "Invalid JSON"
}

Data Sources

Get / Search Data Sources

Get / Search Data Sources

SecurityBearer
Request
header Parameters
version
number

Version number of the MeasureOne API you wish to integrate.

Authorization
string <bearer <API_KEY>>

Authorization API Key

Content-type
any <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise.

Request Body schema: application/json
required
object

Allows filtering the list by different attributes

Responses
200

Successful Response

400

Bad Request

401

Authentication with the API Failed due to invalid token OR unauthorized scope / policy

403

Forbidden

405

Method Not Allowed

post/v3/datasources/get
Request samples
application/json
{
  • "filters": {
    }
}
Response samples
application/json
[
  • {
    }
]

Items

Items are the resource representing data shared by Individuals with MeasureOne. The underlying document of an Item is called source data These can be college transcripts, pay stubs, real estate titles, etc. Items are stored and information from them can be retrieved through the Service API calls. The information in an Item is shared through the Service APIs according to the consumer permission. Importantly, note that unless permissioned by the Individual, the Item data may not be shared directly with you.

Submit a new item

Usage options

The usage of /v3/items/new varies depending on its intended use and availability of information. The request payload must include either a source_data_value object OR a source_data_reference object. Passing both as a part of the payload may result in processing errors.

Using Source Data Object

If the attribute values for a transcript are known, send the source data inline in the request using the source_data_value object.

Using Source Data Reference Object

If the data is in a document, upload it using the /items/upload endpoint or make it available at a remote location. A reference to the uploaded document should then be included in the request using the source_data_reference object.

SecurityBearer
Request
header Parameters
version
number

Version number of the MeasureOne API you wish to integrate.

Authorization
string <bearer <API_KEY>>

Authorization API Key

Content-type
string <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

Request Body schema: application/json
required
individual_id
string
Deprecated

MeasureOne generated unique identifier linked to the item. If this is not provided, MeasureOne will generate a new individual_id for given item. This attribute is deprecated

datarequest_id
string

MeasureOne generated unique datarequest identifier linked to the item. If this is not provided, MeasureOne will generate a new datarequest for given item.

external_id
string

A customer generated unique identifier linked to the item

datasource_id
required
string

Unique identifier of the datasource. This attribute is non-mandatory M1_DIGEST source_data_type

media_type
string

Media type of the source data document Supported Types: application/pdf, image/jpeg, image/png, image/tiff, image/bmp, text/html

source_data_type
required
string

The type of the source_data

Enum Value Description
M1_ACADEMIC_RECORD

JSON payload constituting the academic Record of the Individual

M1_DIGEST

JSON payload for Digest of the academic record

TRANSCRIPT_FILE

PDF, HTML or Image of the academic transcript

PAYSTUB_FILE

PDF, HTML or Image of the paystub

W2_FILE

PDF, HTML or Image of the W-2

INSURANCE_POLICY

PDF, HTML or Image of the insurance policy

INSURANCE_CARD

PDF or Image of the insurance card

STUDENT_ID_CARD

PDF or Image of the Student ID

PROCEEDS_1099_B

PDF of 1099-B

refresh_id
string

Unique ID of a scheduled refresh identified by MeasureOne

required
Array of Source Data Value (object) or Source Data Reference (object) (Source Data Object)

Source data object contains one complete academic record. Multiple source data objects containing source_data_value will result in an error

Responses
200

Successful Response. You can now call the end points to get desired information from a transcript.

400

Bad Request

401

Authentication with the API Failed due to invalid token OR unauthorized scope / policy

403

Forbidden

405

Method Not Allowed

500

Internal Server Error

post/v3/items/new
Request samples
application/json

Example payload when creating a transcript with M1_DIGEST

{
  • "external_id": "ABCDECD",
  • "datarequest_id": "dr_Cevp4Jw9CIsEeNjpgAAjy2EZt3R\"",
  • "source_data_type": "M1_DIGEST",
  • "acquisition_completed": true,
  • "manual_upload_completed": false,
  • "source_data": [
    ]
}
Response samples
application/json
{
  • "id": "itm_Cevp4Jw9CIsEeNjpgAAjy2EZt3R",
  • "individual_id": "idv_Cevp4Jw9CIsEeNjpgAAjy2EZt3R",
  • "datarequest_id": "dr_1faOM8Q4efEWIjzdE2SBM2kLq4O",
  • "processing_status": "IN_PROGRESS"
}

Upload files

The /items/upload endpoint is used to upload documents containing source data for a new item.
Supported File Types: HTML, JPG, JSON, PDF, PNG, TIFF, TIF

SecurityBearer
Request
header Parameters
version
number

Version number of the MeasureOne API you wish to integrate.

Authorization
string <bearer <API_KEY>>

Authorization API Key

Content-type
string <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

Request Body schema: application/form-data-upload
files
Array of strings
Responses
200

Successful Response

400

Bad Request

401

Authentication with the API Failed due to invalid token OR unauthorized scope / policy

403

Forbidden

405

Method Not Allowed

500

Internal Server Error

post/v3/items/upload
Request samples
application/form-data-upload

Example payload when uploading item as file(s)

{
  "files": [
    "path/to/file.pdf"
  ]
}
Response samples
application/json
[
  • {
    },
  • {
    }
]

Get item details

Retrieves an existing Item data. The endpoint can be used once the processing_status for an Item is COMPLETED. It will return Item data in its response payload. If the processing of the Item is not yet complete, it will return the current status of the Item. This API is asynchronous.

The optional data_confidence object, if present, lists data attributes whose extraction accuracy was lower than 95%. Such a scenario can come up when processing images or other unstructured source data items. The attributes are specified as a json path within the corresponding data object. In the event that the data_confidence object is not present (i.e., null), the data extraction should be considered 100% accurate.

SecurityBearer
Request
header Parameters
version
number

Version number of the MeasureOne API you wish to integrate.

Authorization
string <bearer <API_KEY>>

Authorization API Key

Content-type
string <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

Request Body schema: application/json
id
required
string

Unique ID of the Item identified by MeasureOne

Responses
200

Successful Response

400

Bad Request

401

Authentication with the API Failed due to invalid token OR unauthorized scope / policy

403

Forbidden

405

Method Not Allowed

422

Unprocessable Entity

500

Internal Server Error

post/v3/items/get_by_id
Request samples
application/json

Example payload for retrieving the item details

{
  • "id": "itm_Cevp4Jw9CIsEeNjpgAAjy2EZt3R"
}
Response samples
application/json
{
  • "id": "itm_Cevp4Jw9CIsEeNjpgAAjy2EZt3R",
  • "individual_id": "idv_Cevp4Jw9CIsEeNjpgAAjy2EZt3R",
  • "external_id": "ABCDECD",
  • "datasource_id": "dts_1skdjflsoer3432ndsldfs",
  • "datarequest_id": "dr_2ILkNTtHEC0Q9dMOBnRB6oL7R69",
  • "media_type": "application/pdf",
  • "source_data": [
    ],
  • "source_data_type": "TRANSCRIPT_FILE",
  • "duplicates": [ ],
  • "refresh_id": "rfs_1233ks2lkdw4i4j2li342podjslfu",
  • "data": {
    },
  • "confidence": {
    },
  • "processing_status": "COMPLETED",
  • "created_at": 1556781225343,
  • "updated_at": 1556781257964
}

Get item files

The items/get_files endpoint is used to download the source data for an item. The API returns a byte stream of a zip file.

SecurityBearer
Request
header Parameters
version
number

Version number of the MeasureOne API you wish to integrate.

Authorization
string <bearer <API_KEY>>

Authorization API Key

Content-type
string <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

Request Body schema: application/json
id
required
string

Unique ID of the Item identified by MeasureOne

Responses
200

Successful Response will return a byte stream of a zip file

400

Bad Request

401

Authentication with the API Failed due to invalid token OR unauthorized scope / policy

403

Forbidden

404

Not found

405

Method Not Allowed

500

Internal Server Error

post/v3/items/get_files
Request samples
application/json

Example payload for retrieving the files for an item

{
  • "id": "itm_Cevp4Jw9CIsEeNjpgAAjy2EZt3R"
}
Response samples
application/json

Example payload Bad Requests

{
  • "timestamp": 1585747802495,
  • "error_code": "BAD_REQUEST",
  • "http_code": 400,
  • "error_message": "Invalid JSON"
}

Get PDF item

The items/get_pdf endpoint is used to download/view an item as PDF document. The API returns a byte stream of a PDF item file.

SecurityBearer
Request
header Parameters
version
number

Version number of the MeasureOne API you wish to integrate.

Authorization
string <bearer <API_KEY>>

Authorization API Key

Content-type
string <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

Request Body schema: application/json
required
id
required
string

Unique ID of the Item identified by MeasureOne

Responses
200

Successful Response will return a byte stream of a PDF file

400

Bad Request

401

Authentication with the API Failed due to invalid token OR unauthorized scope / policy

403

Forbidden

404

Bad Request

405

Method Not Allowed

500

Internal Server Error

post/v3/items/get_pdf
Request samples
application/json
{
  • "id": "itm_Cevp4Jw9CIsEeNjpgAAjy2EZt3R"
}
Response samples
application/json

Example payload Bad Requests

{
  • "timestamp": 1585747802495,
  • "error_code": "BAD_REQUEST",
  • "http_code": 400,
  • "error_message": "Invalid JSON"
}

Invitations

MeasureOne offers a framework for initiating the consumer-permissioned data exchange using automatically generated invitations. These invitations contain unique links that refer the user back to the MeasureOne hosted portal in a personalized manner to initiate and complete the consumer-permissioned data exchange. These API endpoints provide a programmatic interface to this framework. Note that a zero code alternative to a programmatic implementation is to use the MeasureOne Customer Dashboard to interface with the Invitations framework.

Create a new InvitationDeprecated

Creates a new invitation. This API is deprecated. Use /datarequests/generate_link and /datarequests/notify_user to create an invitation

SecurityBearer
Request
header Parameters
version
number

Version number of the MeasureOne API you wish to integrate.

Authorization
string <bearer <API_KEY>>

Authorization API Key

Content-type
string <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

Request Body schema: application/json
One of:
individual_id
required
string

Unique ID of the Individual identified by MeasureOne

validity
number

Validity in seconds from the created Timestamp. Default is 259200 seconds (3 days) from the created time stamp.

link_only
boolean

Boolean indicating whether to send communication to the Individual or just generate a link. Default is false and MeasureOne sends the Email Communication to the Individual. If false, individual_id is required.

requestor_name
string

Name of the requesting organization / entity

additional_message
string <= 1000 characters

Additional message that you may want to pass to the candidate in the invitation email. This attribute cannot be used when link_only is false.

institution_name
string

Institution name for which you want the candidate to complete verification.

query_type
required
Array of strings
Items Enum: "ACADEMIC_SUMMARY" "ENROLLMENT_STATUS" "EMPLOYMENT_SUMMARY" "INCOME_SUMMARY" "AUTO_INSURANCE" "AUTO_INSURANCE_DETAILS" "HOME_INSURANCE" "HOME_INSURANCE_DETAILS" "INCOME_EMPLOYMENT_DETAILS" "REALIZED_GAINS"
Responses
200

Successful Response

400

Bad Request

401

Authentication with the API Failed due to invalid token OR unauthorized scope / policy

403

Forbidden

404

Invalid Individual ID

405

Method Not Allowed

500

Internal Server Error

post/v3/invitations/new
Request samples
application/json

Submitting invitation new with Institution name

{
  • "individual_id": "idv_Cevp4Jw9CIsEeNjpgAAjy2EZt3R",
  • "validity": 259200,
  • "link_only": false,
  • "requester_name": "string value",
  • "additional_message": "Please use this invitation for University of Michigan Ann Arbor",
  • "institution_name": "University of Michigan Ann Arbor",
  • "query_type": [
    ]
}
Response samples
application/json
{
  • "id": "1faOM8Q4efEWIjzdE2SBM2kLq4O"
}

Get the list of invitationsDeprecated

Get the list of invitations based on the filter criteria provided. This API is deprecated. Use /datarequests/get

SecurityBearer
Request
header Parameters
version
number

Version number of the MeasureOne API you wish to integrate.

Authorization
string <bearer <API_KEY>>

Authorization API Key

Content-type
string <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

Request Body schema: application/json
required
object
Responses
200

Successful Response

400

Bad Request

401

Authentication with the API Failed due to invalid token OR unauthorized scope / policy

403

Forbidden

405

Method Not Allowed

500

Internal Server Error

post/v3/invitations/get
Request samples
application/json
{
  • "filters": {
    }
}
Response samples
application/json
[
  • {
    }
]

Get details of an InvitationDeprecated

Get the details of an Invitation. The endpoint will return an error response if the Invitation is not found. This API is deprecated. Use /datarequests/get_by_id

SecurityBearer
Request
header Parameters
version
number

Version number of the MeasureOne API you wish to integrate.

Authorization
string <bearer <API_KEY>>

Authorization API Key

Content-type
string <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

Request Body schema: application/json
required
id
required
string

MeasureOne recognized Unique ID of the Invitation

Responses
200

Successful Response

400

Bad Request

401

Authentication with the API Failed due to invalid token OR unauthorized scope / policy

403

Forbidden

404

Invalid Invitation ID

405

Method Not Allowed

500

Internal Server Error

post/v3/invitations/get_by_id
Request samples
application/json
{
  • "id": "1faOM8Q4efEWIjzdE2SBM2kLq4O"
}
Response samples
application/json
{
  • "id": "1xkaiwio21ksdj135",
  • "individual_id": "idv_Cevp4Jw9CIsEeNjpgAAjy2EZt3R",
  • "updated_at": 1596268104941,
  • "created_at": 1596268104941,
  • "expires_at": 1596468135586,
  • "completed_at": 1596468135586,
  • "status": "USED",
  • "link_only": false,
  • "requester_name": "string value",
  • "additional_message": "Please use this invitation for University of Michigan Ann Arbor",
  • "institution_name": "University of Michigan Ann Arbor",
  • "query_type": [
    ],
  • "expiry_reason": "LINK_EXPIRED",
  • "datasource": {
    }
}

Expire an InvitationDeprecated

Expire an Invitation. The Invitation can be expired only if it has not yet been EXPIRED. An attempt to expire an invitation that is already expired will return an error. This API is deprecated. Use /datarequests/expire_invitation_link

SecurityBearer
Request
header Parameters
version
number

Version number of the MeasureOne API you wish to integrate.

Authorization
string <bearer <API_KEY>>

Authorization API Key

Content-type
string <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

Request Body schema: application/json
required
id
required
string

MeasureOne recognized Unique ID of the Invitation

Responses
200

Successful Response

400

Bad Request

401

Authentication with the API Failed due to invalid token OR unauthorized scope / policy

403

Forbidden

404

Invalid Invitation ID

405

Method Not Allowed

500

Internal Server Error

post/v3/invitations/expire
Request samples
application/json
{
  • "id": "1faOM8Q4efEWIjzdE2SBM2kLq4O"
}
Response samples
application/json

Example payload Bad Requests

{
  • "timestamp": 1585747802495,
  • "error_code": "BAD_REQUEST",
  • "http_code": 400,
  • "error_message": "Invalid JSON"
}

Education

Get academic summary

Provides a summary of academic and educational data, including dates of attendance, degrees achieved, and other fields. Please see response payload for the detailed fields. MeasureOne uses a set of heuristics to make a final determination. These heuristics are summarized in Reason Codes as detailed in the following table.

Reason Codes

Code Description
MAS_DRVD_ATTNDNC_ACAD_SESSION Attendance determined via academic session enrollments
MAS_DRVD_STD_CLSF_CRSE_IN_PRG Courses are in progress
MAS_EXPLICIT_TYPE Enrollment Type explicitly available on the school website
MAS_DRVD_ENRL_TYPE_ENRL_STS Enrollment Type derived based INACTIVE enrollment status
MAS_DRVD_ENRL_TYPE Enrollment Type derived based on credits attempted in currently enrolled term
MAS_DRVD_ENRL_TYPE_PRV_TERM Enrollment Type derived based on credits attempted in the previous enrolled term within 180 days of the date available in the data
MAS_DRVD_ENRL_TYPE_INFR_CRED Enrollment Type derived based on inferred credits attempted
MAS_DRVD_ENRL_TYPE_COOP_CRSE Enrollment Type derived based on enrolled COOP course
MAS_INSUFFICIENT_DATA Attendance record not available
MAS_INSUFFICIENT_DATA Date degree was awarded not available
MAS_INSUFFICIENT_DATA Degree GPA not available
MAS_INSUFFICIENT_DATA Degree majors not available
MAS_INSUFFICIENT_DATA Description of degree not available
MAS_INSUFFICIENT_DATA Number of credits not available
MAS_INSUFFICIENT_DATA Number of degree credits not available
MAS_INSUFFICIENT_DATA Status of student degree not available
MAS_INSUFFICIENT_DATA Student classification data not available
MAS_INSUFFICIENT_DATA Student degree data not available
MAS_INSUFFICIENT_DATA Student GPA not available
MAS_INSUFFICIENT_DATA Type of student degree not available
MAS_INSUFFICIENT_DATA Enrollment Type of student not available
ITEM_ON_HOLD Student transcript(s) on financial hold
MAS_VF_DAC Verification method: Direct school account connection
MAS_VF_USD Verification method: User-submitted transcript
MAS_VF_DAC_USD Verification method: Direct school account connection and one or more user-submitted transcript
SecurityBearer
Request
header Parameters
version
number

Version number of the MeasureOne API you wish to integrate.

Authorization
string <bearer <API_KEY>>

Authorization API Key

Content-type
string <application/json>

Content-type of the request payload. MeasureOne accepts content in application/json format unless specified otherwise

Request Body schema: application/json
One of:
datarequest_id
required
string

Unique ID of the Data Request identified by MeasureOne

Responses
200

Successful Response

400

Bad Request

401

Authentication with the API Failed due to invalid token OR unauthorized scope / policy

403

Forbidden

404

One or more provided parameters were not found. E.g - individual_id or transaction_id or datarequest_id

422

Unprocessable Entity. Occurs when academic summary cannot be generated due to data unavailability

500

Internal Server Error

post/v3/services/get_academic_summary
Request samples
application/json
{
  • "datarequest_id": "dr_1faOM8Q4efEWIjzdE2SBM2kLq4O"
}
Response samples
application/json
{
  • "individual": {
    },
  • "transaction_id": "trx_1fGUhrSFQ1L4Jd2rOeQiHQgt986",
  • "datarequest_id": "dr_1faOM8Q4efEWIjzdE2SBM2kLq4O",
  • "processing_status": "COMPLETED",
  • "academic_summary": [