Rippling: Create a new draft transition
Rippling restApi.createDraftTransitions: arguments, response, policy and SDK examples.
← Rest API operations · Get started
Operation rippling.rest_api.create_draft_transitions
Provider route: POST /draft-transitions/. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “Call through Alter”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"]["createDraftTransitions"]>[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.createDraftTransitions(input); const result = await call.wait(); return result.bodyJson(); } finally { await app.close(); }}import osfrom alter_sdk import Appfrom 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_draft_transitions(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
body | Model | Optional | Expand Create a new draft transition — request body — body |
Referenced models: Create a new draft transition — request body — body
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
effective_at | string | Required within parent | Effective timestamp applied to the entire draft transition request. |
items | array | Required within parent | Draft transition items to accept for asynchronous processing. |
items[] | Model | Each item | Expand Create a new draft transition — response body — items item |
timezone | string | Required within parent | IANA timezone used to interpret and display the request’s effective timestamp. |
Referenced models: Create a new draft transition — response body — items item
Schemas
Section titled “Schemas”1 more schema is linked from the tables above, on the schema pages.
Create a new draft transition — response body — items item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
changes | object | Required within parent | Requested role/profile changes for this item. |
changes.country_specific_info | object | Optional | Country-specific field changes supported by current draft transition flows. |
changes.employment_info | object | Optional | Employment information changes for the target role. |
changes.employment_info.annual_salary_equivalent | object | Optional | New annual salary equivalent. |
changes.employment_info.annual_salary_equivalent.currency_type | string | Optional | The currency type, ex: USD, EUR, etc. |
changes.employment_info.annual_salary_equivalent.value | JSON | Optional | |
changes.employment_info.annual_salary_equivalent.value (anyOf 1) | number | Alternative | The decimal amount for the currency. |
changes.employment_info.annual_salary_equivalent.value (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
changes.employment_info.currency | string | Optional | New compensation currency for a currency-only change. When monetary amounts are also supplied, this must match their currency_type. All monetary fields in one item must use the same currency. |
changes.employment_info.department_id | string | Optional | New department identifier for the target role. |
changes.employment_info.employment_type_id | string | Optional | New company employment type identifier for the target role. |
changes.employment_info.equity_num_shares | JSON | Optional | |
changes.employment_info.equity_num_shares (anyOf 1) | integer | Alternative | New offer letter equity share count. |
changes.employment_info.equity_num_shares (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
changes.employment_info.equity_value | object | Optional | New offer letter equity value. |
changes.employment_info.equity_value.currency_type | string | Optional | The currency type, ex: USD, EUR, etc. |
changes.employment_info.equity_value.value | JSON | Optional | |
changes.employment_info.equity_value.value (anyOf 1) | number | Alternative | The decimal amount for the currency. |
changes.employment_info.equity_value.value (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
changes.employment_info.equity_vesting_package_id | string | Optional | New equity vesting package identifier. |
changes.employment_info.job_family_id | string | Optional | New job family identifier for the target role. |
changes.employment_info.level_id | string | Optional | New level identifier for the target role. |
changes.employment_info.manager_id | string | Optional | New manager role identifier for the target role. |
changes.employment_info.on_target_commission | object | Optional | New annual on-target commission amount. |
changes.employment_info.on_target_commission.currency_type | string | Optional | The currency type, ex: USD, EUR, etc. |
changes.employment_info.on_target_commission.value | JSON | Optional | |
changes.employment_info.on_target_commission.value (anyOf 1) | number | Alternative | The decimal amount for the currency. |
changes.employment_info.on_target_commission.value (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
changes.employment_info.relocation_reimbursement | object | Optional | New relocation reimbursement amount. |
changes.employment_info.relocation_reimbursement.currency_type | string | Optional | The currency type, ex: USD, EUR, etc. |
changes.employment_info.relocation_reimbursement.value | JSON | Optional | |
changes.employment_info.relocation_reimbursement.value (anyOf 1) | number | Alternative | The decimal amount for the currency. |
changes.employment_info.relocation_reimbursement.value (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
changes.employment_info.salary_per_unit | object | Optional | New compensation amount per salary unit. |
changes.employment_info.salary_per_unit.currency_type | string | Optional | The currency type, ex: USD, EUR, etc. |
changes.employment_info.salary_per_unit.value | JSON | Optional | |
changes.employment_info.salary_per_unit.value (anyOf 1) | number | Alternative | The decimal amount for the currency. |
changes.employment_info.salary_per_unit.value (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
changes.employment_info.salary_unit | string | Optional | New salary unit. |
changes.employment_info.start_date | string | Optional | New start date for the target role. |
changes.employment_info.target_annual_bonus | object | Optional | New target annual bonus amount. |
changes.employment_info.target_annual_bonus.currency_type | string | Optional | The currency type, ex: USD, EUR, etc. |
changes.employment_info.target_annual_bonus.value | JSON | Optional | |
changes.employment_info.target_annual_bonus.value (anyOf 1) | number | Alternative | The decimal amount for the currency. |
changes.employment_info.target_annual_bonus.value (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
changes.employment_info.target_annual_bonus_payment_frequency_unit | string | Optional | New target annual bonus payment frequency. Known values: MONTH, QUARTER, YEAR, SEMI_ANNUAL |
changes.employment_info.target_annual_bonus_percent | JSON | Optional | |
changes.employment_info.target_annual_bonus_percent (anyOf 1) | number | Alternative | New target annual bonus percentage. |
changes.employment_info.target_annual_bonus_percent (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
changes.employment_info.teams_ids | array | Optional | New team identifiers for the target role. |
changes.employment_info.teams_ids[] | string | Each item | |
changes.employment_info.title | string | Optional | New job title for the target role. |
changes.work_location_info | object | Optional | Work location changes for the target role. |
changes.work_location_info.country_code | string | Optional | New work country code for the target role. |
changes.work_location_info.location_id | string | Optional | New work location identifier for the target role. |
draft_grouping_preference | string | Optional | Controls whether this item should append to a compatible existing draft or create a new draft. Known values: APPEND_TO_MATCHING_DRAFT, CREATE_NEW_DRAFT |
role_id | string | Required within parent | Target role identifier for this draft transition item. |
Create a new draft transition — request body — body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
effective_at | string | Required within parent | Effective timestamp applied to the entire draft transition request. |
items | array | Required within parent | Draft transition items to accept for asynchronous processing. |
items[] | Model | Each item | Expand Create a new draft transition — request body — body items item |
timezone | string | Required within parent | IANA timezone used to interpret and display the request's effective timestamp. |
Referenced models: Create a new draft transition — request body — body items item
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: rippling.rest_api.create_draft_transitions. Catalog operation: create-draft-transitions. 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: ["draft-transitions.read-write"]
Provider entitlements: ["Draft_Transitions_API"]
Pinned headers: {"Rippling-Api-Version": "2024-08-01"}