# Quick Start: Create an OU
Creating an OU will require several calls:
- Determine the Type of OU
- Retrieve type-specific custom fields
- Resolve references
- Create the OU record
For type-specific information in steps 1 and 2, you may want to cache the response data on your end for a period of time since these don't change as often.
For this example, we'll be walking through the steps to create a division OU.
# Step 1: Determine the type of OU
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}
This will return the response:
// 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: Retrieve custom fields metadata
From our previous call, we're only interested in the type Division
...
{
"id": 2,
"name": "Division",
"description": "",
"details": {
"required": true
}
}
...
Using the id returned here, we can retrieve additional details with the following call:
GET /services/api/x/organizations/v1/types/2 HTTP/1.1
Host: {your portal}.csod.com
Authorization: Bearer {your oauth2 token}
The response to this request will include additional type-specific information, including any custom fields that can be used for the call:
// 200 OK
{
"timestamp": "2020-04-27T11:53:17.6646931-07:00",
"data": {
"typeId": 2,
"name": "Division",
"description": "",
"details": {
"required": true
},
"customFields": [
{
"id": 579,
"name": "Client Facing",
"type": "RadioButton",
"required": false,
"options": [
{
"id": 268,
"title": "Yes"
},
{
"id": 269,
"title": "No"
}
]
},
{
"id": 576,
"name": "Scrolling Text Box Field 1",
"type": "LocalizedScrollingTextBox",
"required": false
},
{
"id": 575,
"name": "Numeric Field 1",
"type": "NumericField",
"required": false
},
{
"id": 574,
"name": "Dropdown Field 1",
"type": "Dropdown",
"required": false,
"options": [
{
"id": 265,
"title": "Drop down value 1"
},
{
"id": 266,
"title": "Drop down value 2"
}
]
}
]
}
}
# Step 3: Resolving references
Since most of the time, we're not creating top-level OUs, we need to take a moment to resolve the references we'll be using for creating this OU. Specifically, we need the ownerId of the user who will own the OU, and the parentId of the OU that will take the parent relationship.
We'll start by retrieving the parent OU:
GET /services/api/x/organizations/v1/ous?typeId=2&externalId=d00234 HTTP/1.1
Host: {your portal}.csod.com
Authorization: Bearer {your oauth2 token}
From the response, we're looking for the id field to use as the parentId for our OU:
// 200 OK
{
"timestamp": "2020-04-27T13:02:18.5974798-07:00",
"pageNumber": 1,
"count": 1,
"data": [
{
"id": 186,
"active": true,
"name": "Engineering Division",
"externalId": "d00234",
"typeId": 2,
"ownerId": null,
"description": "The Engineering Division",
"parentId": 1,
"reconcilable": false
}
]
}
As you can see above, the id for our parent division is 186.
This leaves us with retrieving our owner ID. We can retrieve the owner by following the [Quick Start Guide: Get an Employee] (https://csod.dev/guides/core-hr/employee-ou/quick-start-get-employee.html). Here again, we'll look for John Swift, with externalId jswift1822.
GET /services/api/x/users/v2/employees?externalId=jswift1822
HTTP/1.1
Host: {your portal}.csod.com
Authorization: Bearer {your oauth2 token}
This returns us the following:
// 200 OK
[
{
"id": 5646543,
"externalId": "jswift1822",
"userName": "johnathan.swift",
"guid": "97eaec4f-77d8-4765-acee-d7b7312b9140",
"firstName": "Johnathan",
"lastName": "Swift",
"primaryEmail": "johnathanswift@csod.com",
"workPhone": "4245551234",
"address": {
"country": "US",
"line1": "1601 Cloverfield Blvd",
"city": "Santa Monica",
"state": "CA",
"zipCode": "90404"
},
"workerStatus": {
"lastHireDate": "2008-07-04",
"originalHireDate": "2018-12-31",
"active": true,
"absent": false
},
"settings": {
"displayLanguage": "en-US",
"timeZone": "(UTC-08:00) Pacific Time (US & Canada)",
"trainingApprovals": 2
},
"managerId": 37,
"approverId": 38,
"employeeMetaData": {
"createdDate": "2008-07-02T06:33:02.000Z",
"modifiedDate": "2019-03-14T14:11:01.000Z"
}
}
]
This gives us our second reference id, 5646543.
# Step 4: Create the OU record
So far, we've gathered 3 different IDs required for creating our OU. We have:
typeId: 2parentId: 186ownerId: 5646543
Additionally, we've fetched our OU-specific custom fields. We'll use the field "Client-Facing" here.
{
"id": 579,
"name": "Client Facing",
"type": "RadioButton",
"required": false,
"options": [
{
"id": 268,
"title": "Yes"
},
{
"id": 269,
"title": "No"
}
]
}
...
For this exercise, we'll create a division that is NOT client-facing, so we'll use with the value 269.
With this data ready, we can POST a new OU.
POST /services/api/x/organizations/v1/ous HTTP/1.1
Host: {your portal}.csod.com
Authorization: Bearer {your oauth2 token}
{
"typeId": 2,
"active": true,
"name": "Instegration and Services",
"externalId": "d04523",
"ownerId": 5646543,
"description": "The Instegration and Services division",
"parentId": 186,
"reconcilable": true,
"customFields": [
{
"id": 579,
"value": "269"
}
]
}
We can now refer to the OU by the link provided in the response:
// 201 Created
{
"id": 9025,
"links": {
"href": "/v1/ous/9025"
}
}