openapi: 3.0.1
info:
  title: Shareworks Admin REST Authentication Token Vesting Schedule API
  description: Shareworks Admin REST API
  version: 1.0.0
servers:
- url: https://shareworks.solium.com/rest/admin
  description: Production
- url: https://sum-qa02.shareworks.com/rest/admin
  description: Sandbox
security:
- accessToken: []
tags:
- name: Vesting Schedule
paths:
  /v1/company/{companyId}/vesting-schedule:
    get:
      tags:
      - Vesting Schedule
      summary: GET Vesting Schedule (All)
      description: Retrieve the details of all vesting schedules for the specified company
      operationId: getAllVestingScheduleDetails
      parameters:
      - name: companyId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      - name: pageSize
        in: query
        description: Number of items to return per page. Default is 50. Maximum is 250
        schema:
          type: integer
          format: int32
      - name: pageNumber
        in: query
        description: Which page of the data set to fetch. Default is 1.
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          headers:
            Page-Number:
              description: Which page of the data set to fetch. Default is 1.
              style: simple
            Page-Size:
              description: Number of items to return per page. Default is 50. Maximum is 250
              style: simple
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VestingScheduleDetails'
        '400':
          description: The request was unacceptable, often due to missing a required parameter, malformed query, or malformed request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiErrorResponse'
              encoding:
                ? ''
                : contentType: application/json
        '401':
          description: You request was successful and valid but you do not have access to this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiErrorResponse'
              encoding:
                ? ''
                : contentType: application/json
        '403':
          description: When a request tries to access a resource that doesn't belong to them.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiErrorResponse'
              encoding:
                ? ''
                : contentType: application/json
        '422':
          description: There was a validation error. Check the error message to see what values caused the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiErrorResponse'
              encoding:
                ? ''
                : contentType: application/json
        '500':
          description: Servers are not working as expected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiErrorResponse'
              encoding:
                ? ''
                : contentType: application/json
    post:
      tags:
      - Vesting Schedule
      summary: POST Vesting Schedule (Create)
      description: Create a vesting schedule for the specified company
      operationId: createVestingSchedule
      parameters:
      - name: Shareworks-Request-Id
        in: header
        description: An identifier unique to this request.  If a connection is broken or a response does not come in a timely manner, submit the same request again with this same identifier. Shareworks ensures that duplicate requests with the same identifier will only be processed once and will all return the same response.
        required: false
        schema:
          type: string
      - name: companyId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VestingScheduleCrudRequest'
      responses:
        '201':
          description: Created. An object is created and returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VestingScheduleDetails'
        '400':
          description: "The request was unacceptable, often due to missing a required parameter, malformed query, or malformed request body.\n\nAlso occurs when using Shareworks-Request-Id header if:  \n- A previous request with the identifier has been submitted but is not yet complete  \n    - errors[] will include {code: 461, message: A request with the provided Shareworks-Request-Id is currently in-progress}  \n- A previous, but different, request was already processed with the same identifier  \n    - errors[] will include {code: 460, message: The provided Shareworks-Request-Id header is not unique for this user}"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiErrorResponse'
              encoding:
                ? ''
                : contentType: application/json
        '401':
          description: You request was successful and valid but you do not have access to this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiErrorResponse'
              encoding:
                ? ''
                : contentType: application/json
        '403':
          description: When a request tries to access a resource that doesn't belong to them.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiErrorResponse'
              encoding:
                ? ''
                : contentType: application/json
        '422':
          description: There was a validation error. Check the error message to see what values caused the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiErrorResponse'
              encoding:
                ? ''
                : contentType: application/json
        '500':
          description: Servers are not working as expected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiErrorResponse'
              encoding:
                ? ''
                : contentType: application/json
  /v1/company/{companyId}/vesting-schedule/manual:
    get:
      tags:
      - Vesting Schedule
      summary: GET Manual Vesting Schedules (All)
      description: Retrieve the details of all manual vesting schedules for the specified company
      operationId: getAllManualVestingScheduleDetails
      parameters:
      - name: companyId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VestingScheduleDetails'
        '400':
          description: The request was unacceptable, often due to missing a required parameter, malformed query, or malformed request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiErrorResponse'
              encoding:
                ? ''
                : contentType: application/json
        '401':
          description: You request was successful and valid but you do not have access to this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiErrorResponse'
              encoding:
                ? ''
                : contentType: application/json
        '403':
          description: When a request tries to access a resource that doesn't belong to them.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiErrorResponse'
              encoding:
                ? ''
                : contentType: application/json
        '422':
          description: There was a validation error. Check the error message to see what values caused the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiErrorResponse'
              encoding:
                ? ''
                : contentType: application/json
        '500':
          description: Servers are not working as expected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiErrorResponse'
              encoding:
                ? ''
                : contentType: application/json
  /v1/company/{companyId}/vesting-schedule/{vestingScheduleId}:
    get:
      tags:
      - Vesting Schedule
      summary: GET Vesting Schedule (Single)
      description: Retrieve the details of the specified vesting schedule
      operationId: getVestingScheduleDetails
      parameters:
      - name: companyId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      - name: vestingScheduleId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VestingScheduleDetails'
        '400':
          description: The request was unacceptable, often due to missing a required parameter, malformed query, or malformed request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiErrorResponse'
              encoding:
                ? ''
                : contentType: application/json
        '401':
          description: You request was successful and valid but you do not have access to this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiErrorResponse'
              encoding:
                ? ''
                : contentType: application/json
        '403':
          description: When a request tries to access a resource that doesn't belong to them.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiErrorResponse'
              encoding:
                ? ''
                : contentType: application/json
        '422':
          description: There was a validation error. Check the error message to see what values caused the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiErrorResponse'
              encoding:
                ? ''
                : contentType: application/json
        '500':
          description: Servers are not working as expected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiErrorResponse'
              encoding:
                ? ''
                : contentType: application/json
    put:
      tags:
      - Vesting Schedule
      summary: PUT Vesting Schedule (Update)
      description: Update the details of the specified vesting schedule
      operationId: updateVestingSchedule
      parameters:
      - name: companyId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      - name: vestingScheduleId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VestingScheduleCrudRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VestingScheduleDetails'
        '400':
          description: The request was unacceptable, often due to missing a required parameter, malformed query, or malformed request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiErrorResponse'
              encoding:
                ? ''
                : contentType: application/json
        '401':
          description: You request was successful and valid but you do not have access to this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiErrorResponse'
              encoding:
                ? ''
                : contentType: application/json
        '403':
          description: When a request tries to access a resource that doesn't belong to them.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiErrorResponse'
              encoding:
                ? ''
                : contentType: application/json
        '422':
          description: There was a validation error. Check the error message to see what values caused the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiErrorResponse'
              encoding:
                ? ''
                : contentType: application/json
        '500':
          description: Servers are not working as expected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiErrorResponse'
              encoding:
                ? ''
                : contentType: application/json
components:
  schemas:
    ErrorWithCode:
      title: Validation Error
      required:
      - code
      - message
      type: object
      properties:
        message:
          type: string
          description: Message describing the error
        code:
          type: integer
          description: Unique code for the validation error
          format: int32
    RestApiErrorResponse:
      title: Error Response
      required:
      - code
      - errorId
      - message
      type: object
      properties:
        code:
          type: string
          description: Code representing the type of error
        message:
          type: string
          description: Message describing the error
        errors:
          type: array
          description: List of all further error details, usually due to validation checks
          items:
            $ref: '#/components/schemas/ErrorWithCode'
        errorId:
          type: string
          description: Identifier for the error
    VestingScheduleRowRequest:
      title: Vesting Schedule Row Body
      required:
      - amountDenominator
      - amountNumerator
      - vestingPeriodLength
      - vestingPeriodType
      type: object
      properties:
        amountNumerator:
          type: integer
          description: Numerator of the vesting amount for the row/tranche
          format: int64
        amountDenominator:
          type: integer
          description: Denominator of the vesting amount for the row/tranche
          format: int64
        vestingPeriodLength:
          type: integer
          description: Number of periods between the row/tranche and the previous row/tranche (or vesting start date)
          format: int32
        vestingPeriodType:
          type: string
          description: Type of vesting period for the row/tranche
          enum:
          - YEAR
          - MONTH
          - WEEK
          - DAY
      description: List of all rows/tranches for the vesting schedule
    VestingScheduleDetails:
      title: Vesting Schedule Response
      required:
      - vestingBasis
      - vestingScheduleDescription
      - vestingScheduleId
      - vestingScheduleName
      - vestingScheduleRows
      - wholeUnitVesting
      type: object
      properties:
        vestingScheduleId:
          type: integer
          description: Identifier for the vesting schedule
          format: int32
        vestingScheduleName:
          type: string
          description: Name for the vesting schedule
        vestingScheduleDescription:
          type: string
          description: Sentence(s) for describing the vesting schedule
        vestingBasis:
          type: string
          description: Basis type to specify how the vesting start date is determined
          enum:
          - GRANT_DATE
          - GRANT_VESTING_START_DATE
          - SPECIFIED_DATE
          - OTHER
        vestingBasisSpecifiedDate:
          type: string
          description: Date to be used as vesting start date for all grants/certificates using the schedule, only set when vestingBasis is SPECIFIED_DATE
          format: date
        vestingScheduleAllocationType:
          type: string
          description: Strategy for determination allocation of uneven tranches
          enum:
          - CUMULATIVE_ROUNDING
          - CUMUL_ROUND_V2
          - CUMULATIVE_ROUND_DOWN
          - FRONT_LOADED
          - FRONT_LOADED_TO_SINGLE_TRANCHE
          - BACK_LOADED
          - BACK_LOADED_TO_SINGLE_TRANCHE
          - OTHER
        wholeUnitVesting:
          type: boolean
          description: Whether fractional vesting tranches are disallowed (value 'true' indicates the allocation strategy will be used)
        vestingScheduleRows:
          type: array
          description: List of all rows/tranches for the vesting schedule
          items:
            $ref: '#/components/schemas/VestingScheduleRowDetails'
    VestingScheduleRowDetails:
      title: Vesting Schedule Row Response
      required:
      - amountDenominator
      - amountNumerator
      - vestingScheduleRowId
      type: object
      properties:
        vestingScheduleRowId:
          type: integer
          description: Identifier for the vesting row
          format: int32
        amountNumerator:
          type: integer
          description: Numerator of the vesting amount for the row/tranche
          format: int64
        amountDenominator:
          type: integer
          description: Denominator of the vesting amount for the row/tranche
          format: int64
        vestingPeriodLength:
          type: integer
          description: Number of periods between the row/tranche and the previous row/tranche (or vesting start date)
          format: int32
        vestingPeriodType:
          type: string
          description: Type of vesting period for the row/tranche
          enum:
          - YEAR
          - MONTH
          - WEEK
          - DAY
      description: List of all rows/tranches for the vesting schedule
    VestingScheduleCrudRequest:
      title: Vesting Schedule Body
      required:
      - vestingBasis
      - vestingScheduleDescription
      - vestingScheduleName
      - vestingScheduleRows
      - wholeUnitVesting
      type: object
      properties:
        vestingScheduleName:
          type: string
          description: Name for the vesting schedule
        vestingScheduleDescription:
          type: string
          description: Sentence(s) for describing the vesting schedule
        vestingBasis:
          type: string
          description: Basis type to specify how the vesting start date is determined
          enum:
          - GRANT_DATE
          - GRANT_VESTING_START_DATE
          - SPECIFIED_DATE
          - OTHER
        vestingBasisSpecifiedDate:
          type: string
          description: Date to be used as vesting start date for all grants/certificates using the schedule, only set when vestingBasis is SPECIFIED_DATE
          format: date
        vestingScheduleAllocationType:
          type: string
          description: Strategy for determination allocation of uneven tranches
          enum:
          - CUMULATIVE_ROUNDING
          - CUMUL_ROUND_V2
          - CUMULATIVE_ROUND_DOWN
          - FRONT_LOADED
          - FRONT_LOADED_TO_SINGLE_TRANCHE
          - BACK_LOADED
          - BACK_LOADED_TO_SINGLE_TRANCHE
          - OTHER
        wholeUnitVesting:
          type: boolean
          description: Whether fractional vesting tranches are disallowed (value 'true' indicates the allocation strategy will be used)
        vestingScheduleRows:
          type: array
          description: List of all rows/tranches for the vesting schedule
          items:
            $ref: '#/components/schemas/VestingScheduleRowRequest'
  securitySchemes:
    accessToken:
      type: http
      scheme: bearer
      bearerFormat: JWT