Object IDs, SIS IDs, and special IDs

Throughout the API, objects are referenced by internal IDs. You can also reference objects by SIS ID, by prepending the SIS ID with the name of the SIS field, like sis_course_id:. For instance, to retrieve the list of assignments for a course with SIS ID of A1234:

/api/v1/courses/sis_course_id:A1234/assignments

The following objects support SIS IDs in the API:

• sis_account_id
• sis_course_id
• sis_group_id
• sis_group_category_id
• sis_integration_id (for users and courses)
• sis_login_id
• sis_section_id
• sis_term_id
• sis_user_id

Some objects support LTI IDs:

• lti_context_id (for accounts, assignments, courses, groups, and users)
• lti_1_1_id (for users, an alias of lti_context_id, which is sent in LTI 1.1 launches as user_id)
• lti_1_3_id (for users, a separate value from lti_context_id, sent in LTI 1.3 launches as sub)

Additionally, some objects support special IDs:

• Users support self to mean the current user.
• Accounts support self to mean the root account for the current domain, default to mean the Default account, and site_admin to mean the Site Admin account.
• Terms support default to mean the default term, and current to mean the term that is currently active according to term dates. A term must have a start date or an end date to be considered the current term. If there is more than one term that's active, current will not be found.

Encoding and Escaping

SIS IDs should be encoded as UTF-8, and then escaped normally for inclusion in a URI. For instance the SIS ID CS/101.11é is encoded and escaped as CS%2F101%2E11%C3%A9.

Note that some web servers have difficulties with escaped characters, particularly forward slashes. They may require special configuration to properly pass encoded slashes to Rails.

For Apache and Passenger, the following settings should be set:

• AllowEncodedSlashes NoDecode
• PassengerAllowEncodedSlashes on

Also beware that if you use ProxyPass, you should enable the nocanon option. Similarly, RewriteRule should use the NE, or noescape flag. Other modules may also need additional configuration to prevent double-escaping of %2f (/) as %252f.

Prior versions of this API documentation described using a hex encoding to circumvent these issues, since the proper Apache/Passenger configuration was not known at the time. This format is deprecated, and will no longer be described, but will continue to be handled by the server for backwards compatibility.

Trusted Root Accounts

SIS IDs are only unique within a root account, so an unqualified SIS ID is looked up in the root account serving the request and nowhere else. If your root account is part of a consortium, or has a trust relationship with another root account, prefix the SIS ID with the owning account's domain to address a user that account owns:

/api/v1/users/root_account:school.instructure.com:sis_user_id:A1234

Any of the user SIS IDs above (sis_user_id, sis_login_id, sis_integration_id) can be qualified this way. The domain must belong to a root account that yours trusts, or one in which you have permission to read SIS data; otherwise the user is reported as not found.

The domain prefix never needs escaping, since a domain cannot contain any of the affected characters. Encode and escape the SIS ID that follows it exactly as described above.