Cosuno Subcontractor Reviews API

openapi: 3.2.0
info:
  title: Cosuno Subcontractor Reviews API
  version: '1'
  description: '-'
  license:
    name: '-'
  contact:
    name: '-'
servers:
- url: https://api.cosuno.com/v1
- description: current
  url: /v1
tags:
- name: Subcontractor Reviews
paths:
  /subcontractor-reviews:
    get:
      operationId: GetReviews
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ReviewResponse'
                type: array
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Retry-After:
              schema:
                type: string
              required: false
      description: List submitted subcontractor reviews owned by your company, with per-category ratings inline. Results are paginated and ordered by submission time, newest first.
      tags:
      - Subcontractor Reviews
      security:
      - accessKey: []
      parameters:
      - description: Number of reviews to skip before returning results; used together with `limit` to paginate.
        in: query
        name: offset
        required: false
        schema:
          default: 0
          format: int32
          type: integer
          minimum: 0
      - description: Maximum number of reviews to return in a single response.
        in: query
        name: limit
        required: false
        schema:
          default: 50
          format: int32
          type: integer
          minimum: 1
          maximum: 200
      summary: Get reviews
      x-summary-source: derived
  /subcontractor-reviews/requests:
    get:
      operationId: GetReviewRequests
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ReviewRequestResponse'
                type: array
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Retry-After:
              schema:
                type: string
              required: false
      description: List subcontractor review requests owned by your company, including those that are still open, already completed, or skipped. Derive the request's state from `dispatchedAt`, `completedAt`, and `skippedAt`. Results are paginated and ordered by creation time, newest first.
      tags:
      - Subcontractor Reviews
      security:
      - accessKey: []
      parameters:
      - description: Number of requests to skip before returning results; used together with `limit` to paginate.
        in: query
        name: offset
        required: false
        schema:
          default: 0
          format: int32
          type: integer
          minimum: 0
      - description: Maximum number of requests to return in a single response.
        in: query
        name: limit
        required: false
        schema:
          default: 50
          format: int32
          type: integer
          minimum: 1
          maximum: 200
      summary: Get review requests
      x-summary-source: derived
    post:
      operationId: CreateReviewRequests
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateReviewRequestsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Retry-After:
              schema:
                type: string
              required: false
      description: Request one or more reviews of a subcontractor. Each assignment pairs a review template with one or more reviewers; the reviewers are notified and reminded to fill in their reviews. If any requested (template, reviewer) pair already has a submitted review for the object, no requests are created and the response is 409 Conflict.
      tags:
      - Subcontractor Reviews
      security:
      - accessKey: []
      parameters: []
      requestBody:
        description: Subcontractor, the object under review, and the per-template reviewer assignments.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReviewRequestsInput'
              description: Subcontractor, the object under review, and the per-template reviewer assignments.
      summary: Create review requests
      x-summary-source: derived
components:
  schemas:
    ReviewRatingResponse:
      description: Score the reviewer gave for one category of a review.
      properties:
        categoryId:
          type: string
          description: Unique identifier of the rating category.
        categoryName:
          type: string
          description: Name of the rating category.
        rating:
          type:
          - number
          - 'null'
          format: double
          description: Score from 1 (worst) to 5 (best). `null` when the reviewer marked the category as not applicable.
        comment:
          type: string
          description: Free-form comment left by the reviewer for this category, if any.
      required:
      - categoryId
      - categoryName
      - rating
      type: object
      additionalProperties: false
    ReviewSubcontractorResponse:
      description: Subcontractor the review or request is about.
      properties:
        id:
          type: string
          description: ID of the subcontractor.
        name:
          type: string
          description: Name of the subcontractor.
        externalSource:
          type: string
          description: Identifier of the external system this subcontractor was imported from, if any.
        externalId:
          type: string
          description: Identifier of this subcontractor within the external system, if any.
      required:
      - id
      - name
      type: object
      additionalProperties: false
    CreatedReviewRequest:
      properties:
        id:
          type: string
          description: Unique identifier of the created review request.
        reviewerId:
          type: string
          description: ID of the reviewer the request was created for.
      required:
      - id
      - reviewerId
      type: object
      additionalProperties: false
    CreateReviewRequestsResponse:
      properties:
        reviewObjectId:
          type: string
          description: ID of the review object the requests were created under.
        assignments:
          items:
            $ref: '#/components/schemas/ReviewAssignmentResponse'
          type: array
          description: Created review requests, grouped by template.
      required:
      - reviewObjectId
      - assignments
      type: object
      additionalProperties: false
    FieldErrors:
      properties: {}
      type: object
      additionalProperties:
        properties:
          value: {}
          message:
            type: string
        required:
        - message
        type: object
    IndependentReviewObjectInput:
      description: Links the review to an object outside of Cosuno (e.g. a contract managed in your ERP).
      properties:
        name:
          type: string
          description: Human-readable name of the object the review is about.
          maxLength: 150
        externalId:
          type: string
          description: Optional identifier from your external system. Must be unique per company. Reusing the same `externalId` on subsequent calls for the same subcontractor aggregates the reviews under one object; the latest `name` overwrites the stored one. Without an `externalId`, each call creates a new object.
          maxLength: 255
      required:
      - name
      type: object
      additionalProperties: false
    ReviewAssignmentInput:
      properties:
        templateId:
          type: string
          description: ID of the review template the reviewers should fill in.
        reviewerIds:
          items:
            type: string
          type: array
          description: IDs of the users to ask for reviews. Reviewers must be active users of the same company as the caller.
          minItems: 1
        step:
          type: number
          format: double
          description: Required when `sequential` is `true`. 1-indexed position of this template in the dispatch order; values must be unique and contiguous across assignments.
          minimum: 1
      required:
      - templateId
      - reviewerIds
      type: object
      additionalProperties: false
    ReviewAssignmentResponse:
      properties:
        templateId:
          type: string
          description: ID of the review template this group of requests was created for.
        requests:
          items:
            $ref: '#/components/schemas/CreatedReviewRequest'
          type: array
          description: One entry per reviewer in the corresponding input assignment.
      required:
      - templateId
      - requests
      type: object
      additionalProperties: false
    USER_TYPE:
      type: string
      enum:
      - custom
      - administrator
      - employee
      - guest
      - collaborator
      - manager
    BidPackageLinkedReviewObjectResponse:
      description: Object under review, linked to a bid package in Cosuno.
      properties:
        type:
          type: string
          enum:
          - bidPackage
          description: Discriminator. Always `bidPackage` for this variant.
        bidRequestId:
          type: string
          description: ID of the bid request (subcontractor + bid package pair) the review/request is linked to.
        bidPackageId:
          type: string
          description: ID of the bid package the bid request belongs to.
        projectId:
          type: string
          description: ID of the project the bid package belongs to.
      required:
      - type
      - bidRequestId
      - bidPackageId
      - projectId
      type: object
      additionalProperties: false
    USER_STATUS:
      type: string
      enum:
      - approvalPending
      - adminApprovalPending
      - invited
      - inviteCanceled
      - inviteFailed
      - inviteRequested
      - active
      - inactive
    ReviewRequestResponse:
      description: A request asking a user to review a subcontractor. May be pending, dispatched, completed, or skipped — derive the state from the timestamps below.
      properties:
        id:
          type: string
          description: Unique identifier of the review request.
        createdAt:
          type: string
          description: Timestamp at which the request was created.
        dispatchedAt:
          type:
          - string
          - 'null'
          description: Timestamp at which the request was dispatched (notification sent to the reviewer). Non-sequential requests are dispatched immediately on creation. Sequential requests are dispatched only once all earlier steps have completed or been skipped, and stay `null` until then.
        completedAt:
          type:
          - string
          - 'null'
          description: Timestamp at which the reviewer submitted their review for this request, or `null` if not submitted yet.
        skippedAt:
          type:
          - string
          - 'null'
          description: Timestamp at which this request was auto-skipped after the dispatch period expired without a submission, or `null` otherwise.
        batchId:
          type: string
          description: Identifier shared by all requests that were created together in a single call. Groups sequential and parallel requests sent as one batch.
        step:
          type:
          - number
          - 'null'
          format: double
          description: 1-indexed step of this request within a sequential batch. `null` for non-sequential requests.
        subcontractor:
          $ref: '#/components/schemas/ReviewSubcontractorResponse'
          description: Subcontractor the request is about.
        object:
          $ref: '#/components/schemas/ReviewObjectResponse'
          description: Object the request is about.
        template:
          $ref: '#/components/schemas/ReviewTemplateResponse'
          description: Review template (questionnaire) the reviewer is asked to fill in.
        requestedBy:
          $ref: '#/components/schemas/UserResponse'
          description: User who created the request.
        reviewer:
          $ref: '#/components/schemas/UserResponse'
          description: User asked to fill in the review.
      required:
      - id
      - createdAt
      - dispatchedAt
      - completedAt
      - skippedAt
      - batchId
      - step
      - subcontractor
      - object
      - template
      - requestedBy
      - reviewer
      type: object
      additionalProperties: false
    ReviewObjectResponse:
      anyOf:
      - $ref: '#/components/schemas/BidPackageLinkedReviewObjectResponse'
      - $ref: '#/components/schemas/IndependentReviewObjectResponse'
      description: Object the review or request is about. Either tied to a Cosuno bid package, or an independent object identified by name (and optionally an external ID).
    ErrorResponse:
      properties:
        message:
          type: string
        meta:
          properties:
            fieldErrors:
              $ref: '#/components/schemas/FieldErrors'
          required:
          - fieldErrors
          type: object
      required:
      - message
      type: object
      additionalProperties: false
    BidPackageLinkedReviewObjectInput:
      description: Links the review to a bid package the subcontractor has been invited to.
      properties:
        bidPackageId:
          type: string
          description: Unique identifier of the bid package. The subcontractor must already have been invited to bid on it.
      required:
      - bidPackageId
      type: object
      additionalProperties: false
    ReviewResponse:
      description: A submitted review.
      properties:
        id:
          type: string
          description: Unique identifier of the review.
        submittedAt:
          type: string
          description: Timestamp at which the reviewer submitted the review.
        subcontractor:
          $ref: '#/components/schemas/ReviewSubcontractorResponse'
          description: Subcontractor the review is about.
        object:
          $ref: '#/components/schemas/ReviewObjectResponse'
          description: Object the review is about.
        template:
          $ref: '#/components/schemas/ReviewTemplateResponse'
          description: Review template (questionnaire) the reviewer filled in.
        reviewer:
          $ref: '#/components/schemas/UserResponse'
          description: User who submitted the review.
        ratings:
          items:
            $ref: '#/components/schemas/ReviewRatingResponse'
          type: array
          description: Per-category ratings the reviewer submitted.
      required:
      - id
      - submittedAt
      - subcontractor
      - object
      - template
      - reviewer
      - ratings
      type: object
      additionalProperties: false
    ReviewTemplateResponse:
      description: Review template (questionnaire) the review or request uses.
      properties:
        id:
          type: string
          description: Unique identifier of the review template.
        name:
          type: string
          description: Name of the review template.
      required:
      - id
      - name
      type: object
      additionalProperties: false
    UserResponse:
      properties:
        id:
          type: string
          description: ID of the user.
        email:
          type: string
          description: Email address of the user. Also used as their login identifier.
        status:
          $ref: '#/components/schemas/USER_STATUS'
          description: Current status of the user.
        firstName:
          type: string
          description: Given name of the user.
        lastName:
          type: string
          description: Family name of the user.
        type:
          $ref: '#/components/schemas/USER_TYPE'
          description: Account type of the user. Values starting with `custom` indicate a custom user role (see `customUserRoleId`).
        customUserRoleId:
          type: string
          description: ID of the custom user role assigned to the user. Present only when `type` refers to a custom user role.
      required:
      - id
      - email
      - status
      - type
      type: object
      additionalProperties: false
    IndependentReviewObjectResponse:
      description: Object under review, independent of any Cosuno bid package.
      properties:
        type:
          type: string
          enum:
          - independent
          description: Discriminator. Always `independent` for this variant.
        name:
          type: string
          description: Human-readable name of the object under review.
        externalId:
          type: string
          description: Identifier of the object in your external system, if any.
      required:
      - type
      - name
      type: object
      additionalProperties: false
    CreateReviewRequestsInput:
      properties:
        subcontractorId:
          type: string
          description: ID of the subcontractor being reviewed.
        object:
          anyOf:
          - $ref: '#/components/schemas/BidPackageLinkedReviewObjectInput'
          - $ref: '#/components/schemas/IndependentReviewObjectInput'
          description: The object the reviews are about. Either a bid package the subcontractor has been invited to, or an independent object with name.
        assignments:
          items:
            $ref: '#/components/schemas/ReviewAssignmentInput'
          type: array
          description: Templates to request reviews for. Each entry pairs a template with the reviewers who should fill it in.
          minItems: 1
        sequential:
          type: boolean
          description: When `true`, reviewers are notified one step at a time. Step N+1 starts once every reviewer in step N has submitted or has been auto-skipped after a period of inactivity.
      required:
      - subcontractorId
      - object
      - assignments
      type: object
      additionalProperties: false
  securitySchemes:
    accessKey:
      type: http
      scheme: bearer
      bearerFormat: JWT