Developer Platform (April 2024)

Organization structure (Org units, structure)

«  Enrollments   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Discussions (forums, topics, posts)  »

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:
Status Codes:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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:
Status Codes:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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:
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:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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 resulting OrgUnitProperties 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:
Oauth2 Scopes:

organizations:organization:read

Status Codes:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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:
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.42Deprecated 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 resulting OrgUnitProperties 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:
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:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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 resulting OrgUnitProperties 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:
Query Parameters:
  • ouTypeId – Optional. Filter retrieved list by this org unit type.

Oauth2 Scopes:

organizations:organization:read

Status Codes:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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:
Query Parameters:
  • ouTypeId (D2LID) – Optional. Filter retrieved list by this org unit type.

Oauth2 Scopes:

organizations:organization:read

Status Codes:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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:
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:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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:
Query Parameters:
  • ouTypeId (D2LID) – Optional. Filter retrieved list by this org unit type.

Oauth2 Scopes:

organizations:organization:read

Status Codes:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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:
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:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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:
Query Parameters:
  • ouTypeId (D2LID) – Optional. Filter retrieved list by this org unit type.

Oauth2 Scopes:

organizations:organization:read

Status Codes:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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:
JSON Parameters:
Oauth2 Scopes:

organizations:organization:create

Status Codes:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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:
JSON Parameters:
  • OrgUnitId (D2LID as single JSON number) – Org unit to add as a child.

Oauth2 Scopes:

organizations:organization:create

Status Codes:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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:
JSON Parameters:
  • OrgUnitId (D2LID as single JSON number) – Org unit to add as a parent.

Oauth2 Scopes:

organizations:organization:create

Status Codes:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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:
Oauth2 Scopes:

organizations:organization:update

Status Codes:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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.

Colour schemes

GET /d2l/api/lp/(version)/orgstructure/(orgUnitId)/colours

Retrieve the colour scheme for an org unit.

Parameters:
Oauth2 Scopes:

organizations:organization:read

Status Codes:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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 colour scheme.

PUT /d2l/api/lp/(version)/orgstructure/(orgUnitId)/colours

Set a new colour scheme for an org unit.

Parameters:
JSON Parameters:
Oauth2 Scopes:

organizations:organization:update

Status Codes:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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 colour scheme.

Recycle bin

DELETE /d2l/api/lp/(version)/orgstructure/recyclebin/(orgUnitId)

Permanently delete an org unit from the recycle bin.

Parameters:
Oauth2 Scopes:

organizations:organization:delete

Status Codes:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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:
Query Parameters:
  • bookmark (string) – Optional. Bookmark to use for fetching the next data set segment.

Oauth2 Scopes:

organizations:organization:read

Status Codes:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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 OrgUnitProperties 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:
Oauth2 Scopes:

organizations:organization:create

Status Codes:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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:
Oauth2 Scopes:

organizations:organization:create

Status Codes:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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:
Status Codes:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated as of LMS v20.24.1.

  • 1.34-Obsolete as of LMS v20.24.1.

GET /d2l/api/lp/(version)/outypes/department

Retrieve the org unit type information for department org units.

Parameters:
Status Codes:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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:
Status Codes:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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:
JSON Parameters:
Status Codes:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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:
Status Codes:
API Versions:
  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42Deprecated 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.

«  Enrollments   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Discussions (forums, topics, posts)  »