Skip to content

Rippling: Create a new level

Rippling restApi.createLevels: arguments, response, policy and SDK examples.

← Rest API operations · Get started

Operation rippling.rest_api.create_levels

Provider route: POST /levels/. Alter supplies the connection’s credentials and routing.

Install @alter-ai/sdk @alter-ai/rippling with npm, or alter-sdk-rippling with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { RipplingIntegration } from "@alter-ai/rippling";
async function execute(input: Parameters<RipplingIntegration["restApi"]["createLevels"]>[0]) {
const app = new App({ apiKey: process.env.ALTER_API_KEY! });
try {
const provider = new RipplingIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
const call = await provider.restApi.createLevels(input);
const result = await call.wait();
return result.bodyJson();
} finally {
await app.close();
}
}
import os
from alter_sdk import App
from alter_sdk_rippling import RipplingIntegration
async def execute(arguments):
async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
provider = RipplingIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
call = await provider.rest_api.create_levels(arguments)
result = await call.wait()
return result.body_json()
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
bodyModelOptionalExpand Create a new level — request body — body

Referenced models: Create a new level — request body — body

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

FieldTypePresenceDescription and constraints
$objectRoot
created_atstringRequired within parentRecord creation date
descriptionstringOptionalThe description of the level.
experience_requirementsstringOptionalThe experience requirements for the level.
global_levelJSONOptional
global_level (anyOf 1)integerAlternativeGlobal level is used to track the seniority of levels. The higher up a level is placed on the page, the more senior and higher-ranked the level. Global level is used in workflows, policies, and reports that use the level attribute (e.g., you can use Level Lookup to set up a workflow that notifies the nearest person in an worker’s management chain at or above the specified level).
global_level (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
idstringRequired within parentIdentifier field
namestringRequired within parentThe name of the level. Must be unique within the company or organization.
parentModelOptionalExpand Update a level — response body — parent
The parent level.

Expandable field
parent_idstringOptionalThe parent level.
rankJSONOptional
rank (anyOf 1)integerAlternativeThe rank of the level within its track.
rank (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
scope_of_responsibilitiesstringOptionalThe scope of responsibilities for the level.
trackModelOptionalExpand Update a level — response body — track
track_idstringOptionalThe track associated with the level. Required during creation. Include global_level when changing it.
updated_atstringRequired within parentRecord update date

Referenced models: Update a level — response body — parent, Update a level — response body — track

Update a level — response body — parent
FieldTypePresenceDescription and constraints
$objectRoot
created_atstringRequired within parentRecord creation date
descriptionstringOptionalThe description of the level.
experience_requirementsstringOptionalThe experience requirements for the level.
global_levelJSONOptional
global_level (anyOf 1)integerAlternativeGlobal level is used to track the seniority of levels. The higher up a level is placed on the page, the more senior and higher-ranked the level. Global level is used in workflows, policies, and reports that use the level attribute (e.g., you can use Level Lookup to set up a workflow that notifies the nearest person in an worker's management chain at or above the specified level).
global_level (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
idstringRequired within parentIdentifier field
namestringRequired within parentThe name of the level. Must be unique within the company or organization.
parentModelOptionalExpand Update a level — response body — parent
The parent level.

Expandable field
parent_idstringOptionalThe parent level.
rankJSONOptional
rank (anyOf 1)integerAlternativeThe rank of the level within its track.
rank (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
scope_of_responsibilitiesstringOptionalThe scope of responsibilities for the level.
trackModelOptionalExpand Update a level — response body — track
track_idstringOptionalThe track associated with the level. Required during creation. Include global_level when changing it.
updated_atstringRequired within parentRecord update date

Referenced models: Update a level — response body — parent, Update a level — response body — track

Create a new level — request body — body
FieldTypePresenceDescription and constraints
$objectRoot
descriptionstringOptionalThe description of the level.
experience_requirementsstringOptionalThe experience requirements for the level.
global_levelintegerOptionalGlobal level is used to track the seniority of levels. The higher up a level is placed on the page, the more senior and higher-ranked the level. Global level is used in workflows, policies, and reports that use the level attribute (e.g., you can use Level Lookup to set up a workflow that notifies the nearest person in an worker's management chain at or above the specified level).
namestringRequired within parentThe name of the level. Must be unique within the company or organization.
scope_of_responsibilitiesstringOptionalThe scope of responsibilities for the level.
track_idstringRequired within parentThe track associated with the level. Required during creation. Include global_level when changing it.
Update a level — response body — track
FieldTypePresenceDescription and constraints
$objectRootThe track associated with the level, if it's not a global level.

Expandable field
created_atstringRequired within parentRecord creation date
idstringRequired within parentIdentifier field
is_defaultbooleanOptionalWhether this is the company's default track.
namestringRequired within parentThe name of the track. Must be unique within the company or organization.
orderJSONOptional
order (anyOf 1)integerAlternativeThe one-based horizontal display order of the track.
order (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
start_global_levelJSONOptional
start_global_level (anyOf 1)integerAlternativeThe highest global level occupied by this track. Empty tracks return null.
start_global_level (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
updated_atstringRequired within parentRecord update date

SDK function policy ID: rippling.rest_api.create_levels. Catalog operation: create-levels. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Required provider scopes: ["levels.read-write"]

Provider entitlements: ["API_Tier_1"]

Pinned headers: {"Rippling-Api-Version": "2024-08-01"}

Official provider source

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.