Quick Start: Update an OU

Continuing from the example we used in the Quick Start: Create an OU section, you might have noticed that we made a typo when we created the Division - "Instegration and services" should be Integration and Services". We will fix that typo in this example by updating the OU.

For OUs, we have two ways to update OU data: PUT or PATCH. Each of these has a different experience that goes into it, but in short, a PUT will fully update/replace the data in the system, a PATCH only updates the data specified. We'll go through both methods here.

PATCH OU

Since we know what data we want to update, and we still have the OU ID available (9025), we'll just need to make one simple request:

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

{
    "name": "Integration and Services",
    "description": "The Integration and Services division"
}

If our request is successful, we'll see the following response:

204 No Content

This indicates that the request went through successfully, and our OU is updated.

PUT OU

Alternatively, we can make this update by using the PUT method. To do so, we'll need the OU ID (which we have above), and the values for the OU that will need to remain the same. So we have two steps:

1. Get OU details
2. Update the OU

Step 1: Get OU details

We'll start by making the same GET request we have several times now for OU ID 9025 (the value returned from our POST call):

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

In turn, this will return the details on the OU we just created.

// 200 OK
{
    "typeId": 2,
    "active": true,
    "name": "Instegration and Services",
    "externalId": "d04523",
    "ownerId": 123,
    "description": "The Instegration and Services division",
    "parentId": 186,
    "reconcilable": true,
    "customFields": [
        {
            "id": 579,
            "value": "269"
        }
    ]
}

Since the only values we want to update are name and description, we'll make the PUT call using the existing body, modifying just those two pieces.

Step 2: Update the OU

Now we're ready to update our OU. We'll do a put request, which completely replaces the OU data, which is why we have to submit the entire OU body:

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

{
    "typeId": 2,
    "active": true,
    "name": "Integration and Services",
    "externalId": "d04523",
    "ownerId": 123,
    "description": "The Integration and Services division",
    "parentId": 186,
    "reconcilable": true,
    "customFields": [
        {
            "id": 579,
            "value": "269"
        }
    ]
}

If successful, this will return the response:

204 No Content

Note that if the entire OU payload is not submitted in a PUT request, any data for fields that are NOT supplied WILL be deleted.