MeasureOne API (3.0)

The MeasureOne API enables secure, consumer-permissioned data integration into your applications and workflows. Our platform facilitates the entire data-sharing process, from consent management to data delivery, while maintaining the highest standards of privacy and security.

At its core, our API streamlines the complex process of permissioned data sharing. When users grant consent to share their information, they either upload their documents or provide credentials through the MeasureOne LINK widget to access their data sources. Our platform then securely connects to these sources, acquires the authorized data, and delivers it through standardized APIs. This process ensures both data integrity and user privacy, with built-in safeguards that enforce consent boundaries and prevent unauthorized access.

The platform offers comprehensive features including secure consent management, safe credential handling, automated data acquisition, and standardized delivery - all while guaranteeing data authenticity and tamper-proof delivery. By abstracting these complex workflows into straightforward APIs, we enable you to focus on your application while we handle the intricacies of secure data access and privacy compliance.

Download OpenAPI description

openapi.json

openapi.yaml

Overview

E-mail

support@measureone.com

Servers

Production

https://api.measureone.com/

Staging

https://api-stg.measureone.com/

API Host and Protocols

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.

Operations

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	ENTERPRISE_WIDGET
/individuals/new	YES	YES	YES
/individuals/get_by_id	YES	YES	YES
/individuals/get_items	YES	YES	NO
/datarequests/new	YES	YES	YES
/datarequests/update	YES	YES	YES
/datarequests/get	YES	YES	YES
/datarequests/get_by_id	YES	YES	YES
/datarequests/generate_invitation_link	YES	YES	YES
/datarequests/notify_user	YES	YES	YES
/datarequests/get_invitation_link	YES	YES	YES
/datarequests/expire_invitation_link	YES	YES	NO
/datarequests/refresh_now	YES	YES	NO
/datarequests/enable_refresh	YES	YES	NO
/datarequests/disable_refresh	YES	YES	NO
/datasources/get	YES	YES	YES
/items/new	YES	YES	YES
/items/upload	YES	YES	YES
/items/get_by_id	YES	YES	YES
/items/get_files	YES	YES	NO
/items/get_pdf	YES	YES	NO
/services/get_academic_summary	NO	YES	YES
/services/get_enrollment_status	NO	YES	YES
/services/gradscore	NO	YES	NO
/services/meritscore	NO	YES	NO
/services/get_digest_by_id	NO	YES	NO
/services/get_employment_summary	NO	YES	YES
/services/get_income_summary	NO	YES	YES
/services/get_income_employment_details	NO	YES	YES
/services/get_insurance_details	NO	YES	YES
/services/get_realized_gains	NO	YES	YES

Generate Access Token

Request

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

Security

Basic

Headers

Authorizationstring(Basic <client_id>:<secret>)

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

Content-typestring(application/json)

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

Bodyapplication/json

object(EmptyBody)

curl -i -X POST \
  -u <username>:<password> \
  https://api.measureone.com/v3/auth/generate_access_token \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

Successful Response

Bodyapplication/json

access_tokenstring

Access token generated for you to access MeasureOne API

Example: "6fd5122a-9a91-4bd6-1219-d6e71fd123b0"

token_typestring

Type of access token. This value is always bearer

Example: "bearer"

expires_innumber

Seconds left to expire

Example: 899

expires_atnumber

Timestamp in milliseconds at which access token will expire

Example: 1681191048000

Response

application/json

Response Access token

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

Invalidate Access Token

Request

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

Security

Basic

Headers

Authorizationstring(Basic <client_id>:<secret>)

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

Content-typestring(application/json)

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

Bodyapplication/json

access_tokenstringrequired

Access token generated for you to access MeasureOne API

Example: "6fd5122a-9a91-4bd6-1219-d6e71fd123b0"

curl -i -X POST \
  -u <username>:<password> \
  https://api.measureone.com/v3/auth/invalidate \
  -H 'Content-Type: application/json' \
  -d '{
    "access_token": "6fd5122a-9a91-4bd6-1219-d6e71fd123b0"
  }'

Responses

Successful Response

Response

No content

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.

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 Requests	/datarequests/refresh_now	Refresh data on demand for Data Requests
Data Requests	/datarequests/enable_refresh	Enable data refresh for Data Requests
Data Requests	/datarequests/disable_refresh	Disable data refresh for Data Requests
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

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 Requests	/datarequests/refresh_now	No
Data Requests	/datarequests/enable_refresh	No
Data Requests	/datarequests/disable_refresh	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

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.

Operations

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.

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_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
CUSTOM	Request custom data from an Individual that is not covered by the above types.

Operations

Data Sources

Data Sources are online locations of Items. Individuals (your users) connect Data Sources and provide MeasureOne with their credentials and consent so that MeasureOne may retrieve Items (their data) from the Data Source to be subsequently shared with you in a strictly permissioned way.

Data Sources may be universities, financial institutions, payroll systems, government records. MeasureOne curates the list of Data Sources to ensure the provenance of the retrieved documents. Since not all Data Sources may be relevant to your application, the API allows you to configure and select the list of Data Sources that are displayed to your user.

Operations

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.

Operations

Invitations

The Invitations resource is deprecated. Use /datarequests/ resource to generate a link and /datarequests/notify_user to send the communication to the Individual

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.

Operations

Experiences

Experiences stores the different resources required by the widget, hostedportal, etc.

Operations

Education

Operations

Income & Employment

Operations

Insurance

Operations

Tax Records

Operations

Webhook Events

MeasureOne uses webhooks to notify client applications of certain events. Whenever a notification event occurs we'll submit a POST to your designated webhook URL with information about the event. The webhook URL is configured as part of the onboarding process. You can also provide the webhook details while creating a Data Request

Webhooks

Responding to Webhooks

To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code. Any other information returned in the response headers or response body is ignored.

Webhook Security

MeasureOne's webhook supports JWT and Basic method authorization. The API key configured during the setup of the webhook in the customer onboarding process, will be present in the Authorization header.

M1_ACADEMIC_RECORD

A standardized academic transcript format based on the EDI (Electronic Data Interchange) 130 standard. This schema represents a comprehensive student academic record/transcript that includes course information, grades, academic achievements, and other educational data exchanged between academic institutions. The format supports both high school and college/university transcripts.

transcript_datestring(MM/DD/YYYY)

Date on which the transcript was issued. transcript_date should not be a future date

student_idstring

Unique, school-provided Student ID

other_attributesobject

Any other Attributes which are not defined in M1 TRANSCRIPT

studentobject

Object with information about the Individual, as provided on the transcript

pgcArray of objects

List of parent/guardian/counselor information on the transcript

immunizationsArray of objects

List of immunization provided on the transcript

test_recordsArray of objects

List of national, regional, state, or local test records provided on the transcript

previous_academic_recordArray of objects

List of previous academic records provided on the transcript

teaching_institutionobject

Object with information about the teaching institution for which the transcript was issued

degree_awarding_institutionobject

Object with information about the degree awarding institution for which the transcript was issued

academic_summaryArray of objects

Summary information about the degree

academic_sessionsArray of objects

List of academic sessions provided on the transcript

transcript_institutionobjectDeprecated

Object with information about the institution for which the transcript was issued

M1_DIGEST

A summary object computed based on the academic record of the student.

degree_typestringrequired

Granular level of study. Enum HIGH-SCHOOL-DIPLOMA, ASSOCIATE, BACHELORS, MASTERS, MASTERS-RESEARCH, DOCTORAL, CERTIFICATE, DIPLOMA, NON-DEGREE, PROFESSIONAL, UNDERGRADUATE

Example: "BACHELORS"

years_in_schoolnumber(double)required

Number of years that the Individual has been enrolled, including any breaks between enrollments. Non-zero, non-negative, rounded to two decimals

Example: 4

min_gradestringrequired

Lowest grade earned on a course taken

Example: "D"

cgpanumber(double)required

Weighted CGPA, in the 0 to 4 scale, for the combination of courses attended at the transcript-issuing school

Example: 3

last_term_gpanumber(double)required

GPA, in the 0 to 4 scale, for the last term of attendance

Example: 2

credits_earnednumber(double)required

Total credits earned including transferred credits, converted to a standard semester credit hour system

Example: 65

M1_INCOME_EMPLOYMENT_RECORD

This schema represents a comprehensive record of an individual's income sources, employment details, and financial status. It includes information such as employer details, job title, salary, employment type, and work history.

record_datestring(MM/DD/YYYY)

Date on which the record was generated

pay_datestring(MM/DD/YYYY)

Payment date

intervalobject

Interval for which the income employment details is denoted

employeeobject

Details about the employee

employerobject

Details about the employer

rolesArray of objects

Array of objects representing roles of an Individual during their employment

earningsArray of objects

Array of objects representing earnings

deductionsArray of objects

Deductions of the employee

depositsArray of objects

Employee Deposits

benefitsArray of objects

Benefits for the employee

M1_INSURANCE_RECORD

This schema represents a comprehensive record of an individual's insurance policies, including policy type, coverage details, premium amounts, beneficiaries, claims history, and insurer information.

record_datestring

Date on which the record was generated

cancelled_datestring

Date on which the insurance was cancelled

pending_cancel_datestring

Date on which the insurance will be cancelled

policy_numberstring

Policy number

statusstring

Policy status

Enum"ACTIVE""EXPIRED""PENDING_ACTIVATION""PENDING_CANCELLATION""PENDING_EXPIRATION""CANCELLED""UNVERIFIED""RESCINDED""NOT_AVAILABLE"

policy_typesArray of strings

Type of Policy

Items Enum"AUTO""HOME""RENTERS""PERSONAL_UMBRELLA"

premium_amountobject

Premium amount of policy

payment_frequencystring

Frequency of payment.

Enum"ANNUAL""SEMI_ANNUAL""QUARTERLY""MONTHLY""SEMI_MONTHLY""OTHER"

coverage_periodobject

Insurance coverage period

policy_holdersArray of objects

List of policy holders

insurance_providerobject

Details of insurance provider

remit_toobject

Details of entity to whom premium is remitted

insurance_agentobject

Details of insurance agent

coveragesArray of objects

List of policy coverages

M1_AUTO_INSURANCE_CLAIM_RECORD

This schema represents an individual's auto insurance claim record, including claim details, policy information, vehicle data, involved parties, and payment breakdowns.

as_of_datestring

Date on which the record was generated

auto_insurance_claimsArray of objects

M1_STUDENT_ID_RECORD

This schema represents the student's identification record, containing personal details, academic background, and teaching institution information.

valid_fromstring

Student ID valid from

valid_uptostring

Student ID valid upto

studentobject

Object with information about the Student, as provided on Student ID

teaching_institutionobject

Object with information about the teaching institution

degree_awarding_institutionobject

Object with information about the degree awarding institution

degreesArray of objects

List of degrees found in Student ID

M1_W2_RECORD

The M1_W2_RECORD Schema represents the details of a W-2 tax form, which reports wages, tips, and other compensation paid to an employee. It includes information about the employee, employer, earnings, taxes withheld, and other payroll-related details for tax filing purposes.

allocated_tipsstring

Tips allocated to the employee by the employer.

employeeobject

social_security_tipsstring

Tips subject to Social Security tax.

local_wages_tipsstring

Local wages and tips.

control_numberstring

Control number assigned by the employer.

federal_income_tax_withheldobject

medicare_tax_withheldobject

employerobject

box_13object

box_12Array of arrays

Box 12 items, including codes and amounts.

statestring

State code for state wages and taxes.

box_9string

Verification code for employment-based verification.

dependent_care_benefitsstring

Dependent care benefits provided by the employer.

box_14_otherstring

Other amounts reported in Box 14.

record_yearinteger

Year for which the record is applicable.

state_wages_tipsobject

wages_tips_other_compobject

nonqualified_plansstring

Nonqualified plans amount.

social_security_wagesobject

social_security_tax_withheldobject

locality_namestring

Name of the locality for local wages and taxes.

medicare_wages_and_tipsobject

employer_state_id_numberstring

Employer's state identification number.

state_income_taxobject

local_income_taxstring

Amount of local income tax withheld.

M1_1099_RECORD

The M1_1099_RECORD Schema represents the details of a 1099 tax form, which reports income such as nonemployee compensation, rents, royalties, and other types of income. It includes information about the payer and recipient (e.g., names, addresses, and tax identification numbers), income amounts, and any federal or state tax withholdings. This schema is used for tax reporting purposes.

record_yearnumber(YYYY)

Year on which the record was generated

record_datestring(MM/DD/YYYY)

Date on which the record was generated

document_idstring

account_numberstring

Account Number as presented on the datasource

fatca_filing_requirementboolean

Used to show FATCA filing requirement value

voidboolean

Marks the form as void

correctedboolean

Marks the form as corrected

recipientobject

Details of the recipient

payerobject

Details of the payer

form_1099_divobject

form_1099_intobject

form_1099_miscobject

form_1099_oidobject

form_1099_Bobject(M1_FORM_1099_B Schema)

Representation of the 1099 B

M1_FORM_1098_MORTGAGE_INTEREST

The M1_FORM_1098_MORTGAGE_INTEREST schema represents the details of a 1098 tax form, which reports mortgage interest paid by a taxpayer. It includes information about the borrower, lender, and the amount of interest paid on the mortgage.

record_yearnumber(YYYY)

Year on which the record was generated

record_datestring(MM/DD/YYYY)

Date on which the record was generated

voidboolean

Marks the form as void

correctedboolean

Marks the form as corrected

recipientobject

Details of the recipient

payerobject

Details of the payer

account_numberstring

transactionsArray of objects(M1_FORM_1098 Schema)

totalsobject(M1_FORM_1098 Schema)

Representation of the 1098

M1_PROCEEDS_1099_B

This schema represents the details of a 1099-B tax form, which reports proceeds from broker and barter exchange transactions. It includes information about the seller, the broker, the type of securities sold, the sale amount, and any associated gains or losses for tax reporting. coverage details, premium amounts, beneficiaries, claims history, and insurer information.

as_of_datenumber

timestamp when this record was generated

account_numberstring

Account Number as presented on the datasource

recipientobject

Details of the recipient

payerobject

Details of the payer

transactionsArray of objects

List of transactions

totalsobject

Realized gain totals

MeasureOne API (3.0)

API Host and Protocols

API Keys and Access

Public Tokens

Generate Access Token

Request

Responses

Was this helpful?

Invalidate Access Token

Request

Responses

Was this helpful?

Versioning

Endpoints

Status Codes

Asynchronous Communication

Individuals

Data Requests

Data Sources

Items

Invitations

Experiences

Education

Income & Employment

Insurance

Tax Records

Webhook Events

Responding to Webhooks

Webhook Security

M1_ACADEMIC_RECORD

M1_DIGEST

M1_INCOME_EMPLOYMENT_RECORD

M1_INSURANCE_RECORD

M1_AUTO_INSURANCE_CLAIM_RECORD

M1_STUDENT_ID_RECORD

M1_W2_RECORD

M1_1099_RECORD

M1_FORM_1098_MORTGAGE_INTEREST

M1_PROCEEDS_1099_B