For AI agents: an index of this documentation is at https://developer.rippling.com/llms.txt. Public pages have a Markdown version at the same URL with .md added.

Skip to main content
guide

Create and manage business structures

Fetch, create, and delete company business structure paths using the Business Structures API.

Use with AI:Rippling AI ChatGPT Claude Cursor

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​

EndpointDescription
GET List business structure pathsLists business structure paths.
POST Create a new business structure pathCreates 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 pathRetrieves a specific path by id.
DELETE Delete a business structure pathDeletes a path and every path nested under it.

Related endpoints:

EndpointDescription
GET List job codesLists existing job codes.
POST Create a new job codeCreates a new job code housed within a job dimension.
GET List job dimensionsLists existing job dimensions.
POST Create a new job dimensionCreates a new job dimension.

Suggested workflow​

  1. List existing job codes or create a new job code. A business structure path can only reference existing job codes.
  2. Create a root path with job_code_id and no parent_id.
  3. List business structure paths to grab the parent_id (id) of the new path.
  4. Create child paths with a new job_code_id and the id from GET List business structure paths as the parent_id. Job codes in the same dimension cannot be used in one path.
  5. Retrieve a specific path when you already have the id.
  6. 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.read to list and retrieve paths
    • business-structure-paths.read-write to create or delete paths
    • job-codes.read if you expand job_codes, job-dimensions.read and job-codes.read-write if 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 fieldDescription
idUnique identifier of the path. Used as parent_id when creating child paths from a root.
namePath label, job codes from top to bottom, joined with >.
parent_idParent path. Empty on a root path.
parentParent path object. Populate with ?expand=parent.
job_codes_idOrdered job code IDs from the top of the path to this node.
job_codesFull 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 fieldRequiredDescription
job_code_idYesJob code to place in this path. Fetch from GET List job codes.
parent_idNoParent 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.


See also​