openapi: 3.1.0
info:
  title: Rippling API (Base API) Platform API
  version: 1.0.0
  description: 'Rippling is a unified workforce platform spanning HR, IT, and Finance.

    The Base API (also known as the Platform API) exposes employee, company,

    department, team, work location, level, group, leave, custom field, and

    SAML/SSO data plus app provisioning helpers and ATS push endpoints.

    Authentication uses an OAuth2-issued bearer token (API token) supplied in

    the `Authorization: Bearer <token>` header.

    '
  contact:
    name: Rippling Developer Portal
    url: https://developer.rippling.com/
  license:
    name: Proprietary
servers:
- url: https://api.rippling.com
  description: Rippling production API host
security:
- BearerAuth: []
tags:
- name: Platform
paths:
  /platform/api/me:
    get:
      summary: Get the authenticated user / current token context
      operationId: getMe
      responses:
        '200':
          description: Information about the authenticated user (token owner)
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
  /platform/api/companies:
    get:
      summary: List companies accessible to the token
      operationId: getCompanies
      responses:
        '200':
          description: Company list
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
  /platform/api/company_activity:
    get:
      summary: List recent company activity events
      operationId: getCompanyActivity
      parameters:
      - name: startDate
        in: query
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        schema:
          type: integer
      - name: next
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Page of company activity events
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
  /platform/api/employees:
    get:
      summary: List active employees
      operationId: getEmployees
      parameters:
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated list of employees
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
  /platform/api/employees/include_terminated:
    get:
      summary: List employees including terminated workers
      operationId: getEmployeesIncludeTerminated
      parameters:
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated list of employees including terminated
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
  /platform/api/employees/{employee_id}:
    get:
      summary: Get an employee by ID
      operationId: getEmployeeById
      parameters:
      - $ref: '#/components/parameters/EmployeeId'
      responses:
        '200':
          description: Employee record
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Employee not found
      tags:
      - Platform
  /platform/api/departments:
    get:
      summary: List departments
      operationId: getDepartments
      responses:
        '200':
          description: List of departments
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
  /platform/api/work_locations:
    get:
      summary: List work locations
      operationId: getWorkLocations
      responses:
        '200':
          description: List of work locations
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
  /platform/api/levels:
    get:
      summary: List career/job levels
      operationId: getLevels
      responses:
        '200':
          description: List of levels
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
  /platform/api/teams:
    get:
      summary: List teams
      operationId: getTeams
      responses:
        '200':
          description: List of teams
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
  /platform/api/custom_fields:
    get:
      summary: List custom field definitions
      operationId: getCustomFields
      responses:
        '200':
          description: Custom fields metadata
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
  /platform/api/groups:
    get:
      summary: List groups
      operationId: getGroups
      responses:
        '200':
          description: List of groups
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
    post:
      summary: Create a group
      operationId: createGroup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                users:
                  type: array
                  items:
                    type: string
      responses:
        '201':
          description: Group created
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
  /platform/api/groups/{group_id}:
    get:
      summary: Get a group by ID
      operationId: getGroupById
      parameters:
      - $ref: '#/components/parameters/GroupId'
      responses:
        '200':
          description: Group record
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
    patch:
      summary: Partially update a group
      operationId: patchGroup
      parameters:
      - $ref: '#/components/parameters/GroupId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Group updated
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
    put:
      summary: Replace a group
      operationId: putGroup
      parameters:
      - $ref: '#/components/parameters/GroupId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Group replaced
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
    delete:
      summary: Delete a group
      operationId: deleteGroup
      parameters:
      - $ref: '#/components/parameters/GroupId'
      responses:
        '204':
          description: Group deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
  /platform/api/leave_requests:
    get:
      summary: List leave requests
      operationId: getLeaveRequests
      parameters:
      - name: startDate
        in: query
        schema:
          type: string
          format: date
      - name: endDate
        in: query
        schema:
          type: string
          format: date
      responses:
        '200':
          description: List of leave requests
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
    post:
      summary: Create a leave request
      operationId: createLeaveRequest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                role:
                  type: string
                  description: Employee role ID
                requestedDates:
                  type: array
                  items:
                    type: string
                    format: date
                companyLeaveType:
                  type: string
                reasonForLeave:
                  type: string
      responses:
        '201':
          description: Leave request created
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
  /platform/api/leave_requests/{leave_request_id}:
    patch:
      summary: Update a leave request
      operationId: patchLeaveRequest
      parameters:
      - name: leave_request_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Leave request updated
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
  /platform/api/leave_requests/process:
    post:
      summary: Approve or reject a leave request
      operationId: processLeaveRequest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                leaveRequestId:
                  type: string
                action:
                  type: string
                  enum:
                  - APPROVE
                  - REJECT
      responses:
        '200':
          description: Leave request decision recorded
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
  /platform/api/leave_requests/cancel:
    post:
      summary: Cancel a leave request
      operationId: cancelLeaveRequest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                leaveRequestId:
                  type: string
      responses:
        '200':
          description: Leave request canceled
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
  /platform/api/leave_balances:
    get:
      summary: List leave balances for all employees
      operationId: getLeaveBalances
      responses:
        '200':
          description: Leave balances list
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
  /platform/api/leave_balances/{employee_id}:
    get:
      summary: Get leave balance for one employee
      operationId: getLeaveBalance
      parameters:
      - $ref: '#/components/parameters/EmployeeId'
      responses:
        '200':
          description: Leave balance for the employee
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
  /platform/api/company_leave_types:
    get:
      summary: List company-defined leave types
      operationId: getCompanyLeaveTypes
      responses:
        '200':
          description: Company leave type catalog
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
  /platform/api/saml/idp_metadata:
    get:
      summary: Retrieve SAML Identity Provider metadata for the company
      operationId: getSamlIdpMetadata
      responses:
        '200':
          description: SAML IdP metadata XML
          content:
            application/xml:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
  /platform/api/app/matching_users:
    get:
      summary: List users in the company that match the calling app
      operationId: getAppMatchingUsers
      responses:
        '200':
          description: Matching users payload
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
  /platform/api/mark_app_installed:
    post:
      summary: Mark the calling app as installed for the company
      operationId: markAppInstalled
      responses:
        '200':
          description: Installation acknowledged
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
  /platform/api/ats/candidates/push_candidate:
    post:
      summary: Push an ATS candidate into Rippling
      operationId: pushAtsCandidate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                email:
                  type: string
                  format: email
                jobTitle:
                  type: string
                department:
                  type: string
                resumeUrl:
                  type: string
                  format: uri
      responses:
        '201':
          description: Candidate created
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Platform
components:
  parameters:
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        default: 25
    Offset:
      name: offset
      in: query
      schema:
        type: integer
        default: 0
    GroupId:
      name: group_id
      in: path
      required: true
      schema:
        type: string
    EmployeeId:
      name: employee_id
      in: path
      required: true
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid bearer token
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Rippling API tokens are issued via OAuth2 (or generated as personal/app

        tokens) and supplied as `Authorization: Bearer <token>`.

        '