These actions and structures provide access to the organization structure
configured for an LMS. The structure is grouped into generic nodes called org
units (organizational units). An org unit node can represent several different
kinds of things within an LMS and the institution determines the precise mixture
of custom org unit types
available through
its LMS. However, by default, an LMS comes with several built-in org unit types
(course offerings, departments, semesters) fundamental to most learning
institutions.
Attributes¶
- Org.Organization¶
Fundamental information for the organization itself (the root org unit).
{ "Identifier": <string:D2LID>, "Name": <string>, "TimeZone": <string:TimeZone> }
- TimeZone
Configured local time zone for the back-end Brightspace service.
Org units¶
- OrgUnitEditor.ColourScheme¶
{ "Dark": <string>, "Light": <string>, "Soft": <string> }
- OrgUnit.OrgUnit¶
Fundamental information for an org unit as reported by org unit service actions.
{ "Identifier": <string:D2LID>, "Name": <string>, "Code": <string>|null, "Type": { <composite:OrgUnit.OrgUnitTypeInfo> } }
- Code
In rare cases, an org unit may have no code set for it; in that case, you may get null for the code on actions that retrieve this structure. This is most likely to happen for the root organization org unit only.
- OrgUnit.OrgUnitProperties¶
{ "Identifier": <string:D2LID>, "Name": <string>, "Code": <string>|null, "Path": <string>, "Type": { <composite:OrgUnit.OrgUnitTypeInfo> } }
- Code
In rare cases, an org unit may have no code set for it; in that case, you may get null for the code on actions that retrieve this structure. This is most likely to happen for the root organization org unit only. You may never provide null when setting the code for an org unit.
Note
Note that only the Name, Code, and Path values are used by the back-end service on update actions.
- OrgUnit.OrgUnitCoreInfo¶
Encapsulates the core information associated with an org unit for use by other services (for example, the Dropbox related actions).
{ "Identifier": <string:D2LID>, "TypeIdentifier": <string>, "Name": <string>, "Code": <string>|null, "Path": <string>, "IsActive": <boolean>, "StartDate": <string:UTCDateTime>|null, "EndDate": <string:UTCDateTime>|null }
- Code
In rare cases, an org unit may have no code set for it; in that case, you may get null for the code on actions that retrieve this structure. This is most likely to happen for the root organization org unit only.
- StartDate, EndDate
These fields will have date-time values only for those org units that can have start and end times (for example, course offerings); otherwise, these fields will be null.
- OrgUnit.OrgUnitCreateData¶
Actions that create or update custom org units should provide data to the service in blocks that look like this:
{ "Type": <number:D2LID>, "Name": <string>, "Code": <string>, "Parents": [ <number:D2LID>, ... ] }
- Code
Note that org unit code values have these limitations:
They cannot be more than 50 characters in length.
They may not contain these special characters:
\ : * ? “ ” < > | ‘ # , % &
- Type
D2LID for the org unit’s associated org unit type.
- Parents
JSON array of Org unit IDs that identify this org unit’s immediate parent org units.
Org unit types¶
- OrgUnit.OrgUnitType¶
Actions that retrieve Org Unit Type information from the service receive blocks that look like this:
{ "Id": <number:D2LID>, "Code": <string>, "Name": <string>, "Description": <string>, "SortOrder": <number>, "Permissions": { <composite:OrgUnit.Permissions> } }
- OrgUnit.Permissions¶
{ "CanDelete": <boolean>, "CanEdit": <boolean> }
- OrgUnit.CreateOrgUnitTypeData¶
Actions that create or update custom org unit types should provide data to the service in blocks that look like this:
{ "Code": <string>, "Name": <string>, "Description": <string>, "SortOrder": <number> }
- OrgUnit.OrgUnitTypeInfo¶
Encapsulates the core information associated with an org unit type for use by other services (for example, the Enrollment and Course related actions).
{ "Id": <number:D2LID>, "Code": <string>, "Name": <string> }
Actions¶
- GET /d2l/api/lp/(version)/organization/info¶
Retrieve the organization properties information.
- Parameters:
version (D2LVERSION) – API version.
- Status Codes:
200 OK – Action succeeded.
404 Not Found – This organization hasn’t set its identifier and name.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Return. This action returns a
Organization
JSON data block containing the identifier, name, and time zone of the organization.Note
You can make this call anonymously.
If you’re using OAuth2, you do not need to provide an Authorization header (containing a bearer token) with your call.
If you’re using legacy ID-Key Authentication, you do not need to include the x_b and x_d query parameter values for this call. If you do provide user ID and user signature query parameter values with this call, you should ensure they are validly formed user tokens. This has the advantage of identifying the application making the call to this route.
- GET /d2l/api/lp/(version)/organization/primary-url¶
Retrieve the organization’s primary (root) URL.
- Parameters:
version (D2LVERSION) – API version.
- Status Codes:
200 OK – Action succeeded.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Return. This action does not return a JSON document; rather, it returns a simple text/plain body containing only the fully qualified root URL for this back end service.
Note
You can make this call anonymously.
If you’re using OAuth2, you do not need to provide an Authorization header (containing a bearer token) with your call.
If you’re using legacy ID-Key Authentication, you do not need to include the x_b and x_d query parameter values for these calls. If you do provide user ID and user signature query parameter values with these calls, you should ensure they are validly formed user tokens. This has the advantage of identifying the application making the call to these routes.
Structure¶
- DELETE /d2l/api/lp/(version)/orgstructure/(orgUnitId)/children/(childOrgUnitId)¶
Delete the relationship between a provided org unit and one of its children.
- Parameters:
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
childOrgUnitId (D2LID) – Org unit ID for the child to detach.
- Oauth2 Scopes:
organizations:organization:delete
- Status Codes:
200 OK – Action succeeded.
400 Bad Request – No permission to detach organization units.
403 Forbidden – No permission to edit organizational structure.
404 Not Found – Org unit not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
- DELETE /d2l/api/lp/(version)/orgstructure/(orgUnitId)/parents/(parentOrgUnitId)¶
Delete the relationship between a provided org unit and one of its parents.
- Parameters:
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
parentOrgUnitId (D2LID) – Org unit ID for the parent to detach.
- Oauth2 Scopes:
organizations:organization:delete
- Status Codes:
200 OK – Action succeeded.
400 Bad Request – No permission to detach organization units.
403 Forbidden – No permission to edit organizational structure.
404 Not Found – Org unit not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
- GET /d2l/api/lp/(version)/orgstructure/¶
Retrieve properties for all org units.
- Parameters:
version (D2LVERSION) – API version.
- Query Parameters:
orgUnitType (string) – Optional. Filter to org units with type matching this org unit type ID.
orgUnitCode (string) – Optional. Filter to org units with codes containing this substring.
orgUnitName (string) – Optional. Filter to org units with names containing this substring.
bookmark (string) – Optional. Bookmark to use for fetching next data set segment.
exactOrgUnitCode (string) – Optional. Filter to org units with codes precisely matching this string. Overrides orgUnitCode.
exactOrgUnitName (string) – Optional. Filter to org units with names precisely matching this string. Overrides orgUnitName.
- Oauth2 Scopes:
organizations:organization:read
- Status Codes:
200 OK – Action succeeded.
403 Forbidden – No permission to retrieve org units.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Input. You can use the orgUnitType, orgUnitCode, and orgUnitName query parameters as filters to further narrow the list of org units this action retrieves. Note that for orgUnitType, the back-end service expects to receive a valid org unit type ID value. Note that orgUnitCode and orgUnitName both will search for matches that contain your parameter value.
You can use the exactOrgUnitCode and exactOrgUnitName query parameters as more precise filters for narrowing down the list of org units. If you already know the exact code or name of the org unit in question, we recommend you use these filters instead of the more general ones.
Return. This action returns a
paged result set
containing the resultingOrgUnitProperties
blocks for the segment following your bookmark parameter (or the first segment if that parameter is empty or missing).
- GET /d2l/api/lp/(version)/orgstructure/(orgUnitId)¶
Retrieve the properties for a provided org unit.
- Parameters:
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
- Oauth2 Scopes:
organizations:organization:read
- Status Codes:
200 OK – Action succeeded.
403 Forbidden – No permission to organizational structure.
404 Not Found – Org unit not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Return. This action returns a
OrgUnit
JSON structure containing the properties for the provided org unit.
- GET /d2l/api/lp/(version)/orgstructure/childless/¶
Retrieve all org units that have no children.
- Parameters:
version (D2LVERSION) – API version.
- Query Parameters:
orgUnitType (string) – Optional. Filter to org units of this type.
orgUnitCode (string) – Optional. Filter to org units with codes containing this substring.
orgUnitName (string) – Optional. Filter to org units with names containing this substring.
bookmark (string) – Optional. Bookmark to use for fetching next data set segment.
- Oauth2 Scopes:
organizations:organization:read
- Status Codes:
200 OK – Action succeeded.
403 Forbidden – No permission to search for childless org units.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Input. You can use the orgUnitType, orgUnitCode, and orgUnitName query parameters as filters to further narrow the list of org units this action retrieves.
Return. This action returns a
paged result set
containing the resultingOrgUnitProperties
blocks for the segment following your bookmark parameter (or the first segment if that parameter is empty or missing).
- GET /d2l/api/lp/(version)/orgstructure/orphans/¶
Retrieve all org units that are orphans (have no parents).
- Parameters:
version (D2LVERSION) – API version.
- Query Parameters:
orgUnitType (string) – Optional. Filter to org units of this type.
orgUnitCode (string) – Optional. Filter to org units with codes containing this substring.
orgUnitName (string) – Optional. Filter to org units with names containing this substring.
bookmark (string) – Optional. Bookmark to use for fetching next data set segment.
- Oauth2 Scopes:
organizations:organization:read
- Status Codes:
200 OK – Action succeeded.
403 Forbidden – No permission to search for orphaned org units.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Input. You can use the orgUnitType, orgUnitCode, and orgUnitName query parameters as filters to further narrow the list of org units this action retrieves.
Return. This action returns a
paged result set
containing the resultingOrgUnitProperties
blocks for the segment following your bookmark parameter (or the first segment if that parameter is empty or missing).
- GET /d2l/api/lp/(version)/orgstructure/(orgUnitId)/ancestors/¶
Retrieve a list of ancestor-units for a provided org unit.
- Parameters:
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
- Query Parameters:
ouTypeId – Optional. Filter retrieved list by this org unit type.
- Oauth2 Scopes:
organizations:organization:read
- Status Codes:
200 OK – Action succeeded.
403 Forbidden – No permission to see organizational structure.
404 Not Found – Org unit not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Return. This action returns a JSON array of
OrgUnit
data blocks containing information about all the org units that are ancestors of the provided org unit.
- GET /d2l/api/lp/(version)/orgstructure/(orgUnitId)/children/¶
Retrieve a list of child-units for a provided org unit.
- Parameters:
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
- Query Parameters:
ouTypeId (D2LID) – Optional. Filter retrieved list by this org unit type.
- Oauth2 Scopes:
organizations:organization:read
- Status Codes:
200 OK – Action succeeded.
403 Forbidden – No permission to see organizational structure.
404 Not Found – Org unit not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Return. This action returns a JSON array of
OrgUnit
data blocks containing information about all the org units that are children of the provided org unit.Warning
An organization structure can grow to be a very large collection of nodes. We advise that you make very careful use of this API call because it asks for an unbounded set of results. We strongly recommend you use the
paged version of this call
instead.
- GET /d2l/api/lp/(version)/orgstructure/(orgUnitId)/children/paged/¶
Retrieve a list of child-units for a provided org unit.
- Parameters:
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
- Query Parameters:
ouTypeId (D2LID) – Optional. Filter retrieved list by this org unit type.
bookmark (string) – Optional. Bookmark to use for fetching the next data set segment.
- Oauth2 Scopes:
organizations:organization:read
- Status Codes:
200 OK – Action succeeded.
403 Forbidden – No permission to see organizational structure.
404 Not Found – Org unit not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Return. This action returns a
paged result set
containing the resulting org unit blocks for the segment following your bookmark parameter (or the first segment if that parameter is empty or missing).
- GET /d2l/api/lp/(version)/orgstructure/(orgUnitId)/descendants/¶
Retrieve a list of descendent-units for a provided org unit.
- Parameters:
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
- Query Parameters:
ouTypeId (D2LID) – Optional. Filter retrieved list by this org unit type.
- Oauth2 Scopes:
organizations:organization:read
- Status Codes:
200 OK – Action succeeded.
403 Forbidden – No permission to see organizational structure.
404 Not Found – Org unit not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Return. This action returns a JSON array of
OrgUnit
data blocks containing information about all the org units that are descendants of the provided org unit.Warning
An organization structure can grow to be a very large collection of nodes. We advise that you make very careful use of this API call because it asks for an unbounded set of results. We strongly recommend you use the
paged version of this call
instead.
- GET /d2l/api/lp/(version)/orgstructure/(orgUnitId)/descendants/paged/¶
Retrieve a list of descendent-units for a provided org unit.
- Parameters:
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
- Query Parameters:
ouTypeId (D2LID) – Optional. Filter retrieved list by this org unit type.
bookmark (string) – Optional. Bookmark to use for fetching the next data set segment.
- Oauth2 Scopes:
organizations:organization:read
- Status Codes:
200 OK – Action succeeded.
403 Forbidden – No permission to see organizational structure.
404 Not Found – Org unit not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Return. This action returns a
paged result set
containing the resulting org unit blocks for the segment following your bookmark parameter (or the first segment if that parameter is empty or missing).
- GET /d2l/api/lp/(version)/orgstructure/(orgUnitId)/parents/¶
Retrieve a list of parent-units for a provided org unit.
- Parameters:
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
- Query Parameters:
ouTypeId (D2LID) – Optional. Filter retrieved list by this org unit type.
- Oauth2 Scopes:
organizations:organization:read
- Status Codes:
200 OK – Action succeeded.
403 Forbidden – No permission to see organizational structure.
404 Not Found – Org unit not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Return. This action returns a JSON array of
OrgUnit
data blocks containing information about all the org units that are parents of the provided org unit.
- POST /d2l/api/lp/(version)/orgstructure/¶
Create a new custom org unit.
- Parameters:
version (D2LVERSION) – API version.
- JSON Parameters:
OrgUnitCreateData (
OrgUnit.OrgUnitCreateData
) – Data for new custom org unit.
- Oauth2 Scopes:
organizations:organization:create
- Status Codes:
200 OK – Action succeeded.
400 Bad Request – Invalid org structure creation data provided, or creation of specified org unit type not permitted in the called context, or specified parent org unit not allowed for specified org unit type.
403 Forbidden – No permission to edit organizational structure.
404 Not Found – Org unit not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Return. This action returns an
OrgUnit
JSON data block containing the properties for the newly created org unit.
- POST /d2l/api/lp/(version)/orgstructure/(orgUnitId)/children/¶
Give the provided org unit a new child org unit.
- Parameters:
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
- JSON Parameters:
OrgUnitId (D2LID as single JSON number) – Org unit to add as a child.
- Oauth2 Scopes:
organizations:organization:create
- Status Codes:
200 OK – Action succeeded.
400 Bad Request – No permission to attach org units.
403 Forbidden – No permission to edit organizational structure.
404 Not Found – Org unit not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Input. Note that you must pass a single JSON number in the body of this request; for example, if you want to add org unit with ID 1234 as a child of another org unit, your POST body would be:
1234
- POST /d2l/api/lp/(version)/orgstructure/(orgUnitId)/parents/¶
Give the provided org unit a new parent org unit.
- Parameters:
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
- JSON Parameters:
OrgUnitId (D2LID as single JSON number) – Org unit to add as a parent.
- Oauth2 Scopes:
organizations:organization:create
- Status Codes:
200 OK – Action succeeded.
400 Bad Request – No permission to attach org units.
403 Forbidden – No permission to edit organizational structure.
404 Not Found – Org unit not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Input. Note that you must pass a single JSON number in the body of this request; for example, if you want to add org unit with ID 1234 as a parent of another org unit, your POST body would be:
1234
- PUT /d2l/api/lp/(version)/orgstructure/(orgUnitId)¶
Update a custom org unit’s properties
- Parameters:
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit to update.
- JSON Parameters:
OrgUnitProperties (
OrgUnit.OrgUnitProperties
) – Data for new custom org unit.
- Oauth2 Scopes:
organizations:organization:update
- Status Codes:
200 OK – Action succeeded.
400 Bad Request – Invalid org unit properties provided.
403 Forbidden – No permission to edit organizational structure.
404 Not Found – Org unit not found, or invalid org unit properties provided.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Input. Note that you can only update the Name, Code, and Path properties; the values of the other proprties in the
OrgUnitProperties
you provide are not used to update your specified org unit.Return. This action returns an
OrgUnitProperties
JSON data block containing the properties for the newly created org unit.
Color schemes¶
- GET /d2l/api/lp/(version)/orgstructure/(orgUnitId)/colours¶
Retrieve the color scheme for an org unit.
- Parameters:
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
- Oauth2 Scopes:
organizations:organization:read
- Status Codes:
200 OK – Action succeeded.
403 Forbidden – No permission to view the colour scheme.
404 Not Found – Org unit not found, or colour scheme for org unit not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Return. This action returns a
ColourScheme
JSON data block containing the org unit’s current color scheme.
- PUT /d2l/api/lp/(version)/orgstructure/(orgUnitId)/colours¶
Set a new color scheme for an org unit.
- Parameters:
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
- JSON Parameters:
colourScheme (
OrgUnitEditor.ColourScheme
) – New colour scheme for org unit.
- Oauth2 Scopes:
organizations:organization:update
- Status Codes:
200 OK – Action succeeded.
400 Bad Request – Invalid colour scheme data.
403 Forbidden – No permission to modify the colour scheme.
404 Not Found – Org unit not found, or unable to assign colour scheme to org unit.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Return. This action returns a
ColourScheme
JSON data block containing the org unit’s new color scheme.
Recycle bin¶
- DELETE /d2l/api/lp/(version)/orgstructure/recyclebin/(orgUnitId)¶
Permanently delete an org unit from the recycle bin.
- Parameters:
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
- Oauth2 Scopes:
organizations:organization:delete
- Status Codes:
200 OK – Action succeeded.
403 Forbidden – No permission to delete org unit.
404 Not Found – Org unit not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Note
You can only delete an org unit using this action if the org unit has already been sent to the recycle bin.
- GET /d2l/api/lp/(version)/orgstructure/recyclebin/¶
Retrieve all the org units currently in the recycle bin.
- Parameters:
version (D2LVERSION) – API version.
- Query Parameters:
bookmark (string) – Optional. Bookmark to use for fetching the next data set segment.
- Oauth2 Scopes:
organizations:organization:read
- Status Codes:
200 OK – Action succeeded.
403 Forbidden – No permission to see recycle bin contents.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Return. This action returns a
paged result set
containing the resultingOrgUnitProperties
blocks for the segment following your bookmark parameter (or the first segment if that parameter is empty or missing).
- POST /d2l/api/lp/(version)/orgstructure/recyclebin/(orgUnitId)/recycle¶
Send an org unit to the recycle bin.
- Parameters:
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
- Oauth2 Scopes:
organizations:organization:create
- Status Codes:
200 OK – Action succeeded.
400 Bad Request – No permission to recycle org unit with children, or unable to recycle org unit.
403 Forbidden – No permission to recycle an org unit.
404 Not Found – Org unit not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Note
Using this action has the same effect as deleting the org unit via the OrgUnit Editor (and placing it in the recycling bin) in the Brightspace UI.
- POST /d2l/api/lp/(version)/orgstructure/recyclebin/(orgUnitId)/restore¶
Restore an org unit from the recycle bin.
- Parameters:
version (D2LVERSION) – API version.
orgUnitId (D2LID) – Org unit ID.
- Oauth2 Scopes:
organizations:organization:create
- Status Codes:
200 OK – Action succeeded.
403 Forbidden – No permission to restore org unit.
404 Not Found – Org unit not found in the recycle bin.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Types¶
- DELETE /d2l/api/lp/(version)/outypes/(orgUnitTypeId)¶
Delete a particular org unit type.
- Parameters:
version (D2LVERSION) – API version.
orgUnitTypeId (D2LID) – Org unit type ID.
- Status Codes:
200 OK – Action succeeded.
400 Bad Request – Unable to delete org unit type at this time (a service component depends upon it).
403 Forbidden – No permission to delete org unit types, or attempt to delete built-in org unit type
404 Not Found – Org unit type not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
- GET /d2l/api/lp/(version)/outypes/¶
Retrieve all the known and visible org unit types.
- Parameters:
version (D2LVERSION) – API version.
- Status Codes:
200 OK – Action succeeded.
403 Forbidden – No permission to see org unit types.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Return. This action returns a JSON array of
OrgUnitType
JSON data blocks containing information for all the known and visible org unit types. This action will not provide any of the not-visible org unit types.
- GET /d2l/api/lp/(version)/outypes/(orgUnitTypeId)¶
Retrieve information about a particular org unit type.
- Parameters:
version (D2LVERSION) – API version.
orgUnitTypeId (D2LID) – Org unit type ID.
- Status Codes:
200 OK – Action succeeded.
403 Forbidden – No permission to see org unit types.
404 Not Found – Org unit type not found, or not visible.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Return. This action returns a
OrgUnitType
JSON data block containing the properties of the specified org unit type.
- GET /d2l/api/lp/(version)/outypes/department¶
Retrieve the org unit type information for department org units.
- Parameters:
version (D2LVERSION) – API version.
- Status Codes:
200 OK – Action succeeded.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Return. This action returns a
OrgUnitType
JSON data block containing the properties of the built-in department org unit type.
- GET /d2l/api/lp/(version)/outypes/semester¶
Retrieve the org unit type information for semester org units.
- Parameters:
version (D2LVERSION) – API version.
- Status Codes:
200 OK – Action succeeded.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Return. This action returns a
OrgUnitType
JSON data block containing the properties of the built-in semester org unit type.
- POST /d2l/api/lp/(version)/outypes/¶
Create a new custom org unit type.
- Parameters:
version (D2LVERSION) – API version.
- JSON Parameters:
CreateOrgUnitTypeData (
OrgUnit.CreateOrgUnitTypeData
) – Data for new custom org unit type.
- Status Codes:
200 OK – Action succeeded.
400 Bad Request – Invalid org unit type data provided.
403 Forbidden – No permission to create org unit types.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Return. This action returns a
OrgUnitType
JSON data block containing the current properties for the new custom org unit type.
- POST /d2l/api/lp/(version)/outypes/(orgUnitTypeId)¶
Update a particular org unit type.
- Parameters:
version (D2LVERSION) – API version.
orgUnitTypeId (D2LID) – Org unit type ID.
- JSON Parameters:
CreateOrgUnitTypeData (
OrgUnit.CreateOrgUnitTypeData
) – Updated data for custom org unit type.
- Status Codes:
200 OK – Action succeeded.
400 Bad Request – Invalid org unit type data provided.
403 Forbidden – No permission to edit org unit types, or org unit type is built-in.
404 Not Found – Org unit type not found.
429 Too Many Requests – API call-rate limit exceeded.
- API Versions:
1.43+ – Route first appears in LMS v20.23.5.
1.35-1.42 – Deprecated as of LMS v20.24.1.
1.34- – Obsolete as of LMS v20.24.1.
Return. This action returns a
OrgUnitType
JSON data block containing the current, updated properties for the custom org unit type.