# Create and manage business structures

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

## 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](https://developer.rippling.com/documentation/rest-api/reference/list-business-structure-paths) | Lists business structure paths. |
| [POST Create a new business structure path](https://developer.rippling.com/documentation/rest-api/reference/create-business-structure-paths) | 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](https://developer.rippling.com/documentation/rest-api/reference/get-business-structure-paths) | Retrieves a specific path by `id`. |
| [DELETE Delete a business structure path](https://developer.rippling.com/documentation/rest-api/reference/delete-business-structure-paths) | Deletes a path and every path nested under it. |

Related endpoints:

| Endpoint | Description |
| --- | --- |
| [GET List job codes](https://developer.rippling.com/documentation/rest-api/reference/list-job-codes) | Lists existing job codes. |
| [POST Create a new job code](https://developer.rippling.com/documentation/rest-api/reference/create-job-codes) | Creates a new job code housed within a job dimension. |
| [GET List job dimensions](https://developer.rippling.com/documentation/rest-api/reference/list-job-dimensions) | Lists existing job dimensions. |
| [POST Create a new job dimension](https://developer.rippling.com/documentation/rest-api/reference/create-job-dimensions) | Creates a new job dimension. |

### Suggested workflow

1.  [List existing job codes](https://developer.rippling.com/documentation/rest-api/reference/list-job-codes) or [create a new job code](https://developer.rippling.com/documentation/rest-api/reference/create-job-codes). A business structure path can only reference existing job codes.
2.  [Create a root path](https://developer.rippling.com/documentation/rest-api/reference/create-business-structure-paths) with `job_code_id` and no `parent_id`.
3.  [List business structure paths](https://developer.rippling.com/documentation/rest-api/reference/list-business-structure-paths) to grab the `parent_id` (`id`) of the new path.
4.  [Create child paths](https://developer.rippling.com/documentation/rest-api/reference/create-business-structure-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](https://developer.rippling.com/documentation/rest-api/reference/get-business-structure-paths) when you already have the `id`.
6.  [Delete a path](https://developer.rippling.com/documentation/rest-api/reference/delete-business-structure-paths) 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](https://developer.rippling.com/documentation/rest-api/reference/list-business-structure-paths) to return a paginated list of all paths.

_Request:_

```json
curl -L -X GET 'https://rest.ripplingapis.com/business-structure-paths/'
-H 'Accept: application/json'
-H 'Authorization: Bearer REDACTED'
```

_Response:_

```json
{
  "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](https://developer.rippling.com/documentation/rest-api/reference/get-business-structure-paths) when you already have the path ID.

* * *

## Create

Create a new business structre path using [POST Create a new business structure path](https://developer.rippling.com/documentation/rest-api/reference/create-business-structure-paths). 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](https://developer.rippling.com/documentation/rest-api/reference/list-job-codes). |
| `parent_id` | No | Parent path `id`. Omit to create a root path. |

### Root path

_Request:_

```json
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:_

```json
{
  "job_code_id": "6ac3ea9a2d5fd9f9bbf3143e"
}
```

_Response:_

```json
{
  "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:_

```json
{
  "job_code_id": "682b62564756e8dd608c3ddb",
  "parent_id": "6ac3ef9386800436c638d450"
}
```

_Response:_

```json
{
  "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](https://developer.rippling.com/documentation/rest-api/reference/delete-business-structure-paths) 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:_

```json
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

-   [Get started with the Organizational Data API](https://developer.rippling.com/documentation/rest-api/guides/org-data-getting-started)
-   [Overview of a business structure](https://help.rippling.com/article?articleId=5LZpHIc6h1IlSpFFivYJyY)
-   [Create and edit your company’s business structure](https://help.rippling.com/article?articleId=NqEZsGqO8BiKdVzBJ1zy4)
-   [Bulk import your company’s business structure](https://help.rippling.com/article?articleId=6kLCRqURGVafWZidoyw0SY)

Source: https://developer.rippling.com/documentation/rest-api/guides/business-structures

> For the complete documentation index, see [llms.txt](https://developer.rippling.com/llms.txt). Public pages have a Markdown version at the same URL with .md added.
