Shareworks Stock Certificate API

openapi: 3.2.0
info:
  title: Shareworks Admin REST Stock Certificate 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: Stock Certificate
paths:
  /v1/company/{companyId}/stakeholder/{stakeholderId}/stock-certificate:
    get:
      tags:
      - Stock Certificate
      summary: GET Stock Certificate (All)
      description: Retrieve the details of all stock certificates belonging to the specified stakeholder
      operationId: getStockCertificates
      parameters:
      - name: companyId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      - name: stakeholderId
        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: Identifies which page of the target data set is returned in this response (1 to n). (Only present when the response is paginated)
              style: simple
            Page-Size:
              description: The number of items per page used to paginate the target data set. (Only present when the response is paginated)
              style: simple
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StockCertificateDetails'
        '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:
      - Stock Certificate
      summary: POST Stock Certificate (Create)
      description: Create a stock certificate for the specified stakeholder
      operationId: createStockCertificate
      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: true
        schema:
          type: string
      - name: companyId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      - name: stakeholderId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StockCertificateCrudRequest'
      responses:
        '201':
          description: Created. An object is created and returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StockCertificateDetails'
        '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}/stakeholder/stock-certificate/{stockCertificateId}:
    get:
      tags:
      - Stock Certificate
      summary: GET Stock Certificate (Single)
      description: Retrieve the details of the specified stock certificates
      operationId: getStockCertificate
      parameters:
      - name: companyId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      - name: stockCertificateId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StockCertificateDetails'
        '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:
      - Stock Certificate
      summary: PUT Stock Certificate (Update)
      description: Update the details of the specified stock certificate
      operationId: updateStockCertificate
      parameters:
      - name: companyId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      - name: stockCertificateId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StockCertificateCrudRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StockCertificateDetails'
        '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
    StockCertificateCrudRequest:
      title: Stock Certificate Body
      required:
      - effectiveDate
      - issuePrice
      - quantity
      - stockCertificateNumber
      - stockDesignationId
      type: object
      properties:
        stockDesignationId:
          type: integer
          description: Identifier for the stock designation
          format: int32
        effectiveDate:
          type: string
          description: Effective date for the stock certificate
          format: date
        quantity:
          type: number
          description: Quantity of shares for the stock certificate
          format: double
        issuePrice:
          type: number
          description: Issue price (a.k.a. strike price) for the stock certificate
          format: double
        boardApprovalDate:
          type: string
          description: Board approval date for the stock certificate (if not supplied, the certificate will be created with an unapproved status)
          format: date
        stockCertificateNumber:
          type: string
          description: Number for the stock certificate
        vestingScheduleId:
          type: integer
          description: Identifier for the vesting schedule
          format: int32
        vestingStartDate:
          type: string
          description: Vesting base or commencement date for the vesting schedule
          format: date
        manualVestingRows:
          type: array
          description: List of all manual vesting rows for the stock certificate, specified when using a manual vesting schedule
          items:
            $ref: '#/components/schemas/ManualVestingRowCrudRequest'
    ManualVestingRowDetails:
      title: Manual Vesting Row Response
      required:
      - vestQuantity
      type: object
      properties:
        vestDate:
          type: string
          description: Date on which the vesting occurs for the row/tranche
          format: date
        vestQuantity:
          type: number
          description: Quantity of shares to vest for the row/tranche
          format: double
      description: List of all manual vesting rows for the grant, specified when using a manual vesting schedule
    StockCertificateDetails:
      title: Stock Certificate Response
      required:
      - effectiveDate
      - issuePrice
      - issueReason
      - quantity
      - stakeholderId
      - stockCertificateId
      - stockCertificateNumber
      - stockDesignationId
      - stockDesignationName
      type: object
      properties:
        stockCertificateId:
          type: integer
          description: Identifier for the stock certificate
          format: int32
        stakeholderId:
          type: integer
          description: Identifier for the stakeholder
          format: int32
        stockDesignationId:
          type: integer
          description: Identifier for the stock designation
          format: int32
        stockDesignationName:
          type: string
          description: Name for the stock designation
        stockCertificateNumber:
          type: string
          description: Number for the stock certificate
        quantity:
          type: number
          description: Quantity of shares for the stock certificate
          format: double
        issuePrice:
          type: number
          description: Issue price (a.k.a. strike price) for the stock certificate
          format: double
        issueReason:
          type: string
          description: Issue reason for the stock certificate
          enum:
          - ORIGINAL_ISSUANCE
          - ORIGINAL_ISSUANCE_WITH_VESTING
          - OTHER
        effectiveDate:
          type: string
          description: Effective date for the stock certificate
          format: date
        boardApprovalDate:
          type: string
          description: Board approval date for the stock certificate (if not supplied, the certificate will be created with an unapproved status)
          format: date
        vestingScheduleId:
          type: integer
          description: Identifier for the vesting schedule
          format: int32
        vestingScheduleName:
          type: string
          description: Name for the vesting schedule
        vestingStartDate:
          type: string
          description: Vesting base or commencement date for the vesting schedule
          format: date
        manualVestingRows:
          type: array
          description: List of all manual vesting rows for the stock certificate, specified when using a manual vesting schedule
          items:
            $ref: '#/components/schemas/ManualVestingRowDetails'
    ManualVestingRowCrudRequest:
      title: Manual Vesting Row Body
      type: object
      properties:
        vestDate:
          type: string
          description: Date on which the vesting occurs for the row/tranche
          format: date
        vestQuantity:
          type: number
          description: Quantity of shares to vest for the row/tranche
          format: double
      description: List of all manual vesting rows for the grant, specified when using a manual vesting schedule
    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
  securitySchemes:
    accessToken:
      type: http
      scheme: bearer
      bearerFormat: JWT