Skip to content Skip to site navigation Skip to service navigation

Student RESTful Web Services API

The student web service allows for the retrieval of student and course data.

This includes getting:

  • A Student's Person XML
  • Student's Enrollment XML for current term
  • Student's Enrollment XML for a specific term
  • Student's Enrollment XML — all classes
  • Course and Class, just Course, just Class or Section XML

How to get started with the Student API

Follow the Middleware and Integration Services Integration (MaIS) checklist for RESTful Web Services. If you need help, are not sure whether the Web APIs are the best method for integrating with the registry, or just have some questions, contact the MaIS team.

HTTP status codes

Code Conditions
200 OK The usual successful return code.
400 Bad Request Missing required parameters or identifier is in wrong format.
403 Access Denied The request was made without valid certificate.
404 Not Found The record you're looking for doesn't exist.
500 Internal Server Error Something broke with our code. Please tell us about it.

Error handling

Error handling works for all web services except student search.

Student API sends error status via standard HTTP status codes (4xx or 5xx) and always returns an XML document detailing the error. For example, when the client makes a call to get a person XML and the person's id is invalid, the system will return the following XML error document:

<?xml version="1.0" encoding="UTF-8"?>
<error>
        <code>404</code>
        <message><![CDATA[Person resource xxxxx not found.]]></message>
</error>

Get student's person XML

Description Get Person XML
URL https://studentws.stanford.edu/v1/person/{personId}
Method GET
Returns 200 & Person XML
400 & error XML: personId's affiliation is not student.
404 & error XML: personId is invalid.

personId could be univid, sunetid or regid.

Get student's enrollment XML for current term

Description Get Enrollment XML for current term
URL https://studentws.stanford.edu/v1/person/{personId}/enrollment/term
Method GET
Returns 200 & Enrollment XML
400 & error XML: personId's affiliation is not student.
404 & error XML: personId is not registered for any course in current term.

personId could be univid, sunetid or regid.

Get student's enrollment XML for a term

Description Get Enrollment XML for a term
URL https://studentws.stanford.edu/v1/person/{personId}/enrollment/term/{termId}
Method GET
Returns 200 & Enrollment XML
400 & error XML: personId's affiliation is not student.
404 & error XML: personId is not registered for any course in current term.

personId could be univid, sunetid or regid.

Get student's enrollment XML — all classes

Description Get Enrollment XML
URL https://studentws.stanford.edu/v1/person/{personId}/enrollment
Method GET
Returns 200 & Enrollment XML
400 & error XML: personId's affiliation is not student.
404 & error XML: personId is not registered for any course in current term.

personId could be univid, sunetid or regid.

Student search by qualifier, career, acadId, and returnType — plain text

Description Search students for given qualifier, career, and acadId values. acadId parameter is optional. The method returns the student info in plain text.
The web service returns the student data determined by returnType parameter, e.g., if returnType=sunetid, the search will return sunetid of all the students in plain text, one sunetid per line.
Valid qualifier values are: contingent, incoming, ndo, nonactive, notregistered, onleave, postdoc, recent, and active.
Valid career values are: gsb, med, law, gr, and ug.
Valid returnType values are: regid, univid, card, directory, and sunetid. The default value for returnType is regid.
Set accept header with value text/plain to access this web service.
Method does not return XML in case of an error. Check return types for detail.
Some combinations of parameters do not work, e.g., qualifier=incoming&returnType=card will return 404.
URL https://studentws.stanford.edu/v1/person/search?qualifier=incoming&career=UG
Method GET
Query String qualifier=incoming&career=UG
Returns 200 & persons ids
400 & error string: required parameters qualifier and career are missing
404 & error string: No person is found for given search criteria

Get courseclass XML

Description Get courseclass XML by Id
URL https://studentws.stanford.edu/v1/courseclass/{courseClassId}
Method GET
Returns 200 & CourseClass XML
400 & error XML: courseClassId does not look like termId-courseId or termId-subject-catalogNumber
404 & error XML: courseClassId is invalid.

courseClassId should look like termId-courseId or termId-subject-catalogNumber eg, 1026-103398 or 1026-CHEMENG-450

Get course XML

Description Get course XML by Id
URL https://studentws.stanford.edu/v1/courseclass/{courseClassId}/course
Method GET
Returns 200 & Course XML
400 & error XML: courseClassId does not look like termId-courseId or termId-subject-catalogNumber​
404 & error XML: courseClassId is invalid.

courseClassId should look like termId-courseId or termId-subject-catalogNumber, e.g., 1026-103398 or 1026-CHEMENG-450

Get class XML by courseClassId and class offeringNumber

Description Get class XML by courseClassId and class offeringNumber
URL https://studentws.stanford.edu/v1/courseclass/{courseClassId}/class/offering/{offeringNumber}
Method GET
Returns 200 & Class XML
400 & error XML: courseClassId does not resemble termId-courseId, e.g., 1026-103398
404 & error XML: courseClassId is invalid.

courseClassId should look like termId-courseId, e.g., 1026-103398

Get class XML by class id

Description Get class XML by Id​
URL https://studentws.stanford.edu/v1/class/{classId}
Method GET
Returns 200 & Class XML
400 & error XML: classId does not resemble termId-subject-catalogNumber, e.g., 1026-CHEMENG-450
404 & error XML: classId is invalid.

classId should look like termId-subject-catalogNumber e.g., 1026-CHEMENG-450

Class search by termId and subject

Description Search classes for given termId and subject. termId parameter is optional. If termId is not provided, the current termId is used for class search.​
URL https://studentws.stanford.edu/v1/class/search?termId=1074&subject=ENGR​
Method GET
Query String termId=1074&subject=ENGR​
Returns 200 & classes XML
400 & error XML: required parameter subject is missing
404 & error XML: No class is found for given search criteria

Class search by termId and acadId

Description Search classes for given termId and acadId. termId parameter is optional. If termId is not provided, the current termId is used for class search.
URL https://studentws.stanford.edu/v1/class/search?termId=1074&acadId=GSB
Method GET
Query String termId=1074&acadId=GSB
Returns 200 & classes XML
400 & error XML: required parameter acadId is missing
404 & error XML: No class is found for given search criteria

Get section XML

Description Get section XML by courseClassId, class offeringNumber, and section classNumber
URL https://studentws.stanford.edu/v1/courseclass/{courseClassId}/class/offering/{offeringNumber}/section/{classNumber}
Method GET
Returns 200 & section XML
400 & error XML: courseClassId does not resemble termId-courseId eg, 1026-103398​
404 & error XML: courseClassId is invalid.

courseClassId should look like termId-courseId, e.g., 1026-103398

Last modified January 13, 2017