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
REST API
guide

Manage levels using the API

Fetch and manage company levels using the Levels API.

Use with AI:Rippling AI ChatGPT Claude Cursor

Overview​

Rippling’s Levels API lets you read and manage company-defined job levels. Levels represent seniority and role progression (for example, Senior Engineer or Engineering Manager).

Key terms:

  • Level: A company-defined job level.
  • Track: A career track that groups levels (e.g., Individual Contributor vs. Management).
  • Global level: A number that represents seniority across the company. Higher values are more senior.
  • Rank: The level’s order within its track.
  • Parent level: Optional parent level.

Available endpoints​

EndpointDescription
GET List levelsLists company levels.
POST Create a new levelCreates a new level.
GET Retrieve a specific levelRetrieves a specific level by id.
PATCH Update a levelUpdates a level.
DELETE Delete a levelSoft-deletes the level by id.

Related endpoints:

EndpointDescription
GET List tracksList tracks. Use id as track_id.
GET Retrieve a specific trackRetrieve a specific track by id.

Levels that are not associated with a track are read-only and cannot be created, updated, or deleted through the API.

Suggested workflow​

  1. List tracks to get a valid track_id.
  2. List levels to see existing names, global_level values, and which levels already belong to the track.
  3. Create a new level with name and track_id.
  4. Retrieve a specific level when you already have the id, and expand parent or track if you need nested objects.
  5. Update a level to change display fields, seniority, or track.
  6. Delete a level only when no active worker references it. Delete soft-deletes the level and retains remaining levels in the track.

Requirements​

  • The Rippling API SKU
  • An API token with the following scopes:
    • levels.read to fetch levels
    • levels.read-write to list and manage levels
    • tracks.read to create new levels

Fetch​

Levels​

Use GET List levels to return a paginated list of company levels.

Request:

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

Response:

{
  "results": [
    {
      "id": "65699295fb7bc7c3510f4075",
      "created_at": "2023-12-01T08:00:21.551000+00:00",
      "updated_at": "2025-04-20T13:50:50.632000+00:00",
      "name": "Senior Engineer",
      "parent_id": "65699281fb7bc7c3510f44a6",
      "global_level": 4,
      "description": "Owns complex projects with limited guidance.",
      "scope_of_responsibilities": "Technical delivery for a product area",
      "experience_requirements": "Typically 5+ years",
      "rank": 3,
      "track_id": "674c17a3c3f93afc697160d2"
    }
  ],
  "next_link": null
}
Response fieldDescription
idUnique identifier of the level.
nameDisplay name. Must be unique within the company.
parent_idParent level, if the company uses a level hierarchy.
global_levelCompany-wide seniority. Higher is more senior. Used in workflows, policies, and reports.
descriptionDescription of the level.
scope_of_responsibilitiesScope of responsibilities for the level.
experience_requirementsExperience expected at this level.
rankOrder of the level within its track.
track_idAssociated track. Empty or unset on legacy levels that are not track-backed.

Include nested objects in the same response:

curl -L -X GET 'https://rest.ripplingapis.com/levels/?expand=parent,track'
-H 'Accept: application/json'
-H 'Authorization: Bearer REDACTED'

Use GET Retrieve a specific level when you already have the level id.

Request:

curl -L -X GET 'https://rest.ripplingapis.com/levels/65699295fb7bc7c3510f4075/'
-H 'Accept: application/json'
-H 'Authorization: Bearer REDACTED'

Response:

{
  "id": "65699295fb7bc7c3510f4075",
  "created_at": "2023-12-01T08:00:21.551000+00:00",
  "updated_at": "2025-04-20T13:50:50.632000+00:00",
  "name": "Senior Engineer",
  "parent_id": "65699281fb7bc7c3510f44a6",
  "global_level": 4,
  "description": "Owns complex projects with limited guidance.",
  "scope_of_responsibilities": "Technical delivery for a product area",
  "experience_requirements": "Typically 5+ years",
  "rank": 3,
  "track_id": "674c17a3c3f93afc697160d2"
}

Tracks​

Use GET List tracks to return a paginated list of company tracks.

Request:

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

Response:

{
  "results": [
    {
      "id": "674c17a3c3f93afc697160d2",
      "created_at": "2023-12-01T08:00:21.551000+00:00",
      "updated_at": "2025-04-20T13:50:50.632000+00:00",
      "name": "Individual Contributor",
      "is_default": true,
      "order": 1,
      "start_global_level": 7
    },
    {
      "id": "674c17adc3f93afc697169d5",
      "created_at": "2023-12-01T08:00:21.551000+00:00",
      "updated_at": "2025-04-20T13:50:50.632000+00:00",
      "name": "Management",
      "is_default": false,
      "order": 2,
      "start_global_level": 9
    }
  ],
  "next_link": null
}

Use GET Retrieve a specific track when you already have the track id.

Request:

curl -L -X GET 'https://rest.ripplingapis.com/tracks/6569929bfb7bc7c3510f417b/'
-H 'Accept: application/json'
-H 'Authorization: Bearer REDACTED'

Response:

{
  "id": "6569929bfb7bc7c3510f417b",
  "created_at": "2023-12-01T08:00:27.387000+00:00",
  "updated_at": "2023-12-01T08:00:27.387000+00:00",
  "name": "IC",
  "is_default": false,
  "order": 0,
  "start_global_level": 207
}

Create​

Level​

Use POST Create a new level to add a track-backed level.

Request:

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

Request body:

{
  "name": "Staff Engineer",
  "track_id": "674c17a3c3f93afc697160d2",
  "global_level": 5,
  "description": "Sets technical direction across multiple teams.",
  "scope_of_responsibilities": "Architecture and mentoring across the org",
  "experience_requirements": "Typically 8+ years"
}
FieldRequiredDescription
nameYesDisplay name. Must be unique within the company.
track_idYesTrack from GET List tracks.
global_levelNoSeniority rank used by workflows, policies, and reports.
descriptionNoDescription of the level.
scope_of_responsibilitiesNoScope of responsibilities.
experience_requirementsNoExperience expected at this level.

Response:

{
  "id": "66a43405af71f094991bf94f",
  "created_at": "2026-09-17T17:00:00.000000+00:00",
  "updated_at": "2026-09-17T17:00:00.000000+00:00",
  "name": "Staff Engineer",
  "parent_id": "65699295fb7bc7c3510f4075",
  "global_level": 5,
  "description": "Sets technical direction across multiple teams.",
  "scope_of_responsibilities": "Architecture and mentoring across the org",
  "experience_requirements": "Typically 8+ years",
  "rank": 4,
  "track_id": "674c17a3c3f93afc697160d2"
}

Update​

Level​

Use PATCH Update a level to change a track-backed level. All body fields are optional, and send only the fields you are changing.

If you change track_id, include global_level in the same request.

Request:

curl -L -X PATCH 'https://rest.ripplingapis.com/levels/65699295fb7bc7c3510f4075/'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer REDACTED'

Request body:

{
  "description": "Owns complex projects and mentors mid-level engineers.",
  "global_level": 4
}
Request body fieldRequiredDescription
nameNoDisplay name. Must be unique within the company.
global_levelNoSeniority rank used by workflows, policies, and reports. Higher is more senior. Include this when you change track_id.
descriptionNoDescription of the level.
scope_of_responsibilitiesNoScope of responsibilities.
experience_requirementsNoExperience expected at this level.
track_idNoTrack from GET List tracks. Include global_level in the same request when you change it.

Response:

{
  "id": "65699295fb7bc7c3510f4075",
  "created_at": "2023-12-01T08:00:21.551000+00:00",
  "updated_at": "2026-09-17T17:12:00.000000+00:00",
  "name": "Senior Engineer",
  "parent_id": "65699281fb7bc7c3510f44a6",
  "global_level": 4,
  "description": "Owns complex projects and mentors mid-level engineers.",
  "scope_of_responsibilities": "Technical delivery for a product area",
  "experience_requirements": "Typically 5+ years",
  "rank": 3,
  "track_id": "674c17a3c3f93afc697160d2"
}

Delete​

Level​

Use DELETE Delete a level to remove an eligible track-backed level.

Notes:

  • A level cannot be deleted while an active worker is assigned to it. Reassign or remove those workers first.
  • Levels without a track cannot be deleted.

Request:

curl -L -X DELETE 'https://rest.ripplingapis.com/levels/65699295fb7bc7c3510f4075/'
-H 'Accept: application/json'
-H 'Authorization: Bearer REDACTED'

A successful delete returns 200 and no body.

FAQs​

What is the difference between a level and a title?

A level is seniority or career stage (for example, L4 or Senior). A title is the job title (for example, Software Engineer). Workers can have both.

What is the difference between global_level and rank?

global_level is company-wide seniority, while rank is the level’s order within its track. You can send global_level on create and update.

Why do I need a track to create a level?

POST Create a new level is for track-backed levels, and a track_id is required. Levels with no track can be fetched but cannot be managed through the API.

Can I set parent_id when I create a level?

No. parent_id is returned when fetching and can be expanded as parent.

What does "soft-delete" mean?

When a level is deleted via the API, it isn't removed from the database. Instead, it is hidden from future API calls/response code and the level cannot be restored or reused.

Why did my delete call fail?

Typical causes can be that the level has no track or an active worker is still assigned that level_id. Reassign those workers, then retry the API call.

See also​

In this article: