NAV Navbar

Overview

Welcome to the MeasureOne API! Our API provides a modern, developer-friendly, RESTful interface to the MeasureOne platform. Our focus is on simplicity, predictability, and consistency of behavior so that you, the developer, can easily integrate our capabilities into your application.

The MeasureOne platform provides three core functions:

  1. Transcript Data Extraction
  2. Data Standardization
  3. Data Analytics and Metrics

Our API provides endpoints and tools to integrate these capabilities into your application.

We have attempted to provide examples and detailed documentation that should enable you to be up and running quickly, but if you need additional help as you go through integration, please reach out to us at help@measureone.com.

API Access and Protocols

Sample Request

curl "https://api.measureone.com/v1/transcripts/new"
-H "Authorization: bearer <YOUR_API_KEY>"
-H "Content-Type: application/json"
-d "@sample_input.json"
-X POST

Authenticate your account by including your secret key in API requests. To get your testing and production keys, please reach out to us at sales@measureone.com.

Authentication to the API is performed via OAuth2.0 and any API requests without authentication will fail.

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 <YOUR_API_KEY>
Content-Type application/json

Hosting

MeasureOne provides two API environments:

Environment Description Host Name
Staging Full API capabilities with a set of test data api-stg.measureone.com
Production Full production capabilities against live data api.measureone.com


API keys are environment specific. Using Staging API keys to access the Production environment or vice versa will generate an authorization error.

Versioning

The current major version of the MeasureOne API is v1 and is passed in the URL to call MeasureOne endpoints as follows:

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

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

MeasureOne endpoints are used to integrate transcript files, transcript data and transcript analytics into your workflow.

Resource Endpoint Purpose
Transcripts /transcripts/new

/transcripts/upload

/transcripts/get_by_id

/transcripts/get_digest_by_id

/transcripts/get_files
Create a transcript

Upload data for a new transcript

Get data for a transcript

Get the M1-DIGEST for a transcript

Download transcript files
Analytics /analytics/meritscore

/analytics/gradscore
Get the MeritScore a transcript

Get the GradScore a transcript

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.

Get extracted transcript data

One of the key features of the MeasureOne platform is extracting and standardizing data from transcript files, to provide a digital record for easy integration into applications. MeasureOne supports a wide range of file formats, HTML, PDF, rich text documents, MS Word, images, etc.

The MeasureOne API makes it very easy to integrate this processing into any application pipeline. After submitting the document a unique ID for the processing document will be returned.

Once transcript processing has been completed, a webhook notification will be initiated. On receiving this notification, customers call /transcripts/get_by_id with the corresponding transcript ID to get all the raw and standardized values for the transcript.

Generate a MeritScore based on user-reported data

The MeritScore is a MeasureOne analytic that correlates credit performance to academic data. Depending on the location within the customer user experience, requesting the user to submit a full transcript may not be appropriate. An important example of such a use case would be a pre-approval stage at the top of a lending funnel. In these cases, using user-reported data to generate a score, which could later be verified by scoring the full transcript, is often the right design.

To address this use case, MeasureOne provides a "Digest" data type that enables customers to submit a summary of the transcript data, rather than the full transcript record itself. This summary is structured so as to be sufficient to generate a MeritScore.

The detailed flow to do this would then be as follows:

First, call /transcripts/new with source_data_type = "M1_DIGEST" and digest data fields in the source_data_value object. This creates a new transcript object and returns its transcript ID in the response.

Then, call /analytics/meritscore for that transcript ID, and you'll get the MeritScore in the response.

Transcripts

The Transcript resource is the core resource for the MeasureOne transcript object that represents a user's academic record for one program at a single institution.

The resource provides a CRUD-based interface to the transcript object.

Transcripts are created by submitting "source data", which is then extracted and/or normalized into MeasureOne's standard definitions. A full description is presented below.

Once a transcript is submitted, MeasureOne initiates the data extraction and standardization process. Following this processing, the transcript is available for the full set of API operations, including scoring and other standard or custom analytics.

Depending on the source data type, the processing may require asynchronous communication, i.e., the processing response will happen at some time after the submission request. In the event of asynchronous communication, once processing of a transcript is complete you'll get a notification through our webhook system. At that point you can get all the processed data for the transcript using /transcripts/get_by_id, get processed Digest fields for the transcript using /transcripts/get_digest_by_id or pass the transcript to MeasureOne's /analytics resources.

Each Transcript resource should refer to a single program within a single institution. A user's academic record that spans multiple programs across multiple institutions should be submitted in separate transactions so that each Transcript resource follows the single-program per institution guideline. Not doing so will most likely result in errors in the extraction and normalization process.

Type Definitions

Transcript Schema

The core Transcript object.

Attribute Type Description
id string Transcript ID, read-only
external_id string A customer generated unique identifier linked to the transcript. Customers may have multiple transcripts linked to the same external_id
school_unit_id string UnitID (as reported in the IPEDS database) of the school and campus that the transcript belongs to
source_data [object] An array of Source Data objects, with one object per source of academic data within the transcript
processing_status string
ENUM
Status of data extraction on the transcript, read only
Values: IN-PROGRESS, COMPLETED
raw object A JSON object in either MeasureOne's M1_TRANSCRIPT or M1_DIGEST schema, with raw data values for the transcript
standardized object A JSON object in either MeasureOne's M1_TRANSCRIPT or M1_DIGEST schema, with standardized values that conform to MeasureOne's standard definitions
pcodes object A JSON object with the same structure as either MeasureOne's M1_TRANSCRIPT or M1_DIGEST schema, with integer values for processing codes that provide further information about the standardized values
created_at integer Timestamp for when the transcript was created, read-only
updated_at integer Timestamp for when the transcript was last updated, read-only

Source Data Schema

The Source Data object contains the underlying data for the transcript record. The source data serves as the input to the transcript processing pipeline, i.e., it is the data that is extracted and/or standardized, populating the resulting M1-TRANSCRIPT object. Transcript records can be created with source data from a variety of types, ranging from documents containing unstructured academic data to JSON-based MeasureOne types.

The source data can either be included inline within the source data payload or can be designated by a reference to a remote document containing the data. In the event the source data is inline, the data should be provided in the source_data_value attribute. In the event the data is provided by reference, the reference information is designated in the source_data_reference attribute. These two attributes are exclusive within a Source Data object, i.e., each Source Data object must contain one or the other, but not both. A Source Data object with both value and reference attributes will result in an error.

Attribute Type Description
referrer string Label used to identify the source of the transcript data
source_data_type string
ENUM
Format of the source data
Values: M1_DIGEST, M1_TRANSCRIPT, OTHER
source_data_value object Object containing values for source data fields
source_data_reference object Reference information to a document specifying the source data

Source Data Reference Schema

Attribute Type Description
uri string URI scheme for a remote document. The supported schemes include the M1 scheme, an internal scheme used to refer to internal MeasureOne resources. See below for examples.
Supported Schemes: M1, HTTP, HTTPS, FTP, SFTP.
Format: scheme:[//authority]path[?query][#fragment]
media_type string Media type of the source data document
Supported Types: application/pdf, application/json, application/msword, image/jpeg, image/png, image/tiff, text/html, text/plain
http_method string HTTP/S request method
Values: GET, POST
http_headers object HTTP/S request header
http_body object HTTP/S request body
file_name string File name of document uploaded through the /transcripts/upload endpoint, read-only
created_at integer Timestamp for when document containing the source data was provided to MeasureOne, read-only

Source Data Types

MeasureOne supports transcript source data in a variety of formats as detailed in the table below.

Transcript Data Type Format Description
M1_DIGEST JSON
SCHEMA
A lean transcript format that includes select transcript data fields
M1_TRANSCRIPT JSON
SCHEMA
The MeasureOne full transcript payload
OTHER Use this type for all other transcript formats. A common use case for this type is for source data provided in a previously uploaded file containing data that is not M1_DIGEST or M1_TRANSCRIPT (e.g., a PDF or JPEG of a transcript). See below for examples.

M1-Digest Schema

Sample Payload

{ 
    "degree_type": "BACHELORS",
    "years_in_school": 2,
    "min_grade": "D",
    "cgpa": 3.3,
    "last_term_gpa": 3.5,
    "credits_earned": 65
}

The M1_DIGEST type provides a summary representation of a transcript record and includes key transcript attributes and statistics. The Digest format is structured to be sufficient for several MeasureOne transcript analytics, making it a useful format for creating and scoring trascripts based on user-reported data.

Attribute Type Description
degree_type string Granular level of study
Standardized Values: ASSOCIATE, BACHELORS, MASTERS, MASTERS-RESEARCH, DOCTORAL, CERTIFICATE, DIPLOMA, HIGH-SCHOOL-DIPLOMA, NON-DEGREE
years_in_school double Number of years that the student has been enrolled, including any breaks between enrollments
min_grade string Lowest grade earned on a course taken
Standardized Values: A, B, C, D, F
cgpa double Weighted CGPA, in the 0 to 4 scale, for the combination of courses attended at the transcript-issuing school
last_term_gpa double GPA, in the 0 to 4 scale, for the last term of attendance
credits_earned double Total credits earned including transferred credits, converted to a standard semester credit hour system


M1-Transcript Schema


Sample Payload

{
    "transcript_date": "04/13/2015",
    "school": "University of California, Berkeley",
    "school_id": "sch_Cfu77J69CqLVJNwvleOxrVbXbvn",
    "school_student_id": "10112ABCD",
    "enrollments": [
        {
            "school_enrollment_id": "TE13072058",
            "enrollment_status": "Graduated",
            "graduation_date": "05/27/2015",
            "college": "College of Science & Technology",
            "degrees": [
                {
                    "degree": "Bachelor of Science",
                    "degree_level": "Undergraduate",
                    "degree_type": "Bachelors",
                    "program": "Biology",
                    "order": 1,
                    "awarded": true
                },
                {
                    "degree": "Bachelor of Arts",
                    "degree_level": "Undergraduate",
                    "degree_type": "Bachelors",
                    "program": null;
                    "order": 2,
                    "awarded": false
                }
            ],
            "degree_awarded_date": "08/17/2015",
            "majors": [
                {
                    "major": "Biology",
                    "concentration": "Molecular Biology",
                    "department": "LifeScience",
                    "order": 1
                },
                {
                    "major": "Health Science",
                    "department": "LifeScience",
                    "order": 2
                }
            ],
            "minors": [
                {
                    "minor": "Musical Theatre",
                    "order": 1
                },
                {
                    "minor": "Animal Science",
                    "order": 2
                }
            ],
            "honors": [
                "Summa Cum Laude",
                "2013 Phi Theta Kappa (PTK) All-California Academic Team"
            ],
            "credit_system": "Credits",
            "credits": [
                {
                    "attempted": 121,
                    "earned": 101,
                    "gpa_credits": 101,
                    "quality_points": 379.76,
                    "source": "INSTITUTION"
                },
                {
                    "attempted": 22,
                    "earned": 22,
                    "gpa_credits": 0,
                    "quality_points": 0,
                    "source": "TRANSFER"
                },
                {
                    "attempted": 143,
                    "earned": 123,
                    "gpa_credits": 101,
                    "quality_points": 379.76,
                    "source": "TOTAL"
                }
            ],
            "institution_cgpa": 3.76,
            "transfer_cgpa": 0,
            "total_cgpa": 3.76,
            "last_attended_date": "06/17/2015",
            "terms": [
                {
                    "name": "FALL 2012",
                    "start_date": "10/01/2012",
                    "end_date": "12/31/2012",
                    "transfer": true,
                    "advanced_placement": true,
                    "in_progress": false,
                    "courses": [
                        {
                            "code": "BIOL 1100",
                            "name": "Prin of Biology I",
                            "course_start_date": "10/01/2012",
                            "course_end_date": "12/31/2012",
                            "credits": {
                                "attempted": 4,
                                "earned": 4,
                                "gpa_credits": 0,
                                "quality_points": 0
                            },
                            "grading": {
                                "pass_fail": false,
                                "grade_format": "Letter",
                                "value": "T",
                                "grade_points": 0
                            },
                            "retaken": "FALSE"
                        }
                    ]
                },
                {
                    "name": "Spring 2013",
                    "start_date": "04/01/2013",
                    "end_date": "06/30/2013",
                    "transfer": true,
                    "transferred_from_school": "Trident Tech College",
                    "advanced_placement": false,
                    "in_progress": false,
                    "courses": [
                        {
                            "code": "BIOL 210",
                            "name": "Cell Biology",
                            "course_start_date": "04/01/2013",
                            "course_end_date": "04/30/2013",
                            "credits": {
                                "attempted": 5,
                                "earned": 5,
                                "gpa_credits": 0,
                                "quality_points": 0
                            },
                            "grading": {
                                "pass_fail": false,
                                "grade_format": "Letter",
                                "value": "T",
                                "grade_points": 0
                            },
                            "retaken": "FALSE"
                        }
                    ]
                },
                {
                    "name": "Fall 2013",
                    "start_date": "10/01/2013",
                    "end_date": "12/31/2013",
                    "transfer": false,
                    "advanced_placement": false,
                    "in_progress": false,
                    "courses": [
                        {
                            "code": "BIOL 1236",
                            "name": "Microbiology I",
                            "course_start_date": "10/01/2013",
                            "course_end_date": "12/31/2013",
                            "credits": {
                                "attempted": 3,
                                "earned": 3,
                                "gpa_credits": 3,
                                "quality_points": 12
                            },
                            "grading": {
                                "pass_fail": false,
                                "grade_format": "Letter",
                                "value": "A",
                                "grade_points": 4
                            },
                            "retaken": "FALSE"
                        },
                        {
                            "code": "MUS 22121",
                            "name": "MUSIC AS A WORLD PHENOMENON",
                            "course_start_date": "12/01/2013",
                            "course_end_date": "12/31/2013",
                            "credits": {
                                "attempted": 3,
                                "earned": 3,
                                "gpa_credits": 3,
                                "quality_points": 9
                            },
                            "grading": {
                                "pass_fail": false,
                                "grade_format": "Letter",
                                "value": "B",
                                "grade_points": 3
                            },
                            "retaken": "FALSE"
                        }
                    ]
                }
            ]
        }
    ]
}

The M1_TRANSCRIPT type is MeasureOne's standard format for representing transcript data.

Attribute Type Description
transcript_date string Transcript issue date
school string Institution issuing transcript
school_student_id string Unique, school-provided student ID
enrollments [object] Array of Enrollment objects. An Enrollment object contains program level information and aggregated performance metrics. We currently support a single enrollment object. Multiple enrollment objects provided for a new transcript will result in an error.


Enrollment Object:

Attribute Type Description
school_enrollment_id string Unique, school-provided enrollment ID
enrollment_status string Enrollment status as of transcript date i.e. graduated, enrolled, withdrawn, terminated, probation, leave of absence, etc.
graduation_date string Graduation ceremony date (for graduated students only)
college string Sub-unit of the institution, such as a college within a university
campus string Campus name
degrees [object] Array of Degree objects. Each change in degree sought is listed as a separate object in the array.
degree_awarded_date string Degree awarded date (for graduated students only)
majors [object] Array of Major objects. Each declared major or change in declared major is listed as a separate object.
minors [object] Array of Minor objects. Each declared minor or change in declared minor is listed as a separate object.
honors [string] Academic honors or awards for current degree
Eg: Cum Laude, Summa Cum Laude, Magna Cum Laude
credit_system string
ENUM
Method of recording hours of study
Eg: Semester Credits, Quarter Credits, Units, Clock Hours
credits [object] Array of Credits objects. A Credits object contains information on total credits at the enrollment level i.e. aggregated across all terms and courses, with one object per source of credits i.e., INSTITUTION, TRANSFER and TOTAL.
institution_cgpa decimal CGPA for graded courses taken at the institution
transfer_cgpa decimal CGPA for transferred courses accepted by the institution
total_cgpa decimal Total CGPA for current program
last_attended_date string Student's last date of attendance
terms [object] Array of Term objects. A Term object contains information for each term on the transcript.


Degree Object:

Attribute Type Description
degree_level string Level of study
Standardized Values: UNDERGRADUATE, GRADUATE, HIGH-SCHOOL
degree_type string Granular level of study
Standardized Values: ASSOCIATE, BACHELORS, MASTERS, MASTERS-RESEARCH, FIRST-PROFESSIONAL, DOCTORAL, CERTIFICATE/DIPLOMA, HIGH-SCHOOL-DIPLOMA, NON-DEGREE
degree string Degree type and area of study
Eg: Bachelor's of Science, Master's of Arts, etc.
program string Degree type, broad area of study and subject specialization
Eg: BS in Microbiology
order integer Order in which degrees were sought (reverse chronological) where 1 = current/most recent, 2 = previous and so on
awarded boolean Indicates whether the degree is awarded or no


Credits Object:

Level of aggregation/granularity of attributes in this object depend on which object it is in, as follows:

If in Enrollment object, it is the sum of the metric within the enrollment/degree. If in Term object, it is the sum of the metric for the term. If in Course object, it represents the metric per course.

Attribute Type Description
attempted decimal Credits attemped
earned decimal Credits earned
gpa_credits decimal Credits attempted on courses that are included in the GPA calculation
quality_points decimal Numerator for GPA calculation
Formula: Credits Attempted x Grade Points Earned
source string Indicates whether credits are from current institution, transferred from a previous institution, or a total of the two


Major Object:

Attribute Type Description
major string Subject specialization for current program
concentration string Further specialization within major
department string Department offering the major
order integer Order of majors sought (reverse chronological) where, 1 = current/most recent, 2 = previous and so on


Minor Object:

Attribute Type Description
minor string Secondary specialization for current program
order integer Order of minors sought (reverse chronological) where, 1 = current/most recent, 2 = previous and so on


Term Object:

Post-Secondary Institution: Each enrolled term at the institution is a separate object.

High Schools: Each high school semester is one term object.

Transfer Terms: Courses taken at a previous institution and transferred in are listed as a separate term. There can be multiple transfer terms, one for each institution from which credits are transferred in.

Advanced Placement Terms: Advanced Placement or CLEP exams that count towards credit requirements are listed as a separate term.

Attribute Type Description
name string Name of term or semester
start_date string Term start date
end_date string Term end date
transfer boolean Whether the term represents credits transferred in from an earlier institution
transferred_from_school string For transfer terms, institution from which the credits were transferred
advanced_placement boolean Whether term represents credits earned via College Board Advanced Placement or CLEP exams
in_progress boolean Whether term is in progress as of transcript date
courses [object] Array of Course objects. Each course listed on the transcript is one object within the associated term.


Course Object:

Attribute Type Description
code string School-provided course code
name string School-provided course name
course_start_date string School provided course start date
course_end_date string School provided course end date
credits object Object contains credit-related information for each course
grading object Object contains grade-related information for each course
retaken string Indicates whether the course was retaken


Grading Object:

Attribute Type Description
pass_fail boolean Whether evaluated on pass-fail basis i.e. non graded
grade_format string
ENUM
Format of the grade i.e NUMERIC or LETTER
value string Grade earned on the course
grade_points decimal Quality points for grade, used in GPA calculation


Processing Codes

Processing codes are provided for each transcript attribute to provide further information about the standardized value. For more details on the MeasureOne standardization process, refer to the Standardization Guide or contact us on help@measureone.com

9xx OK

A 9xx processing code indicates that the standardized value is OK to use.

Status Code Description
901 Confirmed Value - A standardized attribute for which the standardized value matched the raw value
902 Standard Value Computed - A standardized attribute for which the standardized value was computed from raw transcript values
903 Non-standardized Attribute - Known non-standardized attribute. The attribute is an identifier, name or a similar field, that does not required standardization. Raw value copied to standardized value


800 Conditional OK

An 800 processing code indicates that MeasureOne used certain pre-defined assumptions to compute the standardized value.


7xx Raw Value Copied

A 7xx processing code indicates that MeasureOne does not have a standardized value for the attribute, and the raw value was copied into the standardized value.

Status Code Description
701 Insufficient Information - Known attribute for which there was insufficient information available on the transcript to provide a standardized value
702 Attributed Not Supported - Unsupported or unknown attribute

Transcript Endpoints

Create Transcript

Sample Request

curl "https://api.measureone.com/v1/transcripts/new"
-H "Authorization: bearer 536835b6-77ca-403d-88ef-b3c72580e070"
-H "Content-Type: application/json"
-d "@sample_input.json"
-X POST

POST /transcripts/new

The /transcripts/new endpoint creates a new transcript object for further processing or to generate analytics.

The request payload should include either a source_data_value object or a source_data_reference object.

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

If the data is in a document, upload it using the /transcripts/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.

sample_input.json with an Inline Source Data Payload

{
 "external_id": "ABCDECD",
 "source_data": [
   {
     "referrer": "USER",
     "source_data_type": "M1_DIGEST",
     "source_data_value": { 
                "degree_level": "UNDERGRADUATE",
                "degree_type": "BACHELORS",
                "years_in_school": 2.0,
                "min_grade": "D",
                "cgpa": 3.3,
                "last_term_gpa": 3.5,
                "credits_earned": 65.0
              }
   }
 ]
}


Request Payload: With Source Data Sent Inline

Attribute Type Required?
external_id string No
school_unit_id string No
source_data [object] Yes, include one source data object containing the complete academic record for the transcript. Multiple source data objects containing source_data_value attributes will result in an error.


source_data Object:

Attribute Type Required?
referrer string No
source_data_type string
ENUM
Yes, we currently support creating new transcripts with inline payloads in the M1_DIGEST format
source_data_value object Yes, in the M1_DIGEST schema

sample_input.json with a Reference to Files Uploaded Using /transcripts/upload

{
   "external_id": "ABCDECD",
   "school_unit_id": "420316",
   "source_data": [
      {
         "referrer": "USER",
         "source_data_type": "OTHER",
         "source_data_reference": {
            "uri": "m1://sdr_CaIGVqBRRpETI6fkCyUSpNHbHFo",
            "media_type": "application/pdf"
         }
      },
      {
         "referrer": "USER",
         "source_data_type": "OTHER",
         "source_data_reference": {
            "uri": "m1://sdr_DaKTVqBRRpEEI3fkCbUSpNHbkFm",
            "media_type": "application/pdf"
         }
      }
   ]
}

sample_input.json with a Reference to Files at a Remote Location

{
   "external_id": "ABCDECD",
   "school_unit_id": "420316",
   "source_data": [
      {
         "referrer": "USER",
         "source_data_type": "OTHER",
         "source_data_reference": {
            "uri": "sftp://john.doe:shah@examplesftp.net/path/to/directory/fileY.html",
            "media_type": "text/html"
         }
      },        
      {
         "referrer": "USER",
         "source_data_type": "OTHER",
         "source_data_reference": {
            "uri": "https://example.com/path/to/directory/file_name.extension?query_params1&query_param_2",
            "media_type": "text/html",
            "http_method": "POST",
            "http_headers": {
                "authorization" : "bearer 863268e5-82yr-927h-33ks-h6y82548d284",
                "customer_header": "customer_header_value"
            },
            "http_body": "ESCAPED%20STRING"
        }
      }
   ]
}



Request Payload: With a Reference to Source Data

Attribute Type Required?
external_id string No
school_unit_id string No
source_data [object] Yes, include one or more source data objects with references to documents that, when combined, provide a complete academic record for the transcript


source_data Object:

Attribute Type Required?
referrer string No
source_data_type string
ENUM
Yes, choose OTHER for all source data that isn't an M1_DIGEST or M1_TRANSCRIPT
source_data_reference object Yes


source_data_reference Object for Files Uploaded Using /transcripts/upload:

Attribute Type Required?
uri string Yes, include the m1 scheme uri returned in the response to /transcripts/upload
media_type string Yes


source_data_reference Object for Files Uploaded to a Remote Location:

Attribute Type Required?
uri string Yes
media_type string Yes
http_method string Required for HTTP/S requests
http_headers object Required for HTTP/S requests
http_body string Required for HTTP/S requests


Sample Response

{
   "id": "trc_Cevp4Jw9CIsEeNjpgAAjy2EZt3R",
   "processing_status": "IN_PROGRESS"
}


Response Payload

Transcript Object for the created transcript with the following attributes:

Attribute Type Description
id string ID of the created transcript
processing_status string COMPLETED for transcripts created with source data in inline payloads

IN-PROGRESS for transcripts created with source data in uploaded documents

Upload Transcript Data

Sample Request

curl "https://api.measureone.com/v1/transcripts/upload"
-H "Authorization: bearer 536835b6-77ca-403d-88ef-b3c72580e070"
-F "files[]=@/path/to/fileX.pdf"
-F "files[]=@/path/to/fileY.pdf"
-X POST

Sample Response

[
   {
       "uri": "m1://sdr_CaIGVqBRRpETI6fkCyUSpNHbHFo",
       "file_name": "fileX.pdf",
       "created_at": 1561613398393                 
   },
   {
       "uri": "m1://sdr_DaKTVqBRRpEEI3fkCbUSpNHbkFm",
       "file_name": "fileY.pdf",
       "created_at": 1566455776896
   }
]


POST /transcripts/upload

The /transcripts/upload endpoint is used to upload documents containing source data for a new transcript.


Request Payload

Attribute Type Required?
files [files] Yes
Supported File Types: DOC, HTML, JPG, JSON, PDF, PNG, TIFF, TXT


Response Payload

Array of Source Data Reference Objects, one object for each uploaded document. The uri returned in the response should be used to link the uploaded documents to a new transcript, as in the example here.

Get Transcript

Sample Request

curl "https://api.measureone.com/v1/transcripts/get_by_id"
-H "Authorization: bearer 536835b6-77ca-403d-88ef-b3c72580e070"
-H "Content-Type: application/json"
-d "@sample_input.json"
-X POST

sample_input.json

{
  "id": "trc_TSEne2SSjP3GvpVrs5HLol4xor2"  
}

Sample Response when source_data_type is not M1_DIGEST

{
  "id": "trc_TSEne2SSjP3GvpVrs5HLol4xor2",
  "external_id": "ABCDECD",
  "school_unit_id": 151351,
  "source_data": [
    {
      "referrer": "TLINK_SCHOOL",
      "source_data_type": "OTHER",
      "source_data_reference": {
        "uri": "m1://sdr_1KXGeat97YnOR8AHM4AZWYOAcog",
        "media_type": "application/pdf",
        "file_name": "fileX.pdf",
        "created_at": 1556781221243
      }
    }
  ],
  "raw": {
    "transcript_date": "2016-04-13",
    "school": "UCB",
    "school_student_id": "10112ABCD",
    "enrollments": [
      {
        "school_enrollment_id": "TE13072058",
        "enrollment_status": "PERM OUT - Graduate",
        "graduation_date": "2015/05/27",
        "college": "College of Science & Technology",
        "degrees": [
            {
                "degree": "BS",
                "degree_level": null,
                "degree_type": null,
                "program": "Biology BS",
                "order": 1,
                "awarded": true
            },
            {
                "degree": "Bach. of Arts",
                "degree_level": null,
                "degree_type": null,
                "program": null,
                "order": 2,
                "awarded": false
            }
        ],
        "degree_awarded_date": "2015/08/17",
        "majors": [
            {
                "major": "Biology",
                "concentration": "Molecular Biology",
                "department": "LifeScience (Biology)",
                "order": 1
            },
            {
                "major": "Health Science",
                "department": "LifeScience",
                "order": 2
            }
        ],
        "minors": [
            {
                "minor": "Musical Theatre",
                "order": 1
            },
            {
                "minor": "Animal Science",
                "order": 2
            }
        ],
        "honors": [
                "Summa Cum Laude",
                "2013 Phi Theta Kappa (PTK) All-California Academic Team"
         ],
        "credit_system": "Credits",
        "credits": [
            {
                "attempted": 121,
                "earned": 101,
                "gpa_credits": 101,
                "quality_points": 9494,
                "source": "INSTITUTION"
            },
            {
                "attempted": null,
                "earned": 22,
                "gpa_credits": 0,
                "quality_points": 0,
                "source": "TRANSFER"
            },
            {
                "attempted": 121,
                "earned": 123,
                "gpa_credits": 101,
                "quality_points": 9494,
                "source": "TOTAL"
            }
        ],
        "institution_cgpa": 94,
        "transfer_cgpa": 0,
        "total_cgpa": 94,
        "last_attended_date": "2015/06/17",
        "terms": [
            {
                "name": "2012 Fall",
                "start_date": null,
                "end_date": null,
                "transfer": true,
                "advanced_placement": true,
                "in_progress": null,
                "courses": [
                    {
                        "code": "BIOL 1100",
                        "name": "Prin of Biology I",
                        "course_start_date": null,
                        "course_end_date": null,
                        "credits": {
                            "attempted": 4,
                            "earned": 4,
                            "gpa_credits": null,
                            "quality_points": 0
                        },
                        "grading": {
                            "pass_fail": null,
                            "grade_format": "Letter",
                            "value": "T",
                            "grade_points": null
                        },
                        "retaken": null
                    }
                ]
            },
            {
                "name": "2013 Spring",
                "start_date": null,
                "end_date": null,
                "transfer": true,
                "transferred_from_school": "Trident Tech College",
                "advanced_placement": null,
                "in_progress": null,
                "courses": [
                    {
                        "code": "BIOL 210",
                        "name": "Cell Biology",
                        "course_start_date": "04/01/2013",
                        "course_end_date": "04/31/2013",
                        "credits": {
                            "attempted": null,
                            "earned": 5,
                            "gpa_credits": null,
                            "quality_points": 0
                        },
                        "grading": {
                            "pass_fail": null,
                            "grade_format": "Letter",
                            "value": "T",
                            "grade_points": null
                        },
                        "retaken": null
                    }
                ]
            },
            {
                "name": "2013 Fall",
                "start_date": null,
                "end_date": null,
                "transfer": false,
                "advanced_placement": null,
                "in_progress": null,
                "courses": [
                    {
                        "code": "BIOL 1236",
                        "name": "Microbiology I",
                        "course_start_date": null,
                        "course_end_date": null,
                        "credits": {
                            "attempted": 3,
                            "earned": null,
                            "gpa_credits": 3,
                            "quality_points": 285
                        },
                        "grading": {
                            "pass_fail": null,
                            "grade_format": "Numeric",
                            "value": "95",
                            "grade_points": null
                        },
                        "retaken": null
                    },
                    {
                        "code": "MUS 22121",
                        "name": "MUSIC AS A WORLD PHENOMENON",
                        "course_start_date": "12/01/2013",
                        "course_end_date": "12/31/2013",
                        "credits": {
                            "attempted": 3,
                            "earned": null,
                            "gpa_credits": 3,
                            "quality_points": 255
                        },
                        "grading": {
                            "pass_fail": null,
                            "grade_format": "Numeric",
                            "value": "85",
                            "grade_points": null
                        },
                        "retaken": null
                    }
                ]
            }
        ]
      }
    ]
  },
  "standardized": {
    "transcript_date": "04/13/2016",
    "school": "University of California, Berkeley",
    "school_student_id": "10112ABCD",
    "enrollments": [
      {
        "school_enrollment_id": "TE13072058",
        "enrollment_status": "Graduated",
        "graduation_date": "05/27/2015",
        "college": "College of Science & Technology",
        "degrees": [
            {
                "degree": "Bachelor of Science",
                "degree_level": "Undergraduate",
                "degree_type": "Bachelors",
                "program": "Biology",
                "order": 1,
                "awarded": true
            },
            {
                "degree": "Bachelor of Arts",
                "degree_level": "Undergraduate",
                "degree_type": "Bachelors",
                "program": null,
                "order": 2,
                "awarded": false
            }
        ],
        "degree_awarded_date": "08/17/2015",
        "majors": [
            {
                "major": "Biology",
                "concentration": "Molecular Biology",
                "department": "LifeScience (Biology)",
                "order": 1
            },
            {
                "major": "Health Science",
                "department": "LifeScience",
                "order": 2
            }
        ],
        "minors": [
            {
                "minor": "Musical Theatre",
                "order": 1
            },
            {
                "minor": "Animal Science",
                "order": 2
            }
        ],
        "honors": [
                "Summa Cum Laude",
                "2013 Phi Theta Kappa (PTK) All-California Academic Team"
         ],
        "credit_system": "Credits",
        "credits": [
            {
                "attempted": 121,
                "earned": 101,
                "gpa_credits": 101,
                "quality_points": 379.76,
                "source": "INSTITUTION"
            },
            {
                "attempted": 0,
                "earned": 22,
                "gpa_credits": 0,
                "quality_points": 0,
                "source": "TRANSFER"
            },
            {
                "attempted": 121,
                "earned": 123,
                "gpa_credits": 101,
                "quality_points": 379.76,
                "source": "TOTAL"
            }
        ],
        "institution_cgpa": 3.76,
        "transfer_cgpa": 0,
        "total_cgpa": 3.76,
        "last_attended_date": "06/17/2015",
        "terms": [
            {
                "name": "FALL 2012",
                "start_date": "10/01/2012",
                "end_date": "12/31/2012",
                "transfer": true,
                "advanced_placement": true,
                "in_progress": false,
                "courses": [
                    {
                        "code": "BIOL 1100",
                        "name": "Prin of Biology I",
                        "course_start_date": null,
                        "course_end_date": null,
                        "credits": {
                            "attempted": 4,
                            "earned": 4,
                            "gpa_credits": 0,
                            "quality_points": 0
                        },
                        "grading": {
                            "pass_fail": false,
                            "grade_format": "Letter",
                            "value": "Transfer",
                            "grade_points": 0
                        },
                        "retaken": "FALSE"
                    }
                ]
            },
            {
                "name": "SPRING 2013",
                "start_date": "04/01/2013",
                "end_date": "06/30/2013",
                "transfer": true,
                "transferred_from_school": "Trident Tech College",
                "advanced_placement": false,
                "in_progress": false,
                "courses": [
                    {
                        "code": "BIOL 210",
                        "name": "Cell Biology",
                        "course_start_date": "04/01/2013",
                            "course_end_date": "04/30/2013",
                        "credits": {
                            "attempted": 5,
                            "earned": 5,
                            "gpa_credits": 0,
                            "quality_points": 0
                        },
                        "grading": {
                            "pass_fail": false,
                            "grade_format": "Letter",
                            "value": "Transfer",
                            "grade_points": 0
                        },
                        "retaken": "FALSE"
                    }
                ]
            },
            {
                "name": "FALL 2013",
                "start_date": "10/01/2013",
                "end_date": "12/31/2013",
                "transfer": false,
                "advanced_placement": false,
                "in_progress": false,
                "courses": [
                    {
                        "code": "BIOL 1236",
                        "name": "Microbiology I",
                        "course_start_date": null,
                            "course_end_date": null,
                        "credits": {
                            "attempted": 3,
                            "earned": 3,
                            "gpa_credits": 3,
                            "quality_points": 12
                        },
                        "grading": {
                            "pass_fail": false,
                            "grade_format": "Letter",
                            "value": "A",
                            "grade_points": 4
                        },
                        "retaken": "FALSE"
                    },
                    {
                        "code": "MUS 22121",
                        "name": "MUSIC AS A WORLD PHENOMENON",
                        "course_start_date": "12/01/2013",
                            "course_end_date": "12/31/2013",
                        "credits": {
                            "attempted": 3,
                            "earned": 3,
                            "gpa_credits": 3,
                            "quality_points": 9
                        },
                        "grading": {
                            "pass_fail": false,
                            "grade_format": "Letter",
                            "value": "B",
                            "grade_points": 3
                        },
                        "retaken": "FALSE"
                    }
                ]
            }
        ]
      }
    ]
  },
  "pcodes": {
    "transcript_date": 902,
    "school": 902,
    "school_student_id": 903,
    "enrollments": [
      {
        "school_enrollment_id": 903,
        "enrollment_status": 902,
        "graduation_date": 902,
        "college": 903,
        "degrees": [
            {
                "degree": 902,
                "degree_level": 902,
                "degree_type": 902,
                "program": 702,
                "order": 901,
                "awarded": 901
            },
            {
                "degree": 902,
                "degree_level": 902,
                "degree_type": 902,

                "order": 901,
                "awarded": 901
            }
        ],
        "degree_awarded_date": 902,
        "majors": [
            {
                "major": 901,
                "concentration": 702,
                "department": 902,
                "order": 901
            },
            {
                "major": 901,
                "department": 901,
                "order": 901
            }
        ],
        "minors": [
            {
                "minor": 901,
                "order": 901
            },
            {
                "minor": 901,
                "order": 901
            }
        ],
        "honors": [
                901,
                903
         ],
        "credit_system": 901,
        "credits": [
            {
                "attempted": 901,
                "earned": 901,
                "gpa_credits": 901,
                "quality_points": 902,
                "source": 901
            },
            {
                "attempted": 901,
                "earned": 901,
                "gpa_credits": 901,
                "quality_points": 901,
                "source": 901
            },
            {
                "attempted": 901,
                "earned": 901,
                "gpa_credits": 901,
                "quality_points": 902,
                "source": 901
            }
        ],
        "institution_cgpa": 902,
        "transfer_cgpa": 901,
        "total_cgpa": 902,
        "last_attended_date": 902,
        "terms": [
            {
                "name": 902,
                "start_date": 902,
                "end_date": 902,
                "transfer": 901,
                "advanced_placement": 901,
                "in_progress": 902,
                "courses": [
                    {
                        "code": 903,
                        "name": 903,
                        "course_start_date": 701,
                        "course_end_date": 701,
                        "credits": {
                            "attempted": 901,
                            "earned": 901,
                            "gpa_credits": 902,
                            "quality_points": 901
                        },
                        "grading": {
                            "pass_fail": 902,
                            "grade_format": 901,
                            "value": 902,
                            "grade_points": 902
                        },
                        "retaken": 902
                    }
                ]
            },
            {
                "name": 902,
                "start_date": 902,
                "end_date": 902,
                "transfer": 901,
                "transferred_from_school": 901,
                "advanced_placement": 902,
                "in_progress": 902,
                "courses": [
                    {
                        "code": 903,
                        "name": 903,
                        "course_start_date": 901,
                        "course_end_date": 901,
                        "credits": {
                            "attempted": 902,
                            "earned": 901,
                            "gpa_credits": 902,
                            "quality_points": 901
                        },
                        "grading": {
                            "pass_fail": 902,
                            "grade_format": 901,
                            "value": 902,
                            "grade_points": 902
                        },
                        "retaken": 902
                    }
                ]
            },
            {
                "name": 902,
                "start_date": 902,
                "end_date": 902,
                "transfer": 901,
                "advanced_placement": 902,
                "in_progress": 902,
                "courses": [
                    {
                        "code": 903,
                        "name": 903,
                        "course_start_date": 701,
                        "course_end_date": 701,
                        "credits": {
                            "attempted": 901,
                            "earned": 902,
                            "gpa_credits": 901,
                            "quality_points": 902
                        },
                        "grading": {
                            "pass_fail": 902,
                            "grade_format": 902,
                            "value": 902,
                            "grade_points": 902
                        },
                        "retaken": 902
                    },
                    {
                        "code": 903,
                        "name": 903,
                        "course_start_date": 901,
                        "course_end_date": 901,
                        "credits": {
                            "attempted": 901,
                            "earned": 902,
                            "gpa_credits": 901,
                            "quality_points": 902
                        },
                        "grading": {
                            "pass_fail": 902,
                            "grade_format": 902,
                            "value": 902,
                            "grade_points": 902
                        },
                        "retaken": 902
                    }
                ]
            }
        ]
      }
    ]
  },
  "processing_status": "COMPLETED",
  "created_at": 1556781225343,
  "updated_at": 1556781257964
}




Sample Response when source_data_type = "M1_DIGEST"

{
 "id": "trc_TSEne2SSjP3GvpVrs5HLol4xor2",
 "external_id": "ABCDECD",
 "source_data": [
   {
     "referrer": "USER",
     "source_data_type": "M1_DIGEST",
     "source_data_value": { 
                "degree_type": "BACHELORS",
                "years_in_school": 2,
                "min_grade": "D",
                "cgpa": 3.3,
                "last_term_gpa": 3.5,
                "credits_earned": 65
              }
   }
 ],
 "raw": {
    "degree_type": "BACHELORS",
    "years_in_school": 2,
    "min_grade": "D",
    "cgpa": 3.3,
    "last_term_gpa": 3.5,
    "credits_earned": 65
  },
  "standardized": {
    "degree_type": "BACHELORS",
    "years_in_school": 2,
    "min_grade": "D",
    "cgpa": 3.3,
    "last_term_gpa": 3.5,
    "credits_earned": 65
  },
  "pcodes": {
    "degree_type": 701,
    "years_in_school": 701,
    "min_grade": 701,
    "cgpa": 701,
    "last_term_gpa": 701,
    "credits_earned": 701
  }, 
 "processing_status": "COMPLETED",
 "created_at": 1556781225343,
 "updated_at": 1556781257964
}

POST /transcripts/get_by_id

The /transcripts/get_by_id endpoint allows developers to retrieve transcript metadata and transcript data fields. The endpoint can be used once the processing_status for a transcript is COMPLETE. It will return raw values, standardized values and processing codes for all attributes in the M1_TRANSCRIPT schema.

Request Payload

Attribute Type Required?
id string Yes
include_raw boolean No
DEFAULT: true
include_standardized boolean No
DEFAULT: true
include_pcodes boolean No
DEFAULT: true


Response Payload

Transcript Object for the created transcript, in which the raw and standardized objects are in the M1_TRANSCRIPT schema. pcodes follows the same structure as the M1_TRANSCRIPT schema, with integer values for each attribute.

Please note that for transcripts created with source data in the M1-DIGEST type, the raw object has the customer submitted source data values. No attempt will be made to standardize these values.

Get Digest

Sample Request

curl "https://api.measureone.com/v1/transcripts/get_digest_by_id"
-H "Authorization: bearer 536835b6-77ca-403d-88ef-b3c72580e070"
-H "Content-Type: application/json"
-d "@sample_input.json"
-X POST

sample_input.json

{
  "id": "trc_TSEne2SSjP3GvpVrs5HLol4xor2"  
}

Sample Response when source_data_type is not M1_DIGEST

{
  "id": "trc_TSEne2SSjP3GvpVrs5HLol4xor2",
  "external_id": "ABCDECD",
  "school_unit_id": 151351,
  "source_data": [
    {
      "referrer": "M1_PORTAL_SCHOOL",
      "source_data_type": "OTHER",
      "source_data_reference": {
        "uri": "m1://sdr_1KXGeat97YnOR8AHM4AZWYOAcog",
        "media_type" = "application/pdf",
        "file_name": "fileX.pdf",
        "created_at": 1556781221243
      }
    }
  ],
  "raw": {
    "degree_type": null,
    "years_in_school": null,
    "min_grade": "65",
    "cgpa": 94,
    "last_term_gpa": 91,
    "credits_earned": 123
  },
  "standardized": {
    "degree_type": "BACHELORS",
    "years_in_school": 2,
    "min_grade": "D",
    "cgpa": 3.76,
    "last_term_gpa": 3.52,
    "credits_earned": 123
  },
  "pcodes": {
    "degree_type": 902,
    "years_in_school": 902,
    "min_grade": 902,
    "cgpa": 902,
    "last_term_gpa": 902,
    "credits_earned": 901
  },
  "processing_status": "COMPLETED",
  "created_at": 1556781225343,
  "updated_at": 1556781257964
}

POST /transcripts/get_digest_by_id

The /transcripts/get_digest_by_id endpoint allows developers to retrieve transcript metadata and Digest fields. The endpoint can be used once a the processing_status for a transcript is COMPLETE. It will return raw values, standardized values and processing codes for all attributes in the M1_DIGEST schema.

Request Payload

Attribute Type Required?
id string Yes
include_raw boolean No
DEFAULT: true
include_standardized boolean No
DEFAULT: true
include_pcodes boolean No
DEFAULT: true


Response Payload

Transcript Object for the created transcript, in which the raw and standardized objects are in the M1_DIGEST schema. pcodes follows the same structure as the M1_DIGEST schema, with integer values for each attribute.

Please note that for transcripts created with source data in the M1-DIGEST type, the raw object has the customer submitted source data values. No attempt will be made to standardize these values.

Get Transcript Files

Sample Request

curl "https://api.measureone.com/v1/transcripts/get_files?transcript_id=trc_CV39Blnq2MOHEE2eMQ9C9Cb2LOI" 
-H "Authorization: bearer 536835b6-77ca-403d-88ef-b3c72580e070" 
-X GET --output transcripts.zip

Sample Success Response

File: transcripts.zip

Sample Error Response

{
  "error_code": "INVALID_CREDENTIALS",
  "http_code": 401,
  "request_id": "req_CRT8vDjmSiAynRPIK29CN38d3Pe",
  "error_message": "Unauthorized for the requested operation"
}

GET /transcripts/get_files

The /transcripts/get_files endpoint allows developers to download source data files associated with a transcript. The endpoint returns a ZIP file containing one file (in its original format) per data source for the transcript. This is available only when source data was provided in a document and not an inline payload.

Request Payload

Attribute Type Required?
id string Yes


Response Payload

When the HTTP response code is 200, the response is of type application/zip and returns a ZIP file containing source data files for the transcript. File name will be the transcript ID.

For all other response codes, the response is of type application/json and returns the standard Error object.

Analytics

The resource that provides MeasureOne scores and advance analytics on transcripts.

Send a transcript to an /analytics endpoint when its processing_status = "COMPLETED".

/analytics/meritscore returns MeasureOne's MeritScore for a transcript, a score indicative of default risk.

/analytics/gradscore returns MeasureOne's GradScore for a transcript, a score indicative of graduation likelihood.

MeritScore

Sample Request

curl "https://api.measureone.com/v1/analytics/meritscore"
-H "Authorization: bearer 536835b6-77ca-403d-88ef-b3c72580e070"
-H "Content-Type: application/json"
-d "@sample_input.json"
-X POST

sample_input.json

{
  "transcripts": [
    {
      "id": "trc_TSEne2SSjP3GvpVrs5HLol4xor2"
    }
  ]
}

Sample Response

{
  "merit_score": 698,
  "aa_code_1": 3,
  "aa_code_2": 1,
  "aa_code_3": 4,
  "version": "v1.2"
}

POST /analytics/meritscore

Generate MeasureOne's MeritScore on a transcript.

The MeritScore can be computed on any transcript that has validated, non-null values for required M1_DIGEST fields and processing_status = "COMPLETED".

M1_DIGEST Attribute Required?
degree_type Yes
years_in_school Yes
min_grade Yes
cgpa Yes
last_term_gpa Yes
credits_earned Yes


Request Parameters

Attribute Type Description
transcripts [string] An array of transcript IDs to be scored

NOTE: MeasureOne currently supports scoring single transcripts and will return an error if more than one id is included in the request
id string MeasureOne generated transcript ID


Response Parameters

Attribute Type Description
merit_score decimal MeasureOne's MeritScore for the requested transcript
aa_code_1 integer First adverse action code that can be used for decline decisions
aa_code_2 integer Second adverse action code that can be used for decline decisions
aa_code_3 integer Third adverse action code that can be used for decline decisions


Adverse Action Reasons

Adverse Action Code Adverse Action Reason
1 Overall academic performance could be improved
2 Academic performance has concerning trend
3 Meaningful progress has not been made toward successful completion of studies
4 Academic performance is not steady and stable

GradScore

Sample Request

curl "https://api.measureone.com/v1/analytics/gradscore"
-H "Authorization: bearer 536835b6-77ca-403d-88ef-b3c72580e070"
-H "Content-Type: application/json"
-d "@sample_input.json"
-X POST

sample_input.json

{
  "transcripts": [
    {
      "id": "trc_TSEne2SSjP3GvpVrs5HLol4xor2"
    }
  ]
}

Sample Response

{
  "grad_score": 652,
  "aa_code_1": 2,
  "aa_code_2": 3,
  "aa_code_3": 1,
  "version": "v1.1"
}

POST /analytics/gradscore

Generate MeasureOne's GradScore on a transcript.

The GradScore can be computed on any transcript that has validated, non-null values for required M1_DIGEST fields and processing_status = "COMPLETED".

M1_DIGEST Attribute Required?
degree_type yes
years_in_school yes
min_grade yes
cgpa yes
last_term_gpa yes
credits_earned yes


Request Parameters

Attribute Type Description
transcripts [string] An array of transcript IDs to be scored
NOTE: MeasureOne currently supports scoring single transcripts and will return an error if more than one id is included in the request
id string MeasureOne generated transcript ID


Response Parameters

Attribute Data Type Description
grad_score decimal MeasureOne's GradScore for the requested transcript
aa_code_1 integer First adverse action code that can be used for decline decisions
aa_code_2 integer Second adverse action code that can be used for decline decisions
aa_code_3 integer Third adverse action code that can be used for decline decisions


Adverse Action Reasons

Adverse Action Code Adverse Action Reason
1 Overall academic performance could be improved
2 Academic performance has concerning trend
3 Meaningful progress has not been made toward successful completion of studies
4 Academic performance is not steady and stable

Webhooks

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.

Webhook Security

MeasureOne's webhook supports OAuth 2.0 and Basic Auth for authorization. The API key configured during the setup of the webhook in the customer onboarding process, will be present in the Authorization header. In addition, the User-Agent for the requests will have the prefix M1-Webhook/.

Webhook Payload

Sample Webhook Payload

{
   "transcript_id": "trc_TSEne2SSjP3GvpVrs5HLol4xor2",
   "external_id": "ABCDECD",
   "event": "transcript.created"
}
Attribute Type Description
transcript_id string MeasureOne generated transcript ID
external_id string A customer generated unique identifier linked to the transcript. Customers may have multiple transcripts linked to the same external_id.
event
DEFINITIONS
string
ENUM
Transcript events that trigger webhook notifications

Webhook Events

The current supported notification events are in the following table:

Event Description
transcript.created The transcript object has been created and is pending processing to extract data
"processing_status": "PENDING"
transcript.processed The transcript object has been processed and data is available to be pulled
"processing_status": "COMPLETED"

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.

Status Codes

Sample Error Object

{
  "error_code": "INVALID_CREDENTIALS",
  "http_code": 401,
  "request_id": "req_CRT8vDjmSiAynRPIK29CN38d3Pe",
  "error_message": "Unauthorized to perform the requested operation"
}

MeasureOne uses standard HTTP response codes for success and failure notifications.


2xx Success

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

Status Code Description
200 OK - The request is successful


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 is most commonly the result of failing to include all required fields or failing validation on the object.
401 Unauthorized - Authentication with the API failed. Make sure you are using the correct API key.
403 Forbidden - You do not have permission to access the requested resource.
404 Not Found - The requested resource could not be found.
409 Conflict - The request failed due to a resource conflict. This can occur if you attempt to delete a resource that is needed for the functioning of other resources.


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.