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, orOTHER. - 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 | Lists groups. |
| POST Create a new business partner group | Creates a group. name is required. |
| GET Retrieve a specific business partner group | Retrieves one group by id. |
| DELETE Delete a business partner group | Deletes a group. |
| GET List business partners | Lists partners. |
| POST Create a new business partner | Creates a partner. business_partner_group_id and worker_id are required. |
| GET Retrieve a specific business partner | Retrieves one partner by id. |
| DELETE Delete a business partner | Deletes a partner. |
Related endpoints:
| Endpoint | Description |
|---|---|
| GET List workers | Use id as worker_id or default_business_partner_id. |
Suggested workflow
- List business partner groups or create a business partner group with a
nameand adomain. - List workers and choose the worker who will be the business partner.
- Create a business partner with that group's
idand the workerid. - List business partners with
expand=worker,business_partner_groupto confirm the assignment. - Delete a business partner to remove that worker from the group or delete a business partner group to remove the group.
Requirements
- The Rippling API SKU
- An API token with the following scopes:
business-partners.readto fetch business partnersbusiness-partner-groups.readto fetch business partner groupsbusiness-partners.read-writeto read/write business partner databusiness-partner-groups.read-writeto read/write business partner group data
Fetch
Partners
Use GET List business partners to return a paginated list of partners.
Request:
curl -L -X GET 'https://rest.ripplingapis.com/business-partners/?expand=worker,business_partner_group'
-H 'Accept: application/json'
-H 'Authorization: Bearer REDACTED'
Response:
{
"__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
}
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 when you already have the partner id.
Groups
Use GET List business partner groups to return a paginated list of partner groups.
Request:
curl -L -X GET 'https://rest.ripplingapis.com/business-partner-groups/?expand=default_business_partner'
-H 'Accept: application/json'
-H 'Authorization: Bearer REDACTED'
Response:
{
"__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
}
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 to create a new partner.
Request:
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:
{
"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:
{
"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 to create a new group.
Request:
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:
{
"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:
{
"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
}
default_business_partner_id is a worker id, not a business partner id.
Delete
Use DELETE Delete a business partner or DELETE Delete a business partner group to delete a partner or group.
Request:
curl -L -X DELETE 'https://rest.ripplingapis.com/business-partners/66b26001a91aca1dfb199301/'
-H 'Accept: application/json'
-H 'Authorization: Bearer REDACTED'
Request:
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.