API Guide

Overview

Introduction

Houghton Mifflin Harcourt's (HMH) Developer Portal is an HMH Labs initiative to expose the HMH APIs to others, including customers and third party developers. This creates an exciting opportunity for developers to build solutions that are compatible with those that our customers already know and trust. Initially, the APIs will connect you with a sandbox environment and, with approval, to the rich and diverse world of Houghton Mifflin Harcourt's offerings. Ultimately, our goal is to provide greater opportunities for interoperability and a seamless user experience for teachers, students, and parents..

The release of v3 in January 2016 marked another milestone in the continuous improvement of the HMH Developer Portal. Enhancing the developer experience by introducing a simple design pattern was a driving force in v3 development. v3 of the API program introduces updates to the Identity, Document, Tag, and Content endpoints.

The Latest Improvements - v4 Released May 2016

Building off of the v3 improvements, the v4 release in May 2016 further refines HMH's APIs. This release includes a change in the sandbox endpoint from http://sandbox.api.hmhco.com to http://sandbox.graph.hmhco.com. It also introduces create, update and delete functionalities to the Document and Tag APIs. In order to prevent overlap between developer teams, a /developer call has been added to allow developers to get a unique, clean set of demo data to work with in the sandbox environment. Given some new ability to create, update and delete, this is especially recommended for developers working with Documents and Tags.

The Assignment API was reintroduced in June 2016. It is located in the v4/Rosters section of the Swagger documentation.

Be sure to view the "Release Notes" section below for further details.

RESTful APIs

HMH's APIs employ the guidelines and methods of REST (representational state transfer). Perhaps you have heard of REST, and may even have some experience with RESTful practices..

RESTful APIs, those using REST methods, define a specific set of request URLs that applications can use to retrieve and modify information. Each request is issued via a specific request method, typically POST, GET, PUT, and DELETE. While these methods are used for various purposes in web applications, for REST interfaces, they are commonly associated with the operations Create, Read, Update, and Delete (CRUD).


cURL

Applications can use a variety of means to invoke specific URLs. From a script or from the command line, a tool called cURL permits passing requests to servers and returning the response.

For example, to get information about a roster, the Request URL and the start of the cURL would look like this.

The cURL includes additional headers that identify the API Key, Authorization, client_id, and the Content-Type (for PUT and POST calls). In the Resources section, view the Swagger Documentation for details, sample Request URLs, and sample cURLs. The Swagger Documentation also provides sample responses.

To get started, read on to learn how to create an application. This will generate an API key and client_id for you. These steps are necessary to obtain a SIF token, an access_token for authorization, using the Demo Data available.

Getting Started in Sandbox

Sandbox Quick Start

  1. If you have not created an account already, do so at https://developer.hmhco.com/signup. Alternately, you can navigate to the sign up page by clicking on the "Build with Us" button or by selecting Sign In, then Sign Up.
  2. Complete the Sign Up form.
  3. On successful signup, an email with account activation details is sent to you.The link in the email will activate your account and allow you to log in to the HMH Developer Portal.

STEP 1: Create an Application

  1. Once in the portal, you must create an application. An application is directly coupled to your service plan (selected in Step 3) that HMH exposes, and in that sense represents a contract.
  2. In the top navigation bar, click on “Applications”. Then click “Create new application.”
  3. Complete the form (shown below) and click "Create Application".
    1. Plan: HMH application plan as mentioned in the above note. By default, all new applications start with the Basic plan. A Content plan is also available by request for developers seeking additional samples of content. See the section on the Content API for more information.
    2. Name: Enter the name of your application.
    3. Description: Enter the description of your application.
    4. Redirect URIs: At least one redirect URI must be set. The Redirect URI is where the response from a successful Open ID Connect Authentication is sent, such as http://www.yourcallback.com. For example, once a user authorizes your app, a code is sent to your redirect URI. The code can then be exchanged for an access token.
  4. After inputting this basic info, an application is created for you. An API Key or User Key is also created. This is the Vnd-HMH-Api-key value used in the header of each request. To find this information click “Applications” in the top navigation bar and then select the appropriate application.
  5. Don't see a Client Id or Client Secret? Refresh your page. These values are used during Open ID Connect Authentication.

With the application successfully created, developers are now ready to begin authenticating their users and start using HMH APIs.


STEP 2: How to Authorize in the Sandbox

In the past, we pointed users to the Sample Token API to get a SIF Token. This endpoint was for sandbox use only. In order to more consistently match the requirements of the production environment, we are in the process of removing the Sample Token API in favor of sandbox Open ID Connect Authorization.

Sample App: Durin's Door

We have created a sample node express application, Durin’s Door, to demonstrate how OIDC Authorization interacts with HMH APIs. You can find the information here:https://github.com/hmhco/durinsdoor/tree/api-release .

You will still need the following parameters:

  • Vnd-HMH-Api-Key:This is provided in your application. It will auto-fill in the swagger documentation.
  • client_id: This is provided in your application. To access it, log into the Developer Portal and go to Applications. Click on the app name and locate it below the Redirect URI. If it does not appear, Refresh your Screen. NOTE: If you copy and paste the client_id from the application, be sure to remove any preceding spaces that are inserted.
  • username: This is the username of a Staff person or Student. To start, use gandalf.
  • password: The password of the Student or Staff person account. It will always be "password" without the quotes.

Additionally, follow this authentication flow for Durin’s Door here: https://github.com/hmhco/durinsdoor/blob/api-release/auth_flow.md. This flow will enable you to get your token.

Once OIDC has been built into your application, the user experience will be similar to this example:

  1. The user selects their platform (either HMOF or TC) and enters their HMH information.
  2. Then the user clicks on the yellow arrow to complete the log in and continue to the application.
  3. The user approves the application.

Once you have set up the authorization flow through OIDC, you can use the demo data users or you can create a set of users on your own.

Swagger Documentation

Now that you have successfully been granted an access token through the authorization flow above, you’re ready to build with our APIs. The Swagger Documentation listed under the Resources section of this site, gives valuable details about the sandbox endpoints, call formats, and expected response results.

If desired, it is possible to copy and paste your access_token at the top of the Swagger documentation page for easy experimentation with the APIs. Just click Set Authorization to try the calls within the swagger documentation online. This will auto-fill the Authorization parameter with the token on this page.

Be sure to reset the token if you change users, or get a new token after expiration.


STEP 3: Create a Sample Set of Demo Data

NEW in v4

Next, developers have the option to create their own set of demo data for use with their application. This prevents overlap between developers and teams working with documents, tags, and other editable user data. Alternatively, developers can use the available Demo Data.

  1. Within the Swagger Documentation or by using a cURL in your Terminal, developers should make a call to http://sandbox.graph.hmhco.com/v4/developer.
  2. In the Swagger Documentation, make sure you have a token set up from the OIDC authorization flow.
  3. Select v4/developer.
  4. Enter the required parameters.
  5. Click Try it Out!
  6. Check the response! These are unique users for you to use as you build, test, and demonstrate how your app uses HMH APIs.
  7. 7. Now that you have unique users, you can obtain a SIF token for any staff or students using the given "user_name" field in the Token API. The password is password for demo users.

Build With Us

Now that you've taken all the steps to get started, you're ready to build with HMH's APIs. While we’re taking steps to ensure this Sandbox environment is as close to production as possible, we also are seeking to make the sandbox easy for you to get started and prototype how your application can use our APIs.

We encourage you to read through the following sections to understand the process and steps required to access production, as well as some of the differences that still exist between sandbox and production.

How is production different from the sandbox?

  • Production information is protected by a PII filter. Learn more about the PII filter in Getting Ready for Production.
  • Production is on v1 and has a different endpoint than the sandbox.
  • In production, user authorization takes place through OIDC. To implement this in the sandbox version of this see STEP 2: How to Authorize in the Sandbox . Please note that the sample token endpoint for authorization is for sandbox used only and will be phased out by December 31, 2016.
  • Most developers accessing the production APIs should plan to participate in HMH Marketplace.
  • Web applications that charge a fee (cost > $0.00) are expected to implement LTI link launch and provide LTI launch information.

Need more information?

Continue to use this guide in conjunction with the Swagger Documentation to answer your questions about using our APIs. When you are ready be sure to review the steps outlined in this guide on bringing your application into production and joining HMH Marketplace.

Check out these links to learn more about our API program and the new HMH Marketplace:

  • Forum: Post questions and find answers from other developers.
  • Blog:Check out the blog posts for the latest news and updates.
  • Vist HMH Marketplace (beta)to learn how you can extend your reach to educators. Launched in March 2016 to support teachers looking for additional resources and applications to inspire curiosity in their classrooms, we welcome developers to sign up and create a profile on HMH Marketplace.

APIs

Identity API

Description: The Identity API will help you get a sense of the user's role within the ecosystem. Is the user a student or staff member? Which school are they enrolled in? In general, Identity will help you understand the role and enrollments of different users.

[Note: Here in the Developer Portal, Sandbox developers interact only with a demonstration school featuring fictional characters. New in v4, developers can create their own sample set of demo users with the v4/developer call.]

Why it Matters: HMH serves over 50 million people in all 50 states and over 150 countries worldwide. With approximately 15 million registered digital users, understanding our user base is essential to effectively integrating with our systems. Third party developers will be able to use the identity API to build applications that can help these users.

API Status: Exposed - me_v4, students_v4, staff_v4, schools_v4, and rosters_v4. v3 will remain exposed to allow developers time to transition to the updated v4. These include: me_v3, students_v3, staff_v3, schools_v3, rosters_v3, and sections_v3.

See Release Notes later in this guide for additional details and updates.


Document API

Description: Today's tech-savvy students build and create all sorts of digital files and artifacts, like documents, videos, sound bytes, and photos, to document their work. The document service offers students and teachers a central place to store their digital artifacts so they can more efficiently locate, reflect on, and use these files across all subjects and classes.

Why It Matters:Storage services will be available to provide a simple way for third party developers to POST documents or tags created externally back into the HMH learning ecosystem, for access and use within other HMH programs and platforms. For example, the Document API could also eventually be used to submit work or assignments from a third party app back to students' HMH accounts.

API Status: Exposed - documents_v4

Types:

Here is additional information that is relevant for developers using the document resources. A document can represent an uploaded file, link or note. The type of document depends on the uploaded file type or the document body parameters. The following document types, listed in order of precedence when storing, are possible.

  • Document::Image A document is stored with the Document::Image type if the file uploaded is recognized as an image.
  • Document::Video A document is stored with the Document::Video type if the file uploaded is recognized as a video.
  • Document::YoutubeLink A document is stored with the Document::YoutubeLink type if the url attribute when creating a document is of the form https://www.youtube.com/watch?v=wjd7L6txGLk.
  • Document::Link A document is stored with the Document::Link type if the url attribute is not blank when creating a document.
  • Document::Note A document is stored with the Document::Note type if the note_html attribute is not blank when creating a document.
  • Document If a document is created and does not match one of the requirements for one of the other document types, it will store with the general Document type.

Example:

As an example, start with a request to GET documents for the current user. In the resources section it is possible to see that the application user key and authorization are required headers:

Request:
GET "http://sandbox.graph.hmhco.com/v4/documents?page[size]=5&page[number]=1"

Required Headers:
Vnd-HMH-Api-Key: Your application key
Accepts: application/json
Authorization: SIF Token for user

A successful response will return a lot of information about the documents. Here is a partial sample of the beginning of the response...

[{
{ "data" : [ {
"content_type" : "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"created_at" : "2016-04-06T10:29:05-04:00",
"file_tmp" : "1459952945-33680-1592/GreatGatsbyEssayAssignment.docx",
"original_filename" : "GreatGatsbyEssayAssignment.docx",
"secure_token" : "eff6abc0-dc8b-4578-94b9-a5ac29060039",
"size" : 21579,
"updated_at" : "2016-04-07T13:40:26-04:00",
"title" : "Great Gatsby Essay Assignment",
"link_url" : null,
"user_ids" : [ 6262 ],
"hmh_one_ids" : [ "a6410465-cefb-484a-bbee-40cada43dde9" ],
"note_html" : null,
"type" : "Document",
"tags" : [ {
"id" : 193,
"name" : "Language Arts"
}, {
"id" : 194,
"name" : "Essays"
} ],
"file" : {
"status" : "processing"
}
},

...

Here is a partial sample of the end of the response:

"links" : {
"self" : "http://sandbox.graph.hmhco.com/v4/documents?page[number]=1&page[size]=5",
"next" : "http://sandbox.graph.hmhco.com/v4/documents?page[number]=2&page[size]=5",
"last" : "http://sandbox.graph.hmhco.com/v4/documents?page[number]=25&page[size]=5"
} }

Additonal Usage Notes:

  • The secure_token attribute contains the document Id. This is used in subsequent requests to GET or update (PUT) a specific document.
  • The document type is provided in the type attribute.
  • Note the tags attribute. This provides the tag id and the tag name. This means that the document has been tagged to id 193 with a name of Language Arts. Tags are user-generated key words that help classify and sort documents.
  • When uploading a document file, the file storing is done as a background process. Due to this, the initial JSON response may have a file attribute consisting of {"status":"processing"}. Once the file has been stored, the file attribute will be populated with URLs to access the stored file and any conversions of the file that have been made.
  • A document with the type Document::Image will also generate thumbnails of the images in 64p x 64px and 512px x 512px sizes. URLs for these files are provided in the file.thumb512.url and file.thumb64.url attributes of the JSON response. As with the url for the original document, these should also only be used if the file_tmp attribute is null.
  • A Microsoft Office document (.xls, .xlsx, .doc, .docx, .ppt, .pptx) or text file (.rtf, .txt, .odt) will generate a pdf version of the file. The URL for this file is provided in the file.pdf.url attribute of the JSON response.

For additional examples of cURL requests and sample responses, refer to the document found here.


Tag API

Description: The Tag API can be used in conjunction with the Document API to organize documents.

Why It Matters: Students and teachers generate and store a lot of documents throughout the year, often related to many different subjects. The ability to tag documents to key words, subjects, or phrases simply helps them organize and locate files quickly and easily.

API Status: Exposed - Tags_v4

Types:

UserTag - A UserTag is a tag that was created by the user and is only available for use by the user who created it. Users are able to create a UserTag and can update or delete a UserTag owned by them.

Example:

Consider an example of a developer that has a puzzle-making app. Perhaps it just allows teachers to turn a spelling list into an online crossword puzzle, and teachers want to be able to share the document or the link with their students within their HMH accounts. The developers might want to have a "Puzzle" tag attached to each puzzle the teacher makes so he or she can easily find all of the puzzles within his or her HMH account.

Developers could use a GET all tags request to understand the current tags of the user. The tag attribute that is returned includes a tag name and a tag ID:

GET "http://sandbox.graph.hmhco.com/v4/tags?page[size]=5&page[number]=1"

Required Headers:
Vnd-HMH-Api-Key: Your application key
Accepts: application/json
Authorization: SIF Token for user

Tag attribute from the response:

{ "data" : [ {
"type" : "UserTag",
"user_document_count" : 125,
"created_at" : "2016-04-07T08:06:28-04:00",
"group_id" : null,
"id" : 197,
"name" : "Games",
"updated_at" : "2016-04-07T08:06:28-04:00",
"user_id" : 6262
}

This might return the id # of a "Puzzles" tag, or it might demonstrate a need to create a "Puzzles" tag.

To create a new tag, developers would use the POST tags requests

POST http://sandbox.graph.hmhco.com/v4/tags

including the appropriate headers and the tag JSON:

{"tag":{"name":"Puzzles"}}

This would return a response with the new tag id, for example purposes only:

{ "data" : {
"type" : "UserTag",
"created_at" : "2016-04-14T12:50:18-04:00",
"group_id" : null,
"id" : 219,
"name" : "Puzzles",
"updated_at" : "2016-04-14T12:50:18-04:00",
"user_id" : 6266
}
}

Now, developers can now use this information in the Document API to do a couple of things.

First, developers can include the tag attribute in their POST and PUT documents requests to tag a document with the desired tag. This is done by including the tag id in the tags attribute field.

curl -v -X PUT -H "Vnd-HMH-Api-Key: <API_KEY>" -H "Authorization: <SIF_TOKEN>" -H "Content-Type:application/json" -H "Accepts:application/json"
"http://sandbox.graph.hmhco.com/v4/documents/98d728a9-0524-4dce-8e46-19a996876298"
-d '{"document":
{"title": "",
"url": "",
"tags": [219],
"note_html": ""}
}'

The response will indicate that the document includes the tag:

"data" : {
"content_type" : "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"created_at" : "2016-05-06T18:22:34-04:00",
"file_tmp" : null,
"original_filename" : "puzzle1.docx",
"secure_token" : "98d728a9-0524-4dce-8e46-19a996876298",
"size" : 22165,
"updated_at" : "2016-05-06T19:04:24-04:00",
"title" : "",
"link_url" : "",
"user_ids" : [ 6266 ],
"hmh_one_ids" : [ "4a4022a7-11ea-4c36-bcca-a950a99f5383" ],
"note_html" : "",
"type" : "Document",
"tags" : [ {
"id" : 219,
"name" : "Puzzles"
} ],

NOTE: PUT calls in the Swagger documentation will return a No Content response. The cURL is formatted correctly and will work from the command line.

See the resources for more information on the tags API or click here for further examples of cURLs and responses.


Assignment API

Description: No doubt you will remember your own experiences with assignments: a set of math problems, an essay, or a list of verb conjugations in French, for example. Assignments are typically assigned by teachers and completed and submitted by students for feedback and grading. The Assignment API was reintroduced in June 2016, with additional endpoints added in July 2016.

Why it Matters: Luckily, technology can make assignments a lot more interesting and engaging, and help users do more with the data! Do you have an exciting virtual lab experiment or a language-tutoring tool that could enhance learning for some or all students in a classroom? If so, the assignment APIs might be worth exploring. Teachers looking for new, innovative or additional assignment options might want to provide supplementary lessons, but would like to pull the scores back into their Houghton Mifflin Harcourt accounts. Developers focused on data and reporting might use the API to create an app to visualize data or notify teachers of scoring trends in the class.

API Status: Exposed Under v4/rosters, there are four endpoints for assignments: /v4/rosters/{id}/assignments/score, /v4/rosters/{id}/assignments/{assignment_id}/score, /v4/rosters/{id}/assignments/{assignment_id}/score/items, and /v4/rosters/{id}/assignments/score/standards. These endpoints return the assignment score based on the roster id.

Under v4/students, there are three new endpoints: /v4/students/{id}/assignments/score, /v4/students/{id}/assignments/score and /v4/students/{id}/assignments/score/standards. These three endpoints all need a roster id as a required parameter. They will return the assignment score or assignment standard score of a student for a specific roster.

For more information, visit the Swagger Documentation in the Resources section (must be signed in).


Content API

Description: The Content API is used to provide samples of HMH's award-winning content for developer use in the sandbox. Currently, Leveled Readers are available from the programs On Our Way to English and Literacy by Design.

Specific Readers from these programs have been selected because they are HMH owned, and do not contain licensed materials, such as photographs or text exerpts. This provides a pathway for developers to demonstrate how their app could improve the learning experiences of students in the classroom.

NOTE: The sandbox Content Plan contains a sample of the 160 K - 6 files available in production. Not all titles displayed above are available.

Why It Matters: At Houghton Mifflin Harcourt, we are a global learning company providing world-class programs and education services across a variety of channels. Providing the most accurate, highest-quality materials and content is at the heart of who we are.

By allowing third party developers access to the Content API, we invite you to align your innovative ideas and products to Houghton Mifflin Harcourt's content. This should provide teachers, students and parents with complementary options and a seamless user experience.

Entitlement: Developers creating applications that use the HMH Content API can market and sell applications in the HMH Marketplace to connect to HMH customers entitled to the content. Customers purchasing your app must already be entitled to the content or must purchase the content before the app will work with HMH content included. Entitlement checks will be done by HMH.

For more information on our commitment to quality content, please read the press release on HMH's Content Manifesto.

Visit hmhco.com to learn more about HMH's world class programs.


Using the API:

Before developers can access HMH Content, they must first request that their application's plan be changed to the Content Plan. To request the change:

  1. Click Applications in the top navigation bar of the Developer Portal.
  2. Then click on your application's name.
  3. Next to the plan type click Review / Change.
  4. Click on Content to select the Content plan.
  5. Finally, click Request Plan Change.

Acceptance to the Content plan requires approval. After you have submitted this plan change request, an HMH Labs representative may reach out to you to discuss your application, planned use of application content, and your participation in the HMH Marketplace. If you have questions or would like to discuss this in advance, please email us at labs@hmhco.com.

Have another idea?If you have an idea for enhancing the core experience of educators or students using other HMH Content, please contact us by email to labs@hmhco.com. The HMH Labs team is happy to discuss your plans for the use of HMH Content in your application, and provide guidance on the options available to you.


Release Notes

v4 Notes

In v4, we introduce new capabilities to create, update and delete documents and tags. We also introduce the /developer endpoint for developers to access unique demo data. Additional, the Content API is updated to provide a more accurate reflection of the production environment.

Please review the complete list of v4 updates:

  • Change to a new endpoint for all v4 API calls: http://sandbox.graph.hmhco.com/
  • Documents API: Addition of Create, Update and Delete options.
  • Tags API: Addition of Create, Update and Delete options.
  • Content API: Response data has been updated to reflect production.
  • /me endpoint: Response data has been updated to reflect production.
  • Addition of /developer: Allows developers to access unique demo data.
  • Updated swagger documentation to describe the facet and include params. See v3 release notes for additional details on facet and include.
  • The removal of /sections in favor of /rosters.

v3 Notes

In v3, we've expanded on the v2 improvements by adding a simple design pattern to improve performance and provide an overall enhanced developer experience. Read our December blog post to learn about the thought process behind these changes.

Key changes in v3 include:

  • The addition of the /me endpoint. This was added to provide developers with additional information about the current user.
  • The removal of courses, courses_v2.
  • The temporary removal of assignments.
  • The addition of sections, sections_v3.
  • The addition of pagination for all endpoints that return a list of information. This is implemented by two params: page[page] and page[page_size]. (NOTE: These two params are not currently displayed in the swagger documentation.) For example, http://sandbox.api.hmhco.com/v3/students?page[page]=2&page[page_size]=3 would only return information on students 4 through 6 in the list.
  • The addition of facet and include params. A facet represents a view of the model. Every model will have a summary facet and a detail facet. A summary facet will include commonly used fields like id, name, etc. A detail facet could include all the fields in the model with the child models. Include allows developers to request specific information to include in the child models.

  • Call examples:

    Use facet and include to: Example
    Get list of students with summary facet (default) /v3/students
    Get list of students with detail facet /v3/students?facet=detail
    Get list of students with detail facet and include address /v3/students?facet=detail&include=address
    Get a student with detail facet and include address /v3/students?include=address
    Get a student with detail facet and include address and contacts /v3/students?include=address,contact
    Get the first 10 students on the list /v3/students?page[page]=1&page[page_size]=10

    Refer to the following table to understand the facet, include, and pagination params, page[page] and page[page_size], supported in v3:

    Resource Supported facet Supported include Supports Pagination?
    v3/me summary
    v3/students summary, detail addresses, contacts yes
    v3/students/{id} summary, detail addresses, contacts
    v3/students/{id}/rosters summary, detail staff,students,term yes
    v3/staff summary, detail yes
    v3/staff/{id} summary, detail
    v3/staff/{id}/rosters summary, detail staff,students,term yes
    v3/rosters summary, detail staff,students,term yes
    v3/rosters/{id} summary, detail staff,students,term
    v3/sections summary, detail term yes
    /v3/learning_contents summary, detail yes
    /v3/learning_contents/{id} summary, detail
    /v3/tags yes
    /v3/tags/{id}
    /v3/documents user_ids,tags,file yes
    /v3/documents/{id} user_ids,tags,file

From Sandbox to Production

Getting Ready

Whether you’ve developed your application against our sandbox environment and are ready to apply for access to production, or you are just seeking more information about what is involved in the process, you’ve come to the right place.

Here we outline important considerations you should be aware of in order to get access to production.

Security and Code Review

Step 1. Security Review

Security of our systems is a top priority at HMH. As a precautionary step, HMH’s Information Security team requires a source code analysis before approving your Application for use in production. A security scan can help you to identify and correct potential vulnerabilities during the development stage prior to release of your application. The following resources can be used to further understand potential security risks and best practices that help development teams create more secure applications.

Step 2. Code Review

  • Option 1:Provide a full application security assessment report (either static or dynamic), including all vulnerabilities, for your application from one of the following vendors: Veracode,Checkmarx, IBM AppScan,WhiteHat Security or Cigital. This report should be of the version of code you that will be running in production and accessing HMH APIs and should have been completed within the last 14 days. Reports should be sent to HMH Information Security (Cc Catherine Hutchings).
  • Option 2:If you do not have a qualified report available, HMH can provide a free report to you from Checkmarx. These reviews sometimes cost a few thousand dollars, so we’re pleased to be able to offer this as a complementary service. This option requires a zip file of the uncompiled source code for the version of your application that you will be running in production and using to access HMH APIs. The file would be encrypted in transit and shared through the HMH MassTransit file transfer application. When you are ready to submit your code, contact labs@hmhco.com to request that a MassTransit link be created for transferring files. The request will be in the form of a separate email to you that includes a link to upload files and additional details on using this system. Links will be valid for 10 days.

Step 3. Review Results (Passing / Failing) –Security Review results will be provided, typically within 3 business days.

  • Passing Reviews: You will be notified of a passing result, and a new application will be created for you to access our production environment. Continue to Credentials for Production to learn more.
  • Failed Reviews: If potential risks to HMH are identified, you will be notified of the issues. It is your responsibility to address any issues and resubmit your updated source code for further review. You will not receive application credentials for the production environment until issues are resolved and you have passed review.

Credentials for Production

Get Application Credentials

Following a passing security and code review, complete the steps below to get your application’s credentials.

  1. Once the security and code review has passed, provide to the Labs team your redirect URIs. These must be in HTTPS format. You may provide a staging redirect URI for your own testing environment, and a production redirect URI for your production environment, and request applications for each.
  2. Once the redirect URIs are provided, an application will then be created and available to you in your Developer Portal account in the Applications section. You will need these credentials.
  3. You will be given the v1 production endpoint, and will want to update your app to call the new endpoints.
  4. For testing, you will be provided with demo user information for TC and myHRW users.
  5. If your application is commercially available, plan to participate on HMH Marketplace to promote your application. A Marketplace administrator will register your app in Marketplace – please see information on the Personally Identifiable Information (PII) filter.

HMH Marketplace

Promote Your App

What is HMH Marketplace?

HMH Marketplace is an online destination for educators to discover, share, and sell resources that enhance the teaching and learning experience. These resources can be any tool used by teachers to engage students or manage a classroom – from an app that facilitates communication between parents and teachers to a set of printable world capital flashcards.

What are the benefits of HMH Marketplace? Are there any costs?

Developers engaged in the HMH Developer Portal have an opportunity to create educational tools that integrate with the HMH platforms and easily market their applications to teachers around the world, at no cost. Keep in mind that there is a revenue share, which you can read more about in the Marketplace Terms & Conditions. Once you have built your application, the HMH Marketplace provides a clear path to distribute and commercialize your applications. Teachers will search by topic, grade level, or tool type and find the materials they need. Teachers can make their purchase, use the resource, and return to the HMH Marketplace to leave reviews and shop for more materials.

Where do I sign up?

Sign up for the HMH Marketplace here. Then click on the “Sell your product” button to create your provider account and begin listing your products on the Marketplace. Please be sure to review the Marketplace Terms & Conditions before signing up.

How do I create a listing?

To add a product listing, you'll first be asked to set up a Stripe account. Stripe enables transactions to happen easily on marketplaces.

After you've signed up on Stripe, you can create listings in your HMH Marketplace Account.

Before creating a listing, we suggest gathering the following details about your product:

  • Product Name
  • Product Teaser (limit 250 characters)
  • Product Description
  • Price
  • A primary product image (landscape 300x200 is best, but we can accept any reasonable size)
  • Additional images if you would like to show buyers more about your product
  • Tags or Categories
  • For a downloadable file - a single file: .pdf, .doc/.docx, .ppt/pptx, .xls/.xlsx, .png, .jpg/.jpeg, and .gif, .zip
  • For Mobile Apps, the link to your app in the Apple Store
  • For ALL Web Apps, the link to your web app
  • For Web Apps charging a fee (cost > $0): LTI URL, LTI Key, LTI Secret

See implementation information on LTI at the IMS Global web site: https://www.imsglobal.org/activity/learning-tools-interoperability.

For further information related to the items needed to create a listing, please download the provider checklist.

Creating a Mobile App Listing

Listings for mobile apps will redirect the customer to the App Store to complete the transaction and download the app to their mobile device.

To list mobile apps, you must follow these guidelines when creating the listing:

  • Since the transaction happens outside of HMH Marketplace, in the App Store, enter a price of $0.00 when creating your listing. This is true even if your app is not free, and prevents the customer from getting charged twice.
  • If your app costs money in the app store, clearly state the cost of your app in the Teaser or Description.
  • Select "My product is an application" when creating the listing
  • The URL should be an Apple iTunes URL.

Listings for mobile apps that do not meet these requirements will be returned for corrections.

Creating a Web App Listing

Before you list your web app, review the LTI requirements.

Web apps charging a fee (cost > $0) must provide:

  • URL for your application, such as https://yourcompany.com
  • LTI URL, such as https://yourcompany.com/lti
  • LTI Key
  • LTI Secret

See implementation information on LTI at the IMS Global web site: https://www.imsglobal.org/activity/learning-tools-interoperability.

PII Filter

What is the PII Filter?

The Personally Identifiable Information (PII) Filter is a filter that, when in use, limits personal information on students / teachers from the responses of the APIs.

How does the PII Filter work?

A Marketplace Admin will add the application to Marketplace (PROD). The application is authorized by district. By default, districts are automatically added with the PII Filter ON. When the filter is ON, it filters student information. Please note that limited data should be returned even with the PII filter turned on, so teachers’ should be able to use the product prior to approval. It’s simply that the Personally Identifiable Information (PII) is protected.

Developers need to add the following text to their Marketplace listings:

**Please note: This application is designed to integrate with HMH APIs in order to access relevant data about students. However, when you first access this application, no student data will be made available to you. In order to gain access to student data via this application and HMH APIs, an authorized representative from your school district must provide written approval to representatives at HMH. Please contact HMH Labs for more information.

Turning the PII Filter Off

If you're working with a district and would like the PII filter turned off, the District Admin needs to provide written authorization. An email from their district account to HMH Labs is all that is required. They can also provide their district ID #, if they know it. If they do not know their district ID #, we can determine it for them.

What if the teacher doesn't know who their District Admin is?

The first route is for them to contact their administrator or principal to determine who the current District Admin is for their school. This will be their most valid source of current information. If they continue to have difficulty, HMH Technical Support can look up the District Admin in Think Central or HRW. However, we often see multiple District Admins in the system and won’t necessarily know which one is best.

Sample Responses: PII Filter ON vs. PII Filter OFF

Coming Soon

Additional Considerations for HMH Marketplace

Before signing up for HMH Marketplace, review the Marketplace Terms & Conditions. Additional considerations include:

  • Stripe: A Stripe account is required for Beta – this is our selected platform to handle transactions. Even if all your products are free, you’ll need to set up a free account on https://dashboard.stripe.com/register
  • iOS Apps: For iOS Apps, we will use Apple’s Affiliate Program to track referrals from HMH Marketplace. This does not require any action on your part.