3.2 Working With Organizational Units Via API

Verb

Address

Notes

Additional Details

GET

/orgs

/orgs?page=X

&page_size=Y

Retrieves a paginated list of all OUs, up to Y at a time, along with their basic attributes. A default page size of 25 is used.

The beginning of each response includes a count and a link to the next page. Each entry in the list has a link to itself, which can be used to retrieve that individual OU, as well as links to its associated permissions, child OUs, and hosts.

GET

/orgs/<id>

Retrieves an OU, or “Not found.”

GET

/orgs/<id>/children

&page_size=Y

Returns an array of child OUs.

Each one includes links to itself, its permissions, children and hosts.

GET

/orgs/<id>/perms

/orgs/<id>/perms?page=X

&page_size=Y

Returns a (possibly paginated) list of permissions associated with the OU.

GET

/orgs/<id>hosts

/orgs/<id>/hosts?page=X

&page_size=Y

Returns a (possibly paginated) list of hosts associated with the OU, along with their basic attributes.

POST

/orgs

Creates a new OU. Returns the newly created OU. Note that the code and parent fields are case-sensitive.

body: {

  “code”: string,

  “name”: string,

  “parent”: string (parent code)*,

  “parent_name”: string*,

  “parent_long_name”: string*

}

*Include only one of these three optional fields to specify the parent OU, if needed.

PUT

/orgs/<id>

Updates (replaces) existing OU. Returns the OU.

Include the code and name along with any fields which you want to change.

DELETE

/orgs/<id>

Removes the organizational unit. No content is returned.

If you attempt to remove an OU which has children, an error is returned. You will need to first remove the children or reassign them to another parent.

GET

/orgs?search=string

&page_size=Y

Returns OU objects matching the search string.

Useful for testing.