Quick Start: Get an OU

With the new OU API, we support several different methods of fetching by OU, by:

• id
• externalId
• typeId
• name

Typically, you will want to list OUs by type; e.g., "I want to see all my divisions" and additional details for each one of those OUs. This will require three steps:

1. Identify the type of OUs to lookup
2. Request the list of OUs
3. Finally, get details of a single OU

Step 1: Identify the type of OUs to lookup

We'll start by requesting a list of all OU types. The response should look similar across all OU types, with the exception of location which has one extra object for facilityType.

GET /services/api/x/organizations/v1/types
HTTP/1.1
Host: {your portal}.csod.com
Authorization: Bearer {your oauth2 token}

From the response, notice the ID of "Division" which we'll be using to fetch our OUs. This ID will not change for a given OU type. You may want to store the mapping of the id to the OU type locally on your end to reduce an API call.

// 200 OK
{
    "timestamp": "2020-04-27T11:31:19.7945188-07:00",
    "pageNumber": 1,
    "count": 10,
    "data": [
        {
            "id": 1,
            "name": "Corporation",
            "description": null,
            "details": {
                "required": false
            }
        },
        {
            "id": 2,
            "name": "Division",
            "description": "",
            "details": {
                "required": true
            }
        },
        {
            "id": 4,
            "name": "Position",
            "description": "",
            "details": {
                "required": true
            }
        }
	...
    ]
}

Step 2: Request the list of OUs

Once we've fetched the OU types, we can make a request to fetch all OUs of that type. For this example, we'll request all "Division" OUs, which is ID '2' as seen above. Using typeId=2 as a query parameter, we'll make our call:

GET /services/api/x/organizations/v1/ous?typeId=2
HTTP/1.1
Host: {your portal}.csod.com
Authorization: Bearer {your oauth2 token}

This will return a list of all of our divisions OUs:

// 200 OK
{
    "timestamp": "2020-04-27T13:02:18.5974798-07:00",
    "pageNumber": 1,
    "count": 2,
    "data": [
        {
            "id": 119,
            "active": true,
            "name": "Product Division",
            "externalId": "d00119 ",
            "typeId": 2,
            "ownerId": null,
            "description": "The Product Division",
            "parentId": 1,
            "reconcilable": false
        },
        {
            "id": 131,
            "active": true,
            "name": "Customer Service Division",
            "externalId": "d00131 ",
            "typeId": 2,
            "ownerId": 101,
            "description": "The Customer service Division",
            "parentId": 1,
            "reconcilable": false
        }
    ]
}

Step 3: Get the details for a single OU

Using the list of divisions we retrieved, we can look at the details for one OU in specific. We'll use ID 131, the "Customer Service Division" above:

GET /services/api/x/organizations/v1/ous/131
HTTP/1.1
Host: {your portal}.csod.com
Authorization: Bearer {your oauth2 token}

This will return all details, including custom fields for this division:

// 200 OK
{
    "typeId": 2,
    "active": true,
    "name": "Customer Service Division",
    "externalId": "d00131",
    "ownerId": 101,
    "description": "The customer service division",
    "parentId": 1,
    "reconcilable": true,
    "customFields": [
        {
            "id": 579,
            "value": "268"
        },
        {
            "id": 575,
            "value": "100000"
        }
    ]
}