ConnectCloud Developers

List contracts (tenant:trade:contract:read)

GET /api/trade/v1/contracts

Module: Trade · operationId: listContracts · Tag: Contracts · Auth: access token (Authorization: Bearer <accessToken>)

Newest first (creation time, then id), without contingents and links; pages by keyset (nextCursor).

Parameters

Name In Type Required Description
search query string Substring of the number, the partner's number or the partner name (case-insensitive).
type query ContractType (one of CUSTOMER, SUPPLIER)
status query ContractStatus (one of DRAFT, ACTIVE, EXPIRED, TERMINATED, CANCELLED)
limit query integer 1–100 (else 400 invalid). (default 50; max 100)
cursor query string The nextCursor of the previous page; omit for the first page. A cursor of another list is 400 invalid.

Responses

  • 200 A page of contracts (application/json)
  • 400 Error (application/json)
  • 401 No valid session or bearer token (no body).

Fields of the 200 answer:

  • items (array of Contract, required)
    • autoRenew (boolean): The contract renews automatically.
    • backToBackLinks (array of BackToBackLink, read-only): Back-to-back links of the contract.
      • allocatedMargin (number): Margin allocated to the link.
      • createdAt (string (date-time), read-only): When the link was created.
      • customerContractId (string (uuid)): Id of the customer contract.
      • customerNo (string, read-only): Customer number of the tenant.
      • id (string (uuid), read-only): Id of the back-to-back link.
      • notes (string): Free-text notes.
      • supplierContractId (string (uuid)): Id of the supplier contract.
      • tenantName (string, read-only): Name of the tenant.
    • billingCadence (string): How often the contract is billed. (one of MONTHLY, QUARTERLY, SEMI_ANNUALLY, ANNUALLY, ONE_OFF)
    • contingentPots (array of object): Hour contingents; only written on create.
      • contractId (string (uuid), read-only): Id of the contract.
      • createdAt (string (date-time), read-only): When the hour contingent was created.
      • id (string (uuid), read-only): Id of the hour contingent.
      • name (string): Name of the hour contingent.
      • remainingHours (number, read-only): Hours left.
      • rolloverAllowed (boolean): Unused hours roll over into the next period.
      • totalHours (number): Hours of the contingent.
      • updatedAt (string (date-time), read-only): When the hour contingent was last changed.
      • usedHours (number): Hours used.
      • validUntil (string (date-time)): Last day the hours can be used.
    • contractNumber (string): CTR-<n> when empty on create; never changed by an update.
    • contractType (ContractType): (one of CUSTOMER, SUPPLIER)
    • createdAt (string (date-time), read-only): When the contract was created.
    • cspSubscriptionId (string): Microsoft CSP subscription of the contract.
    • cspTenantId (string): Microsoft CSP tenant.
    • currency (string): Currency (ISO 4217).
    • customerNo (string, read-only): Customer number of the tenant.
    • description (string): Description of the contract.
    • endDate (string (date-time)): End of the contract; absent when open-ended.
    • id (string (uuid), read-only): Id of the contract.
    • leasingRate (number): Leasing rate per billing period.
    • marginPercentage (number): Margin in percent.
    • metadata (object): Free-form metadata.
    • netAmount (number): Net amount per billing period.
    • noticePeriodDays (integer): Notice period in days.
    • partnerId (string (uuid)): Masterdata address of the partner.
    • partnerName (string): Name of the customer or supplier.
    • startDate (string (date-time)): Start of the contract.
    • status (ContractStatus): (one of DRAFT, ACTIVE, EXPIRED, TERMINATED, CANCELLED)
    • tenantName (string, read-only): Name of the tenant.
    • title (string): Title of the contract.
    • updatedAt (string (date-time), read-only): When the contract was last changed.
  • nextCursor (string): Pass as cursor for the next page; absent on the last one.

Example 200 answer:

{
  "items": [
    {
      "autoRenew": true,
      "billingCadence": "MONTHLY",
      "contractNumber": "V-2026-0007",
      "contractType": "CUSTOMER",
      "createdAt": "2025-12-12T10:00:00Z",
      "currency": "EUR",
      "id": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
      "netAmount": 180,
      "noticePeriodDays": 90,
      "partnerId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02",
      "partnerName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
      "startDate": "2026-01-01T00:00:00Z",
      "status": "ACTIVE",
      "title": "Managed Service Arbeitsplätze und Microsoft 365",
      "updatedAt": "2026-10-02T08:15:00Z"
    },
    {
      "autoRenew": true,
      "billingCadence": "MONTHLY",
      "contractNumber": "LV-2026-0003",
      "contractType": "SUPPLIER",
      "createdAt": "2025-12-15T08:00:00Z",
      "currency": "EUR",
      "id": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a03",
      "netAmount": 79,
      "noticePeriodDays": 30,
      "partnerId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d03",
      "partnerName": "CloudNine Hosting AG",
      "startDate": "2026-01-01T00:00:00Z",
      "status": "ACTIVE",
      "title": "Managed Server kanzlei-srv01",
      "updatedAt": "2025-12-15T08:00:00Z"
    }
  ],
  "nextCursor": "Y3JlYXRlZHwyMDI1LTEyLTEyVDEwOjAwOjAwWnwwZTFmMmEzYi00YzVkLTRlNmYtOGE3Yi05YzBkMWUyZjNhMDc"
}

Example request

curl -X GET 'https://api.mbcom.cloud/api/trade/v1/contracts' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

View as Markdown · Interactive reference · OpenAPI