> ## Documentation Index
> Fetch the complete documentation index at: https://docs.launchboard.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Valuations API reference

> Record and manage 409A appraisals, board-determined fair market values, and financing round valuations linked to securities on your cap table.

Valuations establish the fair market value of a share class at a point in time. Launchboard supports three valuation types: `409A` (independent appraisals required for option pricing under IRS Section 409A), `BOARD` (board-determined valuations for early-stage companies), and `FINANCING` (valuations implied by a priced financing round). When you issue a stock option, you reference a valuation to establish the exercise price. The API lets you record valuations, track their approval workflow (`DRAFT` → `PENDING_APPROVAL` → `APPROVED`), and mark them as `EXPIRED` when superseded.

## Endpoints

| Method   | Path                      | Description                        |
| -------- | ------------------------- | ---------------------------------- |
| `GET`    | `/api/v1/valuations`      | List valuations (cursor-paginated) |
| `POST`   | `/api/v1/valuations`      | Create a valuation                 |
| `GET`    | `/api/v1/valuations/{id}` | Get a single valuation             |
| `PATCH`  | `/api/v1/valuations/{id}` | Partially update a valuation       |
| `DELETE` | `/api/v1/valuations/{id}` | Delete a valuation                 |

***

## List valuations

Returns a cursor-paginated list of all valuations for your organization, ordered by creation date descending.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://launchboard.xyz/api/v1/valuations \
    -H "Authorization: Bearer pg_live_your_key"
  ```
</CodeGroup>

### Query parameters

<ParamField path="query.limit" type="number" default="25">
  Maximum results per page. Capped at 100.
</ParamField>

<ParamField path="query.cursor" type="string">
  Opaque cursor from the previous response's `nextCursor` field.
</ParamField>

### Response

<ResponseField name="items" type="object[]">
  Array of valuation objects.

  <Expandable title="Valuation fields">
    <ResponseField name="id" type="string">UUID of the valuation.</ResponseField>
    <ResponseField name="orgId" type="string">UUID of the owning organization.</ResponseField>
    <ResponseField name="type" type="string">Valuation type: `409A`, `BOARD`, or `FINANCING`.</ResponseField>
    <ResponseField name="status" type="string">Approval status: `DRAFT`, `PENDING_APPROVAL`, `APPROVED`, or `EXPIRED`.</ResponseField>
    <ResponseField name="stockClassId" type="string | null">UUID of the share class this valuation applies to.</ResponseField>
    <ResponseField name="pricePerShare" type="string">Fair market value per share at the effective date, as a decimal string.</ResponseField>
    <ResponseField name="effectiveDate" type="string">Date this valuation takes effect, in `YYYY-MM-DD` format.</ResponseField>
    <ResponseField name="expirationDate" type="string | null">Date this valuation expires, in `YYYY-MM-DD` format. 409A valuations typically expire after 12 months.</ResponseField>
    <ResponseField name="provider" type="string | null">Name of the appraisal firm or individual who performed the valuation.</ResponseField>
    <ResponseField name="reportId" type="string | null">Reference identifier for the valuation report.</ResponseField>
    <ResponseField name="comments" type="string | null">Free-text notes.</ResponseField>
    <ResponseField name="verificationStatus" type="string">`UNVERIFIED` or `VERIFIED`.</ResponseField>
    <ResponseField name="createdAt" type="string">ISO-8601 timestamp with timezone offset.</ResponseField>
    <ResponseField name="updatedAt" type="string">ISO-8601 timestamp with timezone offset.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="nextCursor" type="string | null">
  Cursor for the next page. `null` on the last page.
</ResponseField>

***

## Create a valuation

Records a new valuation. Start with `status: "DRAFT"` and advance to `APPROVED` once the board or appraisal firm signs off. Supports the `Idempotency-Key` header for safe retries.

<CodeGroup>
  ```bash 409A valuation theme={null}
  curl -X POST https://launchboard.xyz/api/v1/valuations \
    -H "Authorization: Bearer pg_live_your_key" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: create-409a-q1-2024" \
    -d '{
      "type": "409A",
      "status": "APPROVED",
      "pricePerShare": "1.25",
      "effectiveDate": "2024-01-01",
      "expirationDate": "2025-01-01",
      "stockClassId": "sc_common01",
      "provider": "Carta Valuations",
      "reportId": "CVA-2024-001"
    }'
  ```

  ```bash Financing round valuation theme={null}
  curl -X POST https://launchboard.xyz/api/v1/valuations \
    -H "Authorization: Bearer pg_live_your_key" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "FINANCING",
      "status": "APPROVED",
      "pricePerShare": "5.00",
      "effectiveDate": "2024-03-15",
      "stockClassId": "sc_seriesA",
      "comments": "Series A priced at $5.00/share, $50M pre-money valuation."
    }'
  ```
</CodeGroup>

### Request body

<ParamField body="type" type="string" required>
  Valuation type: `409A`, `BOARD`, or `FINANCING`.
</ParamField>

<ParamField body="status" type="string" default="DRAFT">
  Initial approval status: `DRAFT`, `PENDING_APPROVAL`, `APPROVED`, or `EXPIRED`.
</ParamField>

<ParamField body="pricePerShare" type="string" required>
  Fair market value per share as a positive numeric string (e.g., `"1.25"`).
</ParamField>

<ParamField body="effectiveDate" type="string" required>
  Date this valuation takes effect, in `YYYY-MM-DD` format.
</ParamField>

<ParamField body="stockClassId" type="string" required>
  UUID of the share class this valuation applies to.
</ParamField>

<ParamField body="provider" type="string">
  Name of the appraisal firm or valuation provider. Maximum 200 characters.
</ParamField>

<ParamField body="fairMarketValue" type="string">
  Overall company fair market value at this date, as a numeric string.
</ParamField>

<ParamField body="enterpriseValue" type="string">
  Enterprise value at this date, as a numeric string.
</ParamField>

<ParamField body="boardApprovalDate" type="string">
  Date the board approved this valuation, in `YYYY-MM-DD` format.
</ParamField>

<ParamField body="stockholderApprovalDate" type="string">
  Date stockholders approved this valuation, in `YYYY-MM-DD` format.
</ParamField>

<ParamField body="expirationDate" type="string">
  Date this valuation expires, in `YYYY-MM-DD` format. 409A valuations typically expire 12 months after the effective date or when a material event occurs.
</ParamField>

<ParamField body="comments" type="string">
  Free-text notes. Maximum 2000 characters.
</ParamField>

<ParamField body="sourceDocumentId" type="string">
  UUID of the valuation report document.
</ParamField>

### Response

Returns `201 Created` with the full valuation object and a `Location` header.

<Tip>
  When issuing stock options, set `valuationId` on the security to the UUID of the `APPROVED` 409A valuation that was in effect on the grant date. This establishes a defensible exercise price for IRS Section 409A purposes.
</Tip>

***

## Get a valuation

<CodeGroup>
  ```bash cURL theme={null}
  curl https://launchboard.xyz/api/v1/valuations/abc123 \
    -H "Authorization: Bearer pg_live_your_key"
  ```
</CodeGroup>

Returns the valuation object. Field schema is identical to the list response items.

***

## Update a valuation

Partial update — include only the fields you want to change. Use this endpoint to advance a valuation from `DRAFT` to `APPROVED` or to record an expiration.

<CodeGroup>
  ```bash Approve a draft valuation theme={null}
  curl -X PATCH https://launchboard.xyz/api/v1/valuations/abc123 \
    -H "Authorization: Bearer pg_live_your_key" \
    -H "Content-Type: application/json" \
    -d '{
      "status": "APPROVED",
      "boardApprovalDate": "2024-01-10"
    }'
  ```
</CodeGroup>

### Request body

All fields from the [create request body](#request-body-1) are accepted; all are optional for `PATCH`.

Returns `200 OK` with the updated valuation object.

***

## Delete a valuation

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://launchboard.xyz/api/v1/valuations/abc123 \
    -H "Authorization: Bearer pg_live_your_key"
  ```
</CodeGroup>

Returns `204 No Content` on success.

<Warning>
  Deleting a valuation that is referenced by existing securities may leave those securities without a valid `409A` backing. Prefer setting `status` to `EXPIRED` rather than deleting historical valuations.
</Warning>

***

## Common errors

| Status | When it occurs                                                                                  |
| ------ | ----------------------------------------------------------------------------------------------- |
| `400`  | Malformed JSON in the request body.                                                             |
| `401`  | Missing or invalid `Authorization` header.                                                      |
| `403`  | The API key role does not have `EDITOR` permission. Required for `POST`, `PATCH`, and `DELETE`. |
| `404`  | No valuation with the given `id` exists, or the referenced `stockClassId` does not exist.       |
| `422`  | Request body failed schema validation. The response includes a field-level `errors` array.      |