Overview
A business structure is a tree of paths across job and organizational dimensions. Each path is an ordered combination of job codes, such as Work Location > Department > Project > Task.
Job dimensions and job codes can exist independently of business structures, but a business structure designates which combinations can be used together in certain Rippling products, such as Time & Attendance or Scheduling.
Key terms:
- Business structure path: An ordered combination of existing job codes across different job dimensions.
- Path name: The display name of the business structure path (e.g., SF Office > Coffee > Barista).
- Job dimension: A category you track, such as Work Location, Department, Project, or Task.
- Job code: A value inside a dimension, such as “SF Office” or “Barista.”
Available endpoints
| Endpoint | Description |
|---|---|
| GET List business structure paths | Lists business structure paths. |
| POST Create a new business structure path | Creates a new business structure path. Can create a root path (no parent) or add a new path under an existing parent. |
| GET Retrieve a specific business structure path | Retrieves a specific path by id. |
| DELETE Delete a business structure path | Deletes a path and every path nested under it. |
Related endpoints:
| Endpoint | Description |
|---|---|
| GET List job codes | Lists existing job codes. |
| POST Create a new job code | Creates a new job code housed within a job dimension. |
| GET List job dimensions | Lists existing job dimensions. |
| POST Create a new job dimension | Creates a new job dimension. |
Suggested workflow
- List existing job codes or create a new job code. A business structure path can only reference existing job codes.
- Create a root path with
job_code_idand noparent_id. - List business structure paths to grab the
parent_id(id) of the new path. - Create child paths with a new
job_code_idand theidfrom GET List business structure paths as theparent_id. Job codes in the same dimension cannot be used in one path. - Retrieve a specific path when you already have the
id. - Delete a path only when you intend to remove that node and every path beneath it.
Requirements
- The Rippling API SKU
- An API token with the following scopes:
business-structure-paths.readto list and retrieve pathsbusiness-structure-paths.read-writeto create or delete pathsjob-codes.readif you expandjob_codes,job-dimensions.readandjob-codes.read-writeif you create the dimensions and job codes first
Fetch
Use GET List business structure paths to return a paginated list of all paths.
Request:
curl -L -X GET 'https://rest.ripplingapis.com/business-structure-paths/'
-H 'Accept: application/json'
-H 'Authorization: Bearer REDACTED'
Response:
{
"results": [
{
"id": "6ac3efbc1472d3944138d49c",
"created_at": "2026-08-28T16:00:00.000000+00:00",
"updated_at": "2026-08-28T16:00:00.000000+00:00",
"name": "SF Office > Barista",
"parent_id": "6ac3ef9386800436c638d450",
"parent": null,
"job_codes_id": [
"6ac3ea9a2d5fd9f9bbf3143e",
"682b62564756e8dd608c3ddb"
],
"job_codes": null
}
],
"next_link": null
}
| Response field | Description |
|---|---|
id | Unique identifier of the path. Used as parent_id when creating child paths from a root. |
name | Path label, job codes from top to bottom, joined with >. |
parent_id | Parent path. Empty on a root path. |
parent | Parent path object. Populate with ?expand=parent. |
job_codes_id | Ordered job code IDs from the top of the path to this node. |
job_codes | Full job code objects in that same order. Populate with ?expand=job_codes. Requires the job-codes.read scope. |
Use GET Retrieve a specific business structure path when you already have the path ID.
Create
Create a new business structre path using POST Create a new business structure path. First create the root using no parent_id, then create each child path using separate job code IDs.
| Request body field | Required | Description |
|---|---|---|
job_code_id | Yes | Job code to place in this path. Fetch from GET List job codes. |
parent_id | No | Parent path id. Omit to create a root path. |
Root path
Request:
curl -L -X POST 'https://rest.ripplingapis.com/business-structure-paths/'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer REDACTED'
Request body:
{
"job_code_id": "6ac3ea9a2d5fd9f9bbf3143e"
}
Response:
{
"id": "6ac3ef9386800436c638d450",
"created_at": "2026-08-28T16:00:00.000000+00:00",
"updated_at": "2026-08-28T16:00:00.000000+00:00",
"name": "SF Office",
"parent_id": null,
"job_codes_id": [
"6ac3ea9a2d5fd9f9bbf3143e"
]
}
Child path
Use the id from the root path's response for the parent_id.
Request body:
{
"job_code_id": "682b62564756e8dd608c3ddb",
"parent_id": "6ac3ef9386800436c638d450"
}
Response:
{
"id": "6ac3efbc1472d3944138d49c",
"created_at": "2026-08-28T16:05:00.000000+00:00",
"updated_at": "2026-08-28T16:05:00.000000+00:00",
"name": "SF Office > Barista",
"parent_id": "6ac3ef9386800436c638d450",
"job_codes_id": [
"6ac3ea9a2d5fd9f9bbf3143e",
"682b62564756e8dd608c3ddb"
]
}
Delete
Use DELETE Delete a business structure path to remove a path and every path nested under it. Job codes referenced by deleted paths are not deleted/archived and still available for use in Rippling.
Request:
curl -L -X DELETE 'https://rest.ripplingapis.com/business-structure-paths/6ac3efbc1472d3944138d49c/'
-H 'Accept: application/json'
-H 'Authorization: Bearer REDACTED'
A successful delete returns 200 and no body.