3. EdX Enterprise API Reference¶

This API reference includes detailed information about the endpoints of the edX Enterprise API, including the request, response data, and examples. You can use any technology to send REST API requests as HTTP messages to the edX API. The example API requests shown in this reference use the curl command-line program to show the syntax and data for a request in a way that is easy to read.

3.1. Endpoints¶

The following endpoints are available in the Enterprise API.

/enterprise-catalogs - You can make GET calls to the /enterprise/v2/enterprise-catalogs endpoint to get a list of all the course catalogs that are available to your organization. For details, see enterprise-catalogs Endpoint.
/enterprise-catalogs/{catalog_id} - You can make GET calls to the /enterprise/v2/enterprise-catalogs/{catalog_id} endpoint to get a list of all the active courses in a specified course catalog. Active courses are courses that are currently open for enrollment or that will open for enrollment in the future. For details, see enterprise-catalogs/{catalog_id} Endpoint.
/enterprise-catalogs/{catalogID}/courses/{course_key} - You can make GET calls to the /enterprise/v2/enterprise-catalogs/{catalog_id}/courses/{course_key} endpoint to get information about a single course. For details, see enterprise-catalogs/{catalog_id}/courses/{course_key} Endpoint.
/enterprise-catalogs/{catalogID}/course-runs/{course_run_ID} - You can make GET calls to the /enterprise/v2/enterprise-catalogs/{catalog_id}/course-runs/{course_run_ID} endpoint to get information about a single course run. For details, see enterprise-catalogs/{catalog_id}/course-runs/{course_run_ID} Endpoint.
/enterprise-catalogs/{catalogID}/programs/{program_ID} - You can make GET calls to the /enterprise/v2/enterprise-catalogs/{catalog_id}/programs/{program_ID} endpoint to get information about a single program. For details, see enterprise-catalogs/{catalog_id}/programs/{program_ID} Endpoint.
/learner-summary - You can make GET calls to the /enterprise/v3/enterprise-customer/{enterprise_uuid}/learner-summary endpoint to get a list of information about your enterprise learners and their status in the courses they are enrolled in. For details, see learner-summary Endpoint.

Use this JSON file to import into your Postman enviroment . It includes the endpoints mentioned above.

3.2. Returning Data in XML or JSON Format¶

By default, the edX Enterprise API returns data in XML format. It can also return data in JSON format. To specify that return data should use JSON format, include the Accept: application/json header in your API request. For example, to request JSON-formatted information about a course run using curl, send a request similar to the following command.

curl -X GET \
https://api.edx.org/enterprise/v2/enterprise-catalogs/3f56a21c-76c8-47c0-add8-a99714d40d94/courses/MyUni+Sport101x \
-H "Authorization: JWT {access token}"
-H "Accept: application/json"

3.3. enterprise-catalogs Endpoint¶

GET calls to the enterprise-catalogs endpoint to get list of all the course catalogs that are available to your organization.

3.3.1. Method and Endpoint¶

Method	Endpoint
GET	`/enterprise/v2/enterprise-catalogs`

3.3.2. Example Request¶

curl -X GET
  https://api.edx.org/enterprise/v2/enterprise-catalogs \
  -H "Authorization: JWT {access token}"
  -H "Content-Type: application/json" \
 }]"

3.3.3. Response Values¶

The GET /enterprise/v2/enterprise-catalogs request returns the values: count, next, previous, results described here: Response Values. The results response value include these fields:

Field	Data Type	Description
`uuid`	string	A unique identifier for the catalog.
`title`	string	The name that describes the catalog.
`enterprise_customer`	string	The customer’s unique identifier links to a catalog.
`catalog_query_uuid`	string	A unique identifier for the catalog query.
`content_last_modified`	string	Datetime string of the last time the content in the catalog was updated.
`catalog_modified`	string	Datetime string of the last time the catalog was modified.
`query_title`	string	The string title of the query used by the catalog.
`include_exec_ed_2u_courses`	bool (Nullable)	Whether or not the catalog allows the linking of Executive Education content.

3.4. enterprise-catalogs/{catalog_id} Endpoint¶

GET calls to the enterprise-catalogs/{catalog_id} endpoint return a list of all of the active courses in a specified course catalog. You can then make a GET call to the /enterprise-catalogs/{catalog_id}/courses/{course_key} endpoint to return details about a single course.

3.4.1. Method and Endpoint¶

Method	Endpoint
GET	`/enterprise/v2/enterprise-catalogs/{catalog_id}`

3.4.2. Example Request¶

curl -X GET \
https://api.edx.org/enterprise/v2/enterprise-catalogs/3f56a21c-76c8-47c0-add8-a99714d40d94/ \
-H "Authorization: JWT {access token}"

3.4.3. Parameters¶

You can use an optional limit parameter to specify the number of courses that enterprise-catalogs/{catalog_id} calls return on each page of the response. If you do not supply the limit parameter, the enterprise-catalogs/{catalog_id} call returns the default value of 20 courses per page. For example:

curl -X GET https://api.edx.org/enterprise/v2/\
enterprise-catalogs/3f56a21c-76c8-47c0-add8-a99714d40d94?limit=250 \
-H "Authorization: JWT {access token}"

3.4.4. Response Values¶

The GET /enterprise/v2/enterprise-catalogs/{catalog_id} request returns the following response values.

Note

Responses to GET requests for the edX Enterprise API frequently contain the results response value. The results response value is a variable that represents the intended object from the GET request. For the /enterprise/api/v2/enterprise-catalogs/{catalog_id} endpoint, the results object holds an array of objects that list information about each individual course in the catalog.

Field	Data Type	Description
`count`	integer	The number of courses in the catalog.
`next`	string	The URL for the next page of results.
`previous`	string	The URL for the previous page of results.
`results`	array	A list of content items in the catalog.

Each top-level object in the results array represents a course in the catalog. See course for information about the fields in a course item in the results.

3.5. enterprise-catalogs/{catalog_id}/courses/{course_key} Endpoint¶

GET calls to the enterprise-catalogs/{catalog_id}/courses/{course_key} endpoint return information about a single course in a specified course catalog. In the GET call, you pass a catalog ID, which you can get using the enterprise-catalogs endpoint, and a course key (a unique identifier for a course), which you can get from the key value returned by the enterprise-catalogs/{catalog_id} endpoint. By default, the information is returned in XML format. The information returned is described in Fields in a course Content Item.

3.5.1. Method and Endpoint¶

Method	Endpoint
GET	`/enterprise/v2/enterprise-catalogs/{catalog_id}/courses/{course_key}`

3.5.2. Example Request¶

curl -X GET \
https://api.edx.org/enterprise/v2/enterprise-catalogs/3f56a21c-76c8-47c0-add8-a99714d40d94/courses/MyUni+Sport101x \
-H "Authorization: JWT {access token}"

3.5.3. Response Values¶

The GET /enterprise/v2/enterprise-catalogs/{catalog_id}/courses/{course_key} request returns the response values described in Fields in a course Content Item.

3.6. enterprise-catalogs/{catalog_id}/course-runs/{course_run_ID} Endpoint¶

GET calls to the enterprise-catalogs/{catalog_id}/course-runs/{course_run_ID} endpoint return information about a single course run in a specified course catalog. In the GET call, you pass a catalog ID, which you can get using the enterprise-catalogs endpoint, and a course run ID, which you can get from the key value returned by the enterprise-catalogs/{catalog_id} endpoint. The information returned is described in Fields in a course_run Content Item.

3.6.1. Method and Endpoint¶

Method	Endpoint
GET	`/enterprise/v2/enterprise-catalogs/{catalog_id}/course-runs/{course_run_ID}`

3.6.2. Example Request¶

curl -X GET \
https://api.edx.org/enterprise/v2/enterprise-catalogs/3f56a21c-76c8-47c0-add8-a99714d40d94/course-runs/course-v1:MyUni+Sport101x \
-H "Authorization: JWT {access token}"

3.6.3. Response Values¶

The GET /enterprise/v2/enterprise-catalogs/{catalog_id}/course-runs/{course_run_ID} request returns the response values described in Fields in a course_run Content Item.

3.7. enterprise-catalogs/{catalog_id}/programs/{program_ID} Endpoint¶

GET calls to the enterprise-catalogs/{catalog_id}/programs/{program_ID} endpoint return information about a single program in a specified course catalog. In the GET call, you pass a catalog ID, which you can get using the enterprise-catalogs endpoint, and a program ID, which you can get from the uuid value returned by the enterprise-catalogs/{catalog_id} endpoint. The information returned is described in Fields in a program Content Item.

3.7.1. Method and Endpoint¶

Method	Endpoint
GET	`/enterprise/v2/enterprise-catalogs/{catalog_id}/programs/{program_ID}`

3.7.2. Example Request¶

curl -X GET \
https://api.edx.org/enterprise/v2/enterprise-catalogs/3f56a21c-76c8-47c0-add8-a99714d40d94/programs/7b24a21c-98c8-47c0-b9c8-g54714d40d94 \
-H "Authorization: JWT {access token}"

3.7.3. Response Values¶

The GET /enterprise/v2/enterprise-catalogs/{catalog_id}/programs/{program_uuid} request returns the response values described in Fields in a program Content Item.

3.8. Course, Course Run, and Program Fields¶

Each top-level object in the results array represents a content item in the catalog, which may be a course, a course run, or a program. The results array returns different fields, depending on whether the content item is a course, a course run, or a program.

3.8.1. Fields in a course Content Item¶

Field	Data Type	Description
`course_runs`	array	The currently existing course runs for the course.
`enrollment_url`	string	The URL for the enrollment page.
`entitlements`	array	Information about seat purchase options.
`expected_learning_items`	array	Elements of the course.
`full_description`	string	The HTML full description of the course.
`image`	array	The About page image for the course.
`key`	string	A unique identifier for the course. Example: `edX+DemoX`.
`level_type`	enum string	The course’s level of difficulty, such as `Intermediate` or `Advanced`.
`marketing_url`	string	The URL for the course About page.
`modified`	datetime	The most recent date and time when the course metadata was modified.
`original_image`	string	The URL of the original unmodified image for the course About page.
`outcome`	string	What learners will learn from the course.
`owners`	array	The institution that offers the course.
`prerequisites`	array	Any courses a learner must complete before enrolling in the current course.
`prerequisites_raw`	array	Any courses a learner must complete before enrolling in the current course.
`programs`	array	Any programs that the course is part of.
`short_description`	string	The HTML short description of the course.
`sponsors`	array	The corporate sponsors for the course.
`subjects`	array	The academic subjects that the course covers.
`syllabus_raw`	string	The course syllabus.
`title`	string	The title of the course.
`uuid`	string	The unique identifier for the course. Example: `0dbd8181-8866-47fc...`
`video`	array	The course About video.

3.8.2. Fields in a course_run Content Item¶

Field	Data Type	Description
`aggregation_key`	string	Example: `courserun:edX+DemoX`.
`authoring_organization_uuids`	array	The unique user IDs for the organizations that produced the content item.
`availability`	enum string	One of `Current`, `Upcoming`.
`content_type`	enum string	Type of learning item. In this case, the value is `courserun`.
`end`	datetime	The end date of the course run.
`enrollment_end`	datetime	The last date and time when this course run is open for learners to enroll. Learners cannot enroll after this date and time.
`enrollment_start`	datetime	The first date and time when this course run is open for learners to enroll. Learners cannot enroll before this date and time.
`enrollment_url`	string	The URL for the enrollment page.
`full_description`	string	The long description of the course and its content.
`has_enrollable_seats`	boolean	Whether learners can enroll in the course run.
`image_url`	string	The URL for the About page image for the course.
`key`	string	An identifier for the course. For example, `RITx+PM9003x`.
`language`	string	The language used by the content item.
`level_type`	enum string	The course’s level of difficulty. Can be one of `high_school`, `introductory`, `intermediate`, or `advanced`.
`logo_image_urls`	array	The URLs of the enterprise’s logos.
`marketing_url`	string	The URL for the course About page.
`max_effort`	integer	The maximum number of estimated hours of effort per week.
`min_effort`	integer	The minimum number of estimated hours of effort per week.
`mobile_available`	boolean	Whether the content item is available for mobile devices.
`number`	string	The content item’s course number identifier.
`org`	string	The university or other entity offering the course.
`pacing_type`	enum string	The pacing of the course. May be `self-paced` or `instructor-paced`.
`partner`	string	The university or other entity offering the course.
`program_types`	array	The type of program. One of Professional Certificate, XSeries, MicroMasters, or Professional Program.
`published`	boolean	Whether the content item has been published.
`seat_types`	enum string	The enrollment types that are available. One of `audit`, `verified`, `professional`.
`short_description`	string	The short description of the content item and its content.
`staff_uuids`	array	The unique identifiers of the staff for the content item.
`start`	datetime	The start time for the content item.
`subject_uuids`	array	The unique identifiers of the subject categories of the content item.
`title`	string	The title of the content item. For example, “Introduction to Plasma Physics”.
`transcript_languages`	array	The languages for which video transcripts are available.
`type`	enum string	One of `verified`, `professional`
`weeks_to_complete`	integer	The number of weeks required to complete the content item.

3.8.3. Fields in a program Content Item¶

A program is a collection of related courses.

Field	Data Type	Description
`aggregation_key`	string	Example: `program:7a8b9c6ead`.
`authoring_organization_uuids`	array	The unique user IDs for the organizations that produced the program.
`authoring_organizations`	array	Information about the organizations that produced the program.
`card_image_url`	string	The URL of an image that represents the program.
`content_type`	enum string	Type of learning item. In this case, the value is `program`.
`enrollment_url`	string	The URL for the enrollment page.
`language`	string	The language used by the program.
`marketing_url`	string	The URL for the program About page.
`max_hours_effort_per_week`	integer	The maximum number of estimated hours of effort per week.
`min_hours_effort_per_week`	integer	The minimum number of estimated hours of effort per week.
`partner`	string	The organization offering the program.
`published`	boolean	Whether the program has been published.
`published`	boolean	Whether the content item has been published.
`staff_uuids`	array	The unique identifiers of the staff for the program.
`subject_uuids`	array	The unique identifiers of the subject categories of the program.
`subtitle`	string	A subtitle for the program.
`title`	string	The title of the program. For example, “MicroMasters: Plasma Physics”.
`type`	enum string	The program type. One of `Professional Certificate`, `XSeries`, or `MicroMasters`.
`uuid`	string	The unique identifier for the program.
`weeks_to_complete_max`	integer	The maximum number of estimated weeks required to complete the program.
`weeks_to_complete_min`	integer	The minimum number of estimated weeks required to complete the program.

3.8.4. Example Response Showing Information about a Course Run¶

The following example response shows a single course run. A catalog may contain many course runs.

{
  "uuid": "0e871df0-6e43-4cfc-92cc-357ebf1fda75",
  "title": "All Content",
  "enterprise_customer": "58152f7f-6d0e-41cf-862d-0a27c6fad72c",
  "count": 13,
  "previous": null,
  "next": null,
  "results": [
    {
      "content_type": "courserun",
      "number": "DemoX",
      "weeks_to_complete": 3,
      "partner": "edx",
      "enrollment_url": "https://courses.edx.org/
      enterprise/58152f7f-6d0e-41cf-862d-0a27c6fad72c/course/
      course-v1:edX+DemoX+Demo_Course/enroll/?catalog=0e871df0-6e43-4cfc-92cc-3
      57ebf1fda75&utm_medium=enterprise&utm_source=degreed-company",
      "availability": "Upcoming",
      "transcript_languages": [

      ],
      "logo_image_urls": [
        "https://www.edx.org/sites/default/files/school/image/logo/
        gtx-logo-200x101.png"
      ],
      "end": null,
      "title": "edX Demonstration Course",
      "enrollment_start": "2017-10-01T00:00:00",
      "start": "2017-11-01T05:00:00",
      "min_effort": 5,
      "short_description": "A hands-on introduction to basic programming
      principles and practice relevant to modern data analysis, data mining,
      and machine learning.",
      "image_url": "https://courses.edx.org/
      asset-v1:edX+DemoX+Demo_Course+type@asset+block@images_course_image.jpg",
      "level_type": "Beginner",
      "type": "verified",
      "marketing_url": "course/edxdemoslug?utm_medium=enterprise
      &utm_source=degreed-company",
      "seat_types": [
        "audit",
        "verified"
      ],
      "max_effort": 6,
      "full_description": "<p>The modern data analysis pipeline involves
      collection, preprocessing, storage, analysis, and interactive
      visualization of data.</p>\\n<p>The goal of this course, part of the
      Analytics: Essential Tools and Methods MicroMasters program, is for you
      to learn how to build these components and connect them using modern
      tools and techniques.</p>",
      "key": "course-v1:edX+DemoX+Demo_Course",
      "enrollment_end": null,
      "org": "edX",
      "authoring_organization_uuids": [
        "12de950c-6fae-49f7-aaa9-778c2fbdae56"
      ],
      "subject_uuids": [

      ],
      "has_enrollable_seats": true,
      "language": "English",
      "staff_uuids": [
        "a1b2c3d4-3185-4233-a323-2fbeb401cb82",
        "a1b2c3d4-4ebe-4e5c-b0a2-2ff630c0dae0",
        "b2c3d4e5-bf58-47cf-ae9a-994c0eb22062",
        "1111a42a-b667-4664-bdaa-4754e1cfd480"
      ],
      "mobile_available": true,
      "pacing_type": "self_paced",
      "aggregation_key": "courserun:edX+DemoX",
      "published": true,
      "program_types": [
        "Professional Certificate"
      ]
    }

3.9. learner-summary Endpoint¶

GET calls to the learner-summary endpoint get information about learners’ course enrollments and progress.

3.9.1. Method and Endpoint¶

Method	Endpoint
GET	`/enterprise/v3/enterprise-customer/{enterprise_uuid}/learner-summary`

3.9.2. Example Request¶

curl -X GET
  https://api.edx.org/enterprise/v3/enterprise-customer/{{enterprise_uuid}}/learner-summary \
  -H "Authorization: JWT {access token}"
  -H "Content-Type: application/json" \
 }]"

3.9.3. Response Values¶

The GET /enterprise/v3/enterprise-customer/{enterprise_uuid}/learner-summary request returns the following data.

Field	Data Type	Description
`is_consent_granted`	boolean	Whether the learner has granted consent for edX to share information about their course enrollment and progress with the enterprise.
`amount_learner_paid`	decimal	The amount the learner paid towards the enrollment, if any.
`contract_id`	string	A unique identifier for the contract that this enrollment is associated with.
`coupon_code`	string	The enrollment code string used by the learner to enroll in their course. (Not applicable for Subscriptions or Offers).
`coupon_name`	string	The name of the enrollment code batch used by the learner to enroll in their course. (Not applicable for Subscriptions or Offers).
`course_api_url`	string	The complete url for the course when using the edX API Retrieve Course Metadata endpoint.
`course_duration`	integer	The duration in weeks, for instructor-paced courses, or the expected duration for self-paced courses.
`course_end`	date	The date the course ends, in YYYY-MM-DD format. This is the last date on which learners can submit answers or assessments, or otherwise be credited with completion of a course subsection.
`course_key`	string	The unique identifier for the overall course.
`course_list_price`	decimal	The original price of the course, before any discount were applied.
`course_max_effort`	integer	The estimated maximum effort required by the course, in hours per week.
`course_min_effort`	integer	The estimated minimum effort required by the course, in hours per week.
`course_pacing_type`	string	Whether the course is self-paced or instructor-paced.
`course_primary_program`	string	The primary program a course belongs to. (Not applicable to courses that aren’t part of a program).
`course_primary_subject`	string	The subject category this course falls under when searching on edX.org.
`course_start`	date	The date when the course begins, in YYYY-MM-DD format. This is the date when course content is available for learners to interact with. In most cases, learners can enroll in the course before the `course_start` date.
`course_title`	string	The title of the edX course.
`courserun_key`	string	The unique identifier for the individual courserun.
`created`	timestamp	The date and time the learner progress report was last updated.
`current_grade`	decimal	The learner’s current grade, which will update as the learner proceeds through the course.
`enrollment_date`	date	The date, YYYY-MM-DD, the learner enrolled in the course.
`enrollment_id`	integer	A unique identifier for this enrollment.
`enterprise_customer_uuid`	string	The enterprise account ID assigned by edX.
`enterprise_enrollment_id`	integer	A unique identifier for this enrollment, specific to enterprise enrollments.
`enterprise_name`	string	The enterprise account name.
`enterprise_sso_uid`	string	The learner’s user ID in the enterprise’s Identity Provider. (Only applicable for customers using Single Sign On).
`enterprise_user_id`	integer	The learner’s ID assigned by edX.
`has_passed`	boolean	Whether or not the learner has passed this course.
`is_consent_granted`	boolean	Whether the learner has granted consent for edX to share information about their course enrollment and progress with the enterprise.
`is_refunded`	boolean	Whether or not the learner received a refund on their enrollment.
`last_activity_date`	date	The most recent date, YYYY-MM-DD,the learner was active in an edX.
`letter_grade`	string	The learner’s letter grade, if they have passed the course.
`offer_name`	string	The offer ID used by the learner to enroll in their course. (Not applicable for Subscriptions or Codes).
`offer_type`	string	The offer type and discount percentage used by the learner to enroll in their course. (Not applicable for Subscriptions or Codes).
`paid_by`	string	Whether the enrollment was paid for by the enterprise, the learner, or a third party.
`passed_date`	date	The date, YYYY-MM-DD, the learner passed the course.
`progress_status`	string	Whether the learner is still working on the course, has passed, or has failed. Possible values are: Failed, In Progress, Passed.
`seat_delivery_method`	string	The type of subsidy used by the learner to enroll in their course.
`unenrollment_date`	date	The date,YYYY-MM-DD, the learner unenrolled from the course.
`unenrollment_end_within_date`	date	The date ,YYYY-MM-DD, the learner must unenroll by, in order to receive a refund on the enrollment. This date is traditionally 14 days from the enrollment date or the course start date, whichever is later.
`user_account_creation_date`	timestamp	The date and time when the learner’s account was created in the edx.org LMS.
`user_country`	string	A two-letter country code.
`user_current_enrollment_mode`	string	The learner’s current enrollment mode in the course.
`user_email`	string	The learner’s email address.
`user_username`	string	The learner’s username on edx.org.