Cosuno Awarded Bids API

openapi: 3.2.0
info:
  title: Cosuno Awarded Bids API
  version: '1'
  description: '-'
  license:
    name: '-'
  contact:
    name: '-'
servers:
- url: https://api.cosuno.com/v1
- description: current
  url: /v1
tags:
- name: Awarded Bids
paths:
  /awarded-bids:
    get:
      operationId: GetAwardedBids
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/AwardedBidWithBidRequestResponse'
                type: array
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          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 all awarded bids across your company, each including the bid request and bid package they belong to. Use this endpoint to keep external systems in sync with awarded tenders.
      tags:
      - Awarded Bids
      security:
      - accessKey: []
      parameters:
      - description: Number of awarded bids to skip before returning results; used together with `limit` to paginate. Defaults to `0`.
        in: query
        name: offset
        required: false
        schema:
          default: 0
          format: double
          type: number
      - description: Maximum number of awarded bids to return in a single response. Defaults to `50` and is capped at `100`.
        in: query
        name: limit
        required: false
        schema:
          default: 50
          format: double
          type: number
      summary: Get awarded bids
      x-summary-source: derived
components:
  schemas:
    CURRENCY:
      type: string
      enum:
      - EUR
      - ALL
      - AMD
      - AZN
      - BYN
      - BAM
      - BGN
      - HRK
      - CZK
      - DKK
      - GEL
      - HUF
      - ISK
      - CHF
      - MDL
      - MKD
      - NOK
      - PLN
      - RON
      - RUB
      - RSD
      - SEK
      - TRY
      - UAH
      - GBP
    BidPackageUserResponse:
      properties:
        userRole:
          type: string
          description: Role of the user on the bid package (e.g. bid package manager, team member). Accepted values depend on your company's configuration.
        isContactPerson:
          type: boolean
          description: Whether this user is designated as a contact person for subcontractors on the bid package.
        user:
          $ref: '#/components/schemas/UserResponse'
          description: The user assigned to the bid package.
      required:
      - userRole
      - isContactPerson
      - user
      type: object
      additionalProperties: false
    COMPANY_SIZE:
      type: string
      enum:
      - size_1_4
      - size_5_9
      - size_10_19
      - size_20_49
      - size_50_99
      - size_100_199
      - size_200_499
      - size_500plus
    BID_PACKAGE_STATUS:
      type: string
      enum:
      - draft
      - published
      - closed
      - inNegotiation
      - bidAwarded
      - contractSigning
      - contracted
    CONTACT_TITLE:
      type: string
      enum:
      - mr
      - ms
    AwardedBidWithBidRequestResponse:
      properties:
        id:
          type: string
          description: ID of the bid.
        message:
          type:
          - string
          - 'null'
          description: Free-form message submitted by the subcontractor alongside the bid.
        totalNet:
          type: number
          format: double
          description: Net total of the bid before discount and tax, in the bid package's currency.
        discountRate:
          type: number
          format: double
          description: Discount rate offered by the subcontractor, expressed as a fraction between 0 and 1 (e.g. 0.05 for 5%).
        taxRate:
          type: number
          format: double
          description: Value-added tax rate applied to the bid, expressed as a fraction between 0 and 1.
        skontoRate:
          type: number
          format: double
          description: Early-payment discount (skonto) rate offered by the subcontractor, expressed as a fraction between 0 and 1.
        skontoDeadline:
          type: number
          format: double
          description: Number of days within which the early-payment discount (skonto) applies.
        revision:
          type: number
          format: double
          description: Revision number of the bid. Increments each time the subcontractor submits a revised bid.
        hasBillOfQuantities:
          type: boolean
          description: Whether the bid includes a priced bill of quantities.
        absoluteDiscount:
          type: number
          format: double
          description: Fixed absolute discount applied on top of the bid total, in the bid package's currency.
        additionalCosts:
          type: number
          format: double
          description: Additional costs included in the awarded bid beyond the priced bill of quantities, in the bid package's currency.
        skontoValue:
          type: number
          format: double
          description: Monetary amount corresponding to `skontoRate` applied to the net total with discount.
        totalNetWithDiscount:
          type: number
          format: double
          description: Net total after applying discount, in the bid package's currency.
        taxValue:
          type: number
          format: double
          description: Monetary amount of VAT applied to the bid.
        totalGross:
          type: number
          format: double
          description: Gross total of the bid (net with discount plus tax), in the bid package's currency.
        totalGrossWithSkonto:
          type: number
          format: double
          description: Gross total after applying the early-payment discount (skonto), in the bid package's currency.
        awardedAt:
          type: string
          description: Timestamp at which the bid was awarded.
          format: date
        bidRequest:
          allOf:
          - $ref: '#/components/schemas/Omit_BidRequestResponse.currentBid-or-awardedBid_'
          - properties:
              bidPackage:
                $ref: '#/components/schemas/BidPackageResponse'
            required:
            - bidPackage
            type: object
          description: Bid request the awarded bid was submitted against, along with its parent bid package.
      required:
      - id
      - message
      - totalNet
      - discountRate
      - taxRate
      - skontoRate
      - skontoDeadline
      - revision
      - hasBillOfQuantities
      - absoluteDiscount
      - additionalCosts
      - skontoValue
      - totalNetWithDiscount
      - taxValue
      - totalGross
      - totalGrossWithSkonto
      - awardedAt
      - bidRequest
      type: object
      additionalProperties: false
    ContactResponse:
      properties:
        isPerson:
          type: boolean
          description: Whether this contact represents an individual person (`true`) or a generic company contact channel such as a shared inbox or department (`false`).
        email:
          type:
          - string
          - 'null'
          description: Email address of the contact.
          format: email
          maxLength: 200
        title:
          allOf:
          - $ref: '#/components/schemas/CONTACT_TITLE'
          description: Form of address (e.g. Mr., Mrs., Dr.).
          maxLength: 200
        firstName:
          type:
          - string
          - 'null'
          description: Given name of the contact.
          maxLength: 100
        lastName:
          type:
          - string
          - 'null'
          description: Family name of the contact.
          maxLength: 100
        jobTitle:
          type:
          - string
          - 'null'
          description: Role or title of the contact within their organisation.
          maxLength: 100
        phone:
          type:
          - string
          - 'null'
          description: Business phone number of the contact.
          maxLength: 200
        mobilePhone:
          type:
          - string
          - 'null'
          description: Mobile phone number of the contact.
          maxLength: 200
        fax:
          type:
          - string
          - 'null'
          description: Fax number of the contact.
          maxLength: 200
        id:
          type: string
          description: Unique identifier of the contact.
      required:
      - isPerson
      - id
      type: object
      additionalProperties: false
    FieldErrors:
      properties: {}
      type: object
      additionalProperties:
        properties:
          value: {}
          message:
            type: string
        required:
        - message
        type: object
    STATE_CODE:
      type: string
      enum:
      - DE_BW
      - DE_BY
      - DE_BE
      - DE_BB
      - DE_HB
      - DE_HH
      - DE_HE
      - DE_MV
      - DE_NI
      - DE_NW
      - DE_RP
      - DE_SL
      - DE_SN
      - DE_ST
      - DE_SH
      - DE_TH
    BidPackageResponse:
      properties:
        name:
          type: string
          description: Name of the bid package.
          maxLength: 100
        number:
          type:
          - string
          - 'null'
          description: Internal bid package number or reference code used by your company.
          maxLength: 100
        description:
          type:
          - string
          - 'null'
          description: Longer free-form description of the bid package, shared with invited subcontractors.
        budget:
          type:
          - number
          - 'null'
          format: double
          description: Budget allocated for this bid package, in the bid package's currency.
        notes:
          type:
          - string
          - 'null'
          description: Free-form internal notes about the bid package.
        id:
          type: string
          description: ID of the bid package.
        projectId:
          type: string
          description: ID of the project the bid package belongs to.
        status:
          $ref: '#/components/schemas/BID_PACKAGE_STATUS'
          description: Current lifecycle status of the bid package.
        currency:
          $ref: '#/components/schemas/CURRENCY'
          description: Currency used for all monetary values on this bid package.
        bidsDueAt:
          type: string
          description: 'Deadline by which subcontractors must submit their bids.

            The date-time notation as defined by [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6)'
          format: date-time
        bindingPeriod:
          type: string
          description: Date until which submitted bids remain binding on the subcontractor.
          format: date
        startsOn:
          type: string
          description: Planned start date of the work covered by this bid package.
          format: date
        endsOn:
          type: string
          description: Planned end date of the work covered by this bid package.
          format: date
        primaryUser:
          $ref: '#/components/schemas/UserResponse'
          description: Primary user in charge of the bid package.
        primaryContactUser:
          $ref: '#/components/schemas/UserResponse'
          description: User designated as the primary contact for subcontractors on the bid package. Defaults to the primary user if not set explicitly.
        bidPackageUsers:
          items:
            $ref: '#/components/schemas/BidPackageUserResponse'
          type: array
          description: Users assigned to the bid package with their roles.
        isBlindTender:
          type: boolean
          description: Whether the bid package is a blind tender — bids remain sealed until the opening date.
        openingDate:
          type: string
          description: Date at which bids will be unsealed, for blind tenders.
          format: date
        isMultiAwarding:
          type: boolean
          description: Whether multiple subcontractors can be awarded portions of this bid package.
        isPublishedOnMarketplace:
          type: boolean
          description: Whether the bid package is published on the Cosuno Marketplace, making it discoverable by subcontractors outside your own network.
        publishedAt:
          type: string
          description: 'Timestamp at which the bid package was published to subcontractors. Absent if the bid package has not yet been published.

            The date-time notation as defined by [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6)'
          format: date-time
        workCategories:
          items:
            $ref: '#/components/schemas/BidPackageWorkCategoryResponse'
          type: array
          description: Work categories assigned to the bid package.
        customFields:
          items:
            $ref: '#/components/schemas/MappedCustomField'
          type: array
          description: Values for the custom fields defined on bid packages in your company.
      required:
      - name
      - id
      - projectId
      - status
      - currency
      - bidsDueAt
      - bidPackageUsers
      - isBlindTender
      - isMultiAwarding
      - isPublishedOnMarketplace
      - workCategories
      type: object
      additionalProperties: false
    ORDER_RADIUS:
      type: string
      enum:
      - km_20
      - km_50
      - km_100
      - km_200
      - km_350
      - km_500
      - km_750
      - km_1000
      - km_2000
      - km_3000
      - unlimited
    BID_INVITE_STATUS:
      type: string
      enum:
      - draft
      - opened
      - viewed
      - sent
      - failed
    USER_TYPE:
      type: string
      enum:
      - custom
      - administrator
      - employee
      - guest
      - collaborator
      - manager
    Pick_BidRequestResponse.Exclude_keyofBidRequestResponse.currentBid-or-awardedBid__:
      properties:
        id:
          type: string
          description: ID of the bid request.
        createdAt:
          type:
          - string
          - 'null'
          description: Timestamp at which the bid request was created.
          format: date
        updatedAt:
          type:
          - string
          - 'null'
          description: Timestamp at which the bid request was last updated.
          format: date
        status:
          type: string
          enum:
          - invited
          - inNegotiation
          - bidAwarded
          - pendingInvite
          - pendingApproval
          - opened
          - viewed
          - undecided
          - inviteDeclined
          - bidSubmitted
          - bidRejected
          - withdrawn
          - accepted
          - watched
          description: Current status of the bid request in its lifecycle.
        source:
          type: string
          enum:
          - invite
          - marketplace
          description: 'How the bid request originated: `invite` for subcontractors invited from your own network, `marketplace` for subcontractors who applied via the Cosuno Marketplace.'
        declinedReason:
          type:
          - string
          - 'null'
          enum:
          - other
          - insufficientCapacity
          - distanceTooLarge
          - notOfferingThisService
          - companyClosed
          - null
          description: Standardized reason the bid request was declined by the subcontractor, if any.
        declinedReasonOther:
          type:
          - string
          - 'null'
          description: Free-form text explaining the decline, provided when `declinedReason` is `other`.
        customBidsDueAt:
          type:
          - string
          - 'null'
          description: Per-bid-request override for the bid package submission deadline, if one is set.
          format: date-time
        lastStatusChangeAt:
          type:
          - string
          - 'null'
          description: Timestamp of the last status change on the bid request.
          format: date
        subcontractor:
          allOf:
          - $ref: '#/components/schemas/SubcontractorBase'
          - properties:
              externalId:
                type: string
              externalSource:
                type: string
              workCategoryNames:
                items:
                  type: string
                type: array
              id:
                type: string
            required:
            - workCategoryNames
            - id
            type: object
          description: Subcontractor the bid request is addressed to.
        bidInvites:
          items:
            $ref: '#/components/schemas/BidInviteResponse'
          type: array
          description: Invitations sent to the subcontractor's contacts for this bid request.
      required:
      - id
      - createdAt
      - updatedAt
      - status
      - source
      - declinedReason
      - declinedReasonOther
      - customBidsDueAt
      - lastStatusChangeAt
      - subcontractor
      - bidInvites
      type: object
      description: From T, pick a set of properties whose keys are in the union K
    USER_STATUS:
      type: string
      enum:
      - approvalPending
      - adminApprovalPending
      - invited
      - inviteCanceled
      - inviteFailed
      - inviteRequested
      - active
      - inactive
    ErrorResponse:
      properties:
        message:
          type: string
        meta:
          properties:
            fieldErrors:
              $ref: '#/components/schemas/FieldErrors'
          required:
          - fieldErrors
          type: object
      required:
      - message
      type: object
      additionalProperties: false
    Omit_BidRequestResponse.currentBid-or-awardedBid_:
      $ref: '#/components/schemas/Pick_BidRequestResponse.Exclude_keyofBidRequestResponse.currentBid-or-awardedBid__'
      description: Construct a type with the properties of T except for those in type K.
    SubcontractorBase:
      properties:
        name:
          type: string
          description: Company name of the subcontractor.
          maxLength: 255
        website:
          type:
          - string
          - 'null'
          description: Website URL of the subcontractor.
          maxLength: 200
        street:
          type:
          - string
          - 'null'
          description: Street address of the subcontractor's operating location.
          maxLength: 200
        postalCode:
          type:
          - string
          - 'null'
          description: Postal/ZIP code of the subcontractor's operating location.
          maxLength: 100
        city:
          type:
          - string
          - 'null'
          description: City of the subcontractor's operating location.
          maxLength: 100
        registrationPostalCode:
          type:
          - string
          - 'null'
          description: Postal/ZIP code of the subcontractor's registered (legal) address.
          maxLength: 100
        registrationCity:
          type:
          - string
          - 'null'
          description: City of the subcontractor's registered (legal) address.
          maxLength: 100
        companySize:
          allOf:
          - $ref: '#/components/schemas/COMPANY_SIZE'
          description: Size category of the subcontractor's company.
        countryCode:
          allOf:
          - $ref: '#/components/schemas/COUNTRY_CODE'
          description: ISO 3166-1 alpha-2 country code of the subcontractor's operating location.
        workCategoryNames:
          items:
            type: string
          type: array
          description: Names of the work categories (trades) the subcontractor offers.
        moreInfo:
          type:
          - string
          - 'null'
          description: Free-form internal notes about the subcontractor.
        isBanned:
          type: boolean
          description: Whether the subcontractor is blocked from being invited to tenders in your company.
        isFavorite:
          type: boolean
          description: Whether the subcontractor is marked as a favorite in your company.
        nationalId:
          type:
          - string
          - 'null'
          description: National business registration number (e.g. Handelsregisternummer in Germany).
          maxLength: 255
        foundingYear:
          type:
          - number
          - 'null'
          format: double
          description: Year the subcontractor's company was founded.
        ownerName:
          type:
          - string
          - 'null'
          description: Name of the subcontractor's owner or managing director.
          maxLength: 255
        revenueYear:
          type:
          - number
          - 'null'
          format: double
          description: Year that `yearlyRevenue` refers to.
        taxId:
          type:
          - string
          - 'null'
          description: Tax identification number (e.g. Steuernummer or USt-IdNr. in Germany).
          maxLength: 255
        yearlyRevenue:
          type:
          - number
          - 'null'
          format: double
          description: Annual revenue of the subcontractor for `revenueYear`.
        orderAreaType:
          $ref: '#/components/schemas/ORDER_AREA_TYPE'
          description: 'How the subcontractor''s service area is expressed: by radius around its location, by states, by country, or not specified.'
        orderRadius:
          allOf:
          - $ref: '#/components/schemas/ORDER_RADIUS'
          description: Radius (in km) around the subcontractor's operating location in which it accepts work. Applies when `orderAreaType` is set to the radius option.
        orderAreaStateCodes:
          items:
            $ref: '#/components/schemas/STATE_CODE'
          type:
          - array
          - 'null'
          description: State codes the subcontractor accepts work in. Applies when `orderAreaType` is set to the states option.
        orderAreaCountryCode:
          allOf:
          - $ref: '#/components/schemas/COUNTRY_CODE'
          description: ISO 3166-1 alpha-2 country code the subcontractor accepts work in. Applies when `orderAreaType` is set to the country option.
      required:
      - name
      type: object
      additionalProperties: false
    BidPackageWorkCategoryResponse:
      properties:
        id:
          type: string
          description: ID of the work category.
        name:
          type: string
          description: Name of the work category.
      required:
      - id
      - name
      type: object
      additionalProperties: false
    COUNTRY_CODE:
      type: string
      enum:
      - AW
      - AF
      - AO
      - AI
      - AX
      - AL
      - AD
      - AE
      - AR
      - AM
      - AS
      - AQ
      - TF
      - AG
      - AU
      - AT
      - AZ
      - BI
      - BE
      - BJ
      - BF
      - BD
      - BG
      - BH
      - BS
      - BA
      - BL
      - SH
      - BY
      - BZ
      - BM
      - BO
      - BQ
      - BR
      - BB
      - BN
      - BT
      - BV
      - BW
      - CF
      - CA
      - CC
      - CH
      - CL
      - CN
      - CI
      - CM
      - CD
      - CG
      - CK
      - CO
      - KM
      - CV
      - CR
      - CU
      - CW
      - CX
      - KY
      - CY
      - CZ
      - DE
      - DJ
      - DM
      - DK
      - DO
      - DZ
      - EC
      - EG
      - ER
      - EH
      - ES
      - EE
      - ET
      - FI
      - FJ
      - FK
      - FR
      - FO
      - FM
      - GA
      - GB
      - GE
      - GG
      - GH
      - GI
      - GN
      - GP
      - GM
      - GW
      - GQ
      - GR
      - GD
      - GL
      - GT
      - GF
      - GU
      - GY
      - HK
      - HM
      - HN
      - HR
      - HT
      - HU
      - ID
      - IM
      - IN
      - IO
      - IE
      - IR
      - IQ
      - IS
      - IL
      - IT
      - JM
      - JE
      - JO
      - JP
      - KZ
      - KE
      - KG
      - KH
      - KI
      - KN
      - KR
      - XK
      - KW
      - LA
      - LB
      - LR
      - LY
      - LC
      - LI
      - LK
      - LS
      - LT
      - LU
      - LV
      - MO
      - MF
      - MA
      - MC
      - MD
      - MG
      - MV
      - MX
      - MH
      - MK
      - ML
      - MT
      - MM
      - ME
      - MN
      - MP
      - MZ
      - MR
      - MS
      - MQ
      - MU
      - MW
      - MY
      - YT
      - NA
      - NC
      - NE
      - NF
      - NG
      - NI
      - NU
      - NL
      - 'NO'
      - NP
      - NR
      - NZ
      - OM
      - PK
      - PA
      - PN
      - PE
      - PH
      - PW
      - PG
      - PL
      - PR
      - KP
      - PT
      - PY
      - PS
      - PF
      - QA
      - RE
      - RO
      - RU
      - RW
      - SA
      - SD
      - SN
      - SG
      - GS
      - SJ
      - SB
      - SL
      - SV
      - SM
      - SO
      - PM
      - RS
      - SS
      - ST
      - SR
      - SK
      - SI
      - SE
      - SZ
      - SX
      - SC
      - SY
      - TC
      - TD
      - TG
      - TH
      - TJ
      - TK
      - TM
      - TL
      - TO
      - TT
      - TN
      - TR
      - TV
      - TW
      - TZ
      - UG
      - UA
      - UM
      - UY
      - US
      - UZ
      - VA
      - VC
      - VE
      - VG
      - VI
      - VN
      - VU
      - WF
      - WS
      - YE
      - ZA
      - ZM
      - ZW
    BidInviteResponse:
      properties:
        id:
          type: string
          description: ID of the bid invitation.
        status:
          $ref: '#/components/schemas/BID_INVITE_STATUS'
          description: Current status of the invitation.
        invitedAt:
          type:
          - string
          - 'null'
          description: Timestamp at which the invitation was sent out.
          format: date
        lastRemindedAt:
          type:
          - string
          - 'null'
          description: Timestamp at which the invited contact was last reminded about the invitation.
          format: date
        createdAt:
          type:
          - string
          - 'null'
          description: Timestamp at which the invitation was created.
          format: date
        updatedAt:
          type:
          - string
          - 'null'
          description: Timestamp at which the invitation was last updated.
          format: date
        contact:
          $ref: '#/components/schemas/ContactResponse'
          description: Subcontractor contact the invitation was addressed to.
      required:
      - id
      - status
      - invitedAt
      - lastRemindedAt
      - createdAt
      - updatedAt
      - contact
      type: object
      additionalProperties: false
    MappedCustomField:
      properties:
        id:
          type: string
        label:
          type: string
        value:
          anyOf:
          - type: string
          - type: number
            format: double
          - type: boolean
          - type: string
            format: date-time
          - items:
              type: string
            type: array
      required:
      - id
      - label
      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
    ORDER_AREA_TYPE:
      type: string
      enum:
      - radius
      - state
      - country
      - worldwide
  securitySchemes:
    accessKey:
      type: http
      scheme: bearer
      bearerFormat: JWT