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 partners

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

Use with AI:Rippling AI ChatGPT Claude Cursor

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​

EndpointDescription
GET List business partner groupsLists groups.
POST Create a new business partner groupCreates a group. name is required.
GET Retrieve a specific business partner groupRetrieves one group by id.
DELETE Delete a business partner groupDeletes a group.
GET List business partnersLists partners.
POST Create a new business partnerCreates a partner. business_partner_group_id and worker_id are required.
GET Retrieve a specific business partnerRetrieves one partner by id.
DELETE Delete a business partnerDeletes a partner.

Related endpoints:

EndpointDescription
GET List workersUse id as worker_id or default_business_partner_id.

Suggested workflow​

  1. List business partner groups or create a business partner group with a name and a domain.
  2. List workers and choose the worker who will be the business partner.
  3. Create a business partner with that group's id and the worker id.
  4. List business partners with expand=worker,business_partner_group to confirm the assignment.
  5. 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.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 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 fieldDescription
idPartner identifier.
created_atWhen the partner was created.
updated_atWhen the partner was last updated.
business_partner_group_idGroup this partner belongs to.
business_partner_groupBusiness partner group. Populate with ?expand=business_partner_group.
worker_idWorker who is the business partner.
workerThe worker. Populate with ?expand=worker.
client_group_idSupergroup of employees associated with this partner.
client_groupThe supergroup. Populate with ?expand=client_group.
client_group_member_countNumber 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 fieldDescription
idGroup identifier. Use it as business_partner_group_id when creating a partner.
created_atWhen the group was created.
updated_atWhen the group was last updated.
nameName of the group.
domainHR, IT, FINANCE, RECRUITING, or OTHER.
default_business_partner_idWorker id of the fallback partner. Null when the group has no fallback.
default_business_partnerThe 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 fieldRequiredDescription
business_partner_group_idYesGroup id from GET List business partner groups.
worker_idYesWorker 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"
}
FieldRequiredDescription
nameYesName used to identify the group.
domainNoHR, IT, FINANCE, RECRUITING, or OTHER.
default_business_partner_idNoWorker 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.


See also​