# Create and manage business partners

> Fetch, create, and delete company business partners and business partner groups using the Business Partners API.

## Overview

A **business partner** is an employee or group of employees aligned to a specific group. That particular group is a **business partner group**, for example, HR, IT, Finance, or Payroll.

Business partners and business partner groups allow you to create custom relationships within your organization beyond an employee’s reporting chain or an employee attribute (e.g., department or team). They can be used for managing access, receiving alerts, approving changes, or anywhere you define a supergroup.

For example:

-   Manager business partners receive permissions to edit only their aligned client group’s employment data.
-   Finance business partners receive expense approval requests for anyone in their client group that tries to expense more than $500.
-   HR business partners can verify new hires’ I-9s.

_Key terms:_

-   **Business partner group**: A group with a domain: `HR`, `IT`, `FINANCE`, `RECRUITING`, or `OTHER`.
-   **Business partner**: A worker in that group.
-   **Default business partner**: Optional worker in the group. Employees who are not explicitly mapped to a partner in the group will be mapped to this worker instead.
-   **Client group**: The set of workers explicitly mapped to a partner.

### Available endpoints

| Endpoint | Description |
| --- | --- |
| [GET List business partner groups](https://developer.rippling.com/documentation/rest-api/reference/list-business-partner-groups) | Lists groups. |
| [POST Create a new business partner group](https://developer.rippling.com/documentation/rest-api/reference/create-business-partner-groups) | Creates a group. `name` is required. |
| [GET Retrieve a specific business partner group](https://developer.rippling.com/documentation/rest-api/reference/get-business-partner-groups) | Retrieves one group by `id`. |
| [DELETE Delete a business partner group](https://developer.rippling.com/documentation/rest-api/reference/delete-business-partner-groups) | Deletes a group. |
| [GET List business partners](https://developer.rippling.com/documentation/rest-api/reference/list-business-partners) | Lists partners. |
| [POST Create a new business partner](https://developer.rippling.com/documentation/rest-api/reference/create-business-partners) | Creates a partner. `business_partner_group_id` and `worker_id` are required. |
| [GET Retrieve a specific business partner](https://developer.rippling.com/documentation/rest-api/reference/get-business-partners) | Retrieves one partner by `id`. |
| [DELETE Delete a business partner](https://developer.rippling.com/documentation/rest-api/reference/delete-business-partners) | Deletes a partner. |

Related endpoints:

| Endpoint | Description |
| --- | --- |
| [GET List workers](https://developer.rippling.com/documentation/rest-api/reference/list-workers) | Use `id` as `worker_id` or `default_business_partner_id`. |

### Suggested workflow

1.  [List business partner groups](https://developer.rippling.com/documentation/rest-api/reference/list-business-partner-groups) or [create a business partner group](https://developer.rippling.com/documentation/rest-api/reference/create-business-partner-groups) with a `name` and a `domain`.
2.  [List workers](https://developer.rippling.com/documentation/rest-api/reference/list-workers) and choose the worker who will be the business partner.
3.  [Create a business partner](https://developer.rippling.com/documentation/rest-api/reference/create-business-partners) with that group's `id` and the worker `id`.
4.  [List business partners](https://developer.rippling.com/documentation/rest-api/reference/list-business-partners) with `expand=worker,business_partner_group` to confirm the assignment.
5.  [Delete a business partner](https://developer.rippling.com/documentation/rest-api/reference/delete-business-partners) to remove that worker from the group or [delete a business partner group](https://developer.rippling.com/documentation/rest-api/reference/delete-business-partner-groups) to remove the group.

* * *

## Requirements

-   The Rippling API SKU
-   An API token with the following scopes:
    -   `business-partners.read` to fetch business partners
    -   `business-partner-groups.read` to fetch business partner groups
    -   `business-partners.read-write` to read/write business partner data
    -   `business-partner-groups.read-write` to read/write business partner group data

* * *

## Fetch

### Partners

Use [GET List business partners](https://developer.rippling.com/documentation/rest-api/reference/list-business-partners) to return a paginated list of partners.

_Request:_

```json
curl -L -X GET 'https://rest.ripplingapis.com/business-partners/?expand=worker,business_partner_group'
-H 'Accept: application/json'
-H 'Authorization: Bearer REDACTED'
```

_Response:_

```json
{
  "__meta": {
    "redacted_fields": []
  },
  "results": [
    {
      "id": "66b26001a91aca1dfb199301",
      "created_at": "2026-03-17T21:37:32.953000+00:00",
      "updated_at": "2026-03-17T21:37:32.953000+00:00",
      "business_partner_group_id": "66b2512c4ad1db34abae1e80",
      "business_partner_group": {
        "id": "66b2512c4ad1db34abae1e80",
        "created_at": "2026-03-01T16:00:00.000000+00:00",
        "updated_at": "2026-03-01T16:00:00.000000+00:00",
        "name": "HR Business Partners",
        "domain": "HR",
        "default_business_partner_id": null,
        "default_business_partner": null
      },
      "worker_id": "58d3a1f0e4b0a12c3d456789",
      "worker": null,
      "client_group_id": "66b2512c4ad1db34abae1e90",
      "client_group": null,
      "client_group_member_count": 12
    }
  ],
  "next_link": null
}
```

> **Note:**
> `worker` and `client_group` stay null until you include them in the expand. Expanding `worker` returns the worker object, and expanding `client_group` returns the supergroup of workers associated with that partner.

| Response field | Description |
| --- | --- |
| `id` | Partner identifier. |
| `created_at` | When the partner was created. |
| `updated_at` | When the partner was last updated. |
| `business_partner_group_id` | Group this partner belongs to. |
| `business_partner_group` | Business partner group. Populate with `?expand=business_partner_group`. |
| `worker_id` | Worker who is the business partner. |
| `worker` | The worker. Populate with `?expand=worker`. |
| `client_group_id` | Supergroup of employees associated with this partner. |
| `client_group` | The supergroup. Populate with `?expand=client_group`. |
| `client_group_member_count` | Number of workers associated with this partner. |

Use [GET Retrieve a specific business partner](https://developer.rippling.com/documentation/rest-api/reference/get-business-partners) when you already have the partner id.

### Groups

Use [GET List business partner groups](https://developer.rippling.com/documentation/rest-api/reference/list-business-partner-groups) to return a paginated list of partner groups.

_Request:_

```json
curl -L -X GET 'https://rest.ripplingapis.com/business-partner-groups/?expand=default_business_partner'
-H 'Accept: application/json'
-H 'Authorization: Bearer REDACTED'
```

_Response:_

```json
{
  "__meta": {
    "redacted_fields": []
  },
  "results": [
    {
      "id": "66b2512c4ad1db34abae1e80",
      "created_at": "2026-03-01T16:00:00.000000+00:00",
      "updated_at": "2026-03-01T16:00:00.000000+00:00",
      "name": "HR Business Partners",
      "domain": "HR",
      "default_business_partner_id": "58d3a1f0e4b0a12c3d456789",
      "default_business_partner": {
        "id": "58d3a1f0e4b0a12c3d456789",
        "created_at": "2024-01-15T18:22:10.000000+00:00",
        "updated_at": "2026-02-01T12:00:00.000000+00:00"
      }
    }
  ],
  "next_link": null
}
```

> **Note:**
> `default_business_partner` will be null even when expanded if there is no value associated.

| Response field | Description |
| --- | --- |
| `id` | Group identifier. Use it as `business_partner_group_id` when creating a partner. |
| `created_at` | When the group was created. |
| `updated_at` | When the group was last updated. |
| `name` | Name of the group. |
| `domain` | `HR`, `IT`, `FINANCE`, `RECRUITING`, or `OTHER`. |
| `default_business_partner_id` | Worker id of the fallback partner. Null when the group has no fallback. |
| `default_business_partner` | The worker. Populate with `?expand=default_business_partner`. Null when `default_business_partner_id` is null. |

* * *

## Create

### Partners

Use [POST Create a new business partner](https://developer.rippling.com/documentation/rest-api/reference/create-business-partners) to create a new partner.

_Request:_

```json
curl -L -X POST 'https://rest.ripplingapis.com/business-partners/'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer REDACTED'
```

_Request body:_

```json
{
  "business_partner_group_id": "66b2512c4ad1db34abae1e80",
  "worker_id": "58d3a1f0e4b0a12c3d456789"
}
```

| Request body field | Required | Description |
| --- | --- | --- |
| `business_partner_group_id` | Yes | Group `id` from GET List business partner groups. |
| `worker_id` | Yes | Worker `id` from GET List workers. |

_Response:_

```json
{
  "id": "66b26001a91aca1dfb199301",
  "created_at": "2026-03-17T21:37:32.953000+00:00",
  "updated_at": "2026-03-17T21:37:32.953000+00:00",
  "business_partner_group_id": "66b2512c4ad1db34abae1e80",
  "business_partner_group": null,
  "worker_id": "58d3a1f0e4b0a12c3d456789",
  "worker": null,
  "client_group_id": null,
  "client_group": null,
  "client_group_member_count": 0
}
```

### Groups

Use [POST Create a new business partner group](https://developer.rippling.com/documentation/rest-api/reference/create-business-partner-groups) to create a new group.

_Request:_

```json
curl -L -X POST 'https://rest.ripplingapis.com/business-partner-groups/'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer REDACTED'
```

_Request body:_

```json
{
  "name": "HR Business Partners",
  "domain": "HR",
  "default_business_partner_id": "58d3a1f0e4b0a12c3d456789"
}
```

| Field | Required | Description |
| --- | --- | --- |
| `name` | Yes | Name used to identify the group. |
| `domain` | No | `HR`, `IT`, `FINANCE`, `RECRUITING`, or `OTHER`. |
| `default_business_partner_id` | No | Worker `id` used when an employee is not explicitly mapped to a partner in this group. |

_Response:_

```json
{
  "id": "66b2512c4ad1db34abae1e80",
  "created_at": "2026-03-01T16:00:00.000000+00:00",
  "updated_at": "2026-03-01T16:00:00.000000+00:00",
  "name": "HR Business Partners",
  "domain": "HR",
  "default_business_partner_id": "58d3a1f0e4b0a12c3d456789",
  "default_business_partner": null
}
```

> **Note:**
> `default_business_partner_id` is a `worker id`, not a business partner `id`.

* * *

## Delete

Use [DELETE Delete a business partner](https://developer.rippling.com/documentation/rest-api/reference/delete-business-partners) or [DELETE Delete a business partner group](https://developer.rippling.com/documentation/rest-api/reference/delete-business-partner-groups) to delete a partner or group.

_Request:_

```json
curl -L -X DELETE 'https://rest.ripplingapis.com/business-partners/66b26001a91aca1dfb199301/'
-H 'Accept: application/json'
-H 'Authorization: Bearer REDACTED'
```

_Request:_

```json
curl -L -X DELETE 'https://rest.ripplingapis.com/business-partner-groups/66b2512c4ad1db34abae1e80/'
-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)
-   [Set up and manage Business Partners in Rippling](https://help.rippling.com/article?articleId=772033363900)
-   [API tokens and permissions](https://developer.rippling.com/documentation/rest-api/essentials/api-tokens)

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

> 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.
