ghostfolio/specs/001-family-office-transform/contracts/partnership-api.md

REST API Contracts: Partnership Management

Base Path: /api/v1/partnership Auth: All endpoints require AuthGuard('jwt') + HasPermissionGuard

Endpoints

POST /api/v1/partnership

Create a new partnership.

Permission: createPartnership

Request Body (CreatePartnershipDto):

{
  "name": "Smith Capital Partners LP",
  "type": "LP",
  "inceptionDate": "2020-01-15",
  "fiscalYearEnd": 12,
  "currency": "USD"
}

Field	Type	Required	Validation
name	string	Yes	Non-empty, trimmed
type	PartnershipType	Yes	Valid enum
inceptionDate	ISO date	Yes	Must be in the past
fiscalYearEnd	number	No	1-12, default 12
currency	string	Yes	Valid currency code

Response 201 Created: Partnership object.

---

GET /api/v1/partnership

List all partnerships for the authenticated user.

Response 200 OK:

[
  {
    "id": "uuid",
    "name": "Smith Capital Partners LP",
    "type": "LP",
    "inceptionDate": "2020-01-15T00:00:00.000Z",
    "currency": "USD",
    "latestNav": 5000000,
    "latestNavDate": "2025-12-31T00:00:00.000Z",
    "membersCount": 3,
    "assetsCount": 5
  }
]

---

GET /api/v1/partnership/:partnershipId

Get partnership detail with members, assets, and latest valuation.

Response 200 OK:

{
  "id": "uuid",
  "name": "Smith Capital Partners LP",
  "type": "LP",
  "inceptionDate": "2020-01-15T00:00:00.000Z",
  "fiscalYearEnd": 12,
  "currency": "USD",
  "latestValuation": {
    "date": "2025-12-31",
    "nav": 5000000,
    "source": "NAV_STATEMENT"
  },
  "members": [
    {
      "id": "uuid",
      "entityId": "uuid",
      "entityName": "Smith Family Trust",
      "ownershipPercent": 60,
      "capitalCommitment": 3000000,
      "capitalContributed": 2500000,
      "classType": "Class A LP",
      "allocatedNav": 3000000,
      "effectiveDate": "2020-01-15T00:00:00.000Z"
    }
  ],
  "assets": [
    {
      "id": "uuid",
      "name": "123 Main Street",
      "assetType": "REAL_ESTATE",
      "currentValue": 2000000,
      "acquisitionCost": 1500000,
      "currency": "USD"
    }
  ],
  "totalCommitment": 5000000,
  "totalContributed": 4000000
}

---

PUT /api/v1/partnership/:partnershipId

Update partnership details.

Permission: updatePartnership

Request Body (UpdatePartnershipDto):

{
  "name": "Smith Capital Partners LP (Series A)",
  "fiscalYearEnd": 3
}

Response 200 OK: Updated partnership object.

---

DELETE /api/v1/partnership/:partnershipId

Delete a partnership and cascade to all related data.

Permission: deletePartnership

Response 200 OK: Empty body.

---

POST /api/v1/partnership/:partnershipId/member

Add a member entity to the partnership.

Permission: updatePartnership

Request Body (CreatePartnershipMembershipDto):

{
  "entityId": "uuid",
  "ownershipPercent": 25,
  "capitalCommitment": 1250000,
  "capitalContributed": 1000000,
  "classType": "Class A LP",
  "effectiveDate": "2020-01-15"
}

Response 201 Created: Membership record. Error 400 Bad Request: Total membership percentages would exceed 100%.

---

PUT /api/v1/partnership/:partnershipId/member/:membershipId

Update a membership (e.g., change percentage, add contribution).

Permission: updatePartnership

Response 200 OK: Updated membership record.

---

POST /api/v1/partnership/:partnershipId/valuation

Record a NAV statement for the partnership.

Permission: updatePartnership

Request Body (CreatePartnershipValuationDto):

{
  "date": "2025-12-31",
  "nav": 5000000,
  "source": "NAV_STATEMENT",
  "notes": "Q4 2025 fund admin statement"
}

Response 201 Created: Valuation record. Error 409 Conflict: Valuation already exists for this date.

---

GET /api/v1/partnership/:partnershipId/valuations

Get valuation history for a partnership.

Query Parameters:

Param	Type	Required	Default
startDate	ISO date	No	—
endDate	ISO date	No	—

Response 200 OK:

[
  {
    "id": "uuid",
    "date": "2025-12-31",
    "nav": 5000000,
    "source": "NAV_STATEMENT"
  },
  {
    "id": "uuid",
    "date": "2025-09-30",
    "nav": 4800000,
    "source": "NAV_STATEMENT"
  }
]

---

POST /api/v1/partnership/:partnershipId/asset

Add an underlying asset to the partnership.

Permission: updatePartnership

Request Body (CreatePartnershipAssetDto):

{
  "name": "123 Main Street",
  "assetType": "REAL_ESTATE",
  "description": "4-unit multifamily in Austin, TX",
  "acquisitionDate": "2021-06-01",
  "acquisitionCost": 1500000,
  "currentValue": 2000000,
  "currency": "USD",
  "metadata": { "address": "123 Main St, Austin, TX 78701", "units": 4 }
}

Response 201 Created: Partnership asset record.

---

POST /api/v1/partnership/:partnershipId/asset/:assetId/valuation

Record a valuation for a partnership asset.

Permission: updatePartnership

Request Body:

{
  "date": "2025-12-31",
  "value": 2200000,
  "source": "APPRAISAL",
  "notes": "Annual appraisal by Jones & Co."
}

Response 201 Created: Asset valuation record.

---

GET /api/v1/partnership/:partnershipId/performance

Get partnership performance metrics with optional benchmark comparison.

Query Parameters:

Param	Type	Required	Default	Description
periodicity	MONTHLY | QUARTERLY | YEARLY	No	QUARTERLY	Return period size
benchmarks	string (comma-separated)	No	—	Benchmark IDs (e.g., SP500,REAL_ESTATE)
startDate	ISO date	No	inception	Date range start
endDate	ISO date	No	latest	Date range end

Response 200 OK:

{
  "partnershipId": "uuid",
  "partnershipName": "Smith Capital Partners LP",
  "metrics": {
    "irr": 0.12,
    "tvpi": 1.3,
    "dpi": 0.4,
    "rvpi": 0.9
  },
  "periods": [
    {
      "periodStart": "2025-10-01",
      "periodEnd": "2025-12-31",
      "returnPercent": 0.042,
      "startNav": 4800000,
      "endNav": 5000000,
      "contributions": 0,
      "distributions": 50000
    }
  ],
  "benchmarkComparisons": [
    {
      "id": "SP500",
      "name": "S&P 500",
      "periods": [
        {
          "periodStart": "2025-10-01",
          "periodEnd": "2025-12-31",
          "returnPercent": 0.038
        }
      ],
      "cumulativeReturn": 0.45,
      "excessReturn": 0.05
    }
  ]
}