> ## 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.

# Securities API reference

> Issue and manage individual equity instruments — stock, stock options, warrants, and convertible notes — tied to stakeholders on your cap table.

A security represents a single equity instrument issued to a stakeholder. Launchboard supports four security types: `STOCK` (direct share ownership), `STOCK_OPTION` (the right to purchase shares at a fixed exercise price), `WARRANT` (similar to options but typically issued to investors or service providers), and `CONVERTIBLE` (instruments that convert to equity on a future event such as a priced round). Each security links a stakeholder, a share class or equity plan, optional vesting terms, and a valuation.

## Endpoints

| Method   | Path                      | Description                        |
| -------- | ------------------------- | ---------------------------------- |
| `GET`    | `/api/v1/securities`      | List securities (cursor-paginated) |
| `POST`   | `/api/v1/securities`      | Issue a new security               |
| `GET`    | `/api/v1/securities/{id}` | Get a single security              |
| `PATCH`  | `/api/v1/securities/{id}` | Partially update a security        |
| `DELETE` | `/api/v1/securities/{id}` | Delete a security                  |

***

## List securities

Returns a cursor-paginated list of securities for your organization. Filter by security `type` or `stakeholderId` to narrow results.

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

  ```bash Filter by type and stakeholder theme={null}
  curl "https://launchboard.xyz/api/v1/securities?type=STOCK_OPTION&stakeholderId=abc123" \
    -H "Authorization: Bearer pg_live_your_key"
  ```
</CodeGroup>

### Query parameters

<ParamField path="query.type" type="string">
  Filter by security type. One of `STOCK`, `STOCK_OPTION`, `WARRANT`, or `CONVERTIBLE`.
</ParamField>

<ParamField path="query.stakeholderId" type="string">
  Return only securities belonging to this stakeholder UUID.
</ParamField>

<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 security objects.

  <Expandable title="Security fields">
    <ResponseField name="id" type="string">UUID of the security.</ResponseField>
    <ResponseField name="orgId" type="string">UUID of the owning organization.</ResponseField>
    <ResponseField name="type" type="string">`STOCK`, `STOCK_OPTION`, `WARRANT`, or `CONVERTIBLE`.</ResponseField>

    <ResponseField name="status" type="string">
      Lifecycle status: `ACTIVE`, `CANCELLED`, `EXERCISED`, `CONVERTED`, `REPURCHASED`, or `TRANSFERRED`.
    </ResponseField>

    <ResponseField name="stakeholderId" type="string | null">UUID of the stakeholder who holds this security.</ResponseField>
    <ResponseField name="stockClassId" type="string | null">UUID of the associated share class.</ResponseField>
    <ResponseField name="equityPlanId" type="string | null">UUID of the associated equity plan (options and RSUs).</ResponseField>
    <ResponseField name="vestingTermsId" type="string | null">UUID of the vesting terms applied to this security.</ResponseField>
    <ResponseField name="certificateId" type="string | null">Your internal certificate or grant number.</ResponseField>
    <ResponseField name="quantity" type="string | null">Number of shares or units, as a decimal string.</ResponseField>
    <ResponseField name="pricePerShare" type="string | null">Per-share price at issuance, as a decimal string.</ResponseField>
    <ResponseField name="purchasePrice" type="string | null">Total purchase consideration paid, as a decimal string.</ResponseField>
    <ResponseField name="grantDate" type="string | null">Date the security was granted, in `YYYY-MM-DD` format.</ResponseField>
    <ResponseField name="expirationDate" type="string | null">Date the security expires (options and warrants), in `YYYY-MM-DD` format.</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>

***

## Issue a security

Creates a new security and records the issuance on the cap table ledger. Supports the `Idempotency-Key` header for safe retries.

<CodeGroup>
  ```bash Stock option theme={null}
  curl -X POST https://launchboard.xyz/api/v1/securities \
    -H "Authorization: Bearer pg_live_your_key" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: grant-abc123-2024" \
    -d '{
      "certificateId": "OPT-0042",
      "type": "STOCK_OPTION",
      "status": "ACTIVE",
      "stakeholderId": "stk_abc123",
      "stockClassId": "sc_common01",
      "stockPlanId": "ep_2020plan",
      "quantity": "50000",
      "exercisePrice": "1.25",
      "optionType": "ISO",
      "grantDate": "2024-01-15",
      "expirationDate": "2034-01-15",
      "vestingTermsId": "vt_4yr1yr"
    }'
  ```

  ```bash Stock issuance theme={null}
  curl -X POST https://launchboard.xyz/api/v1/securities \
    -H "Authorization: Bearer pg_live_your_key" \
    -H "Content-Type: application/json" \
    -d '{
      "certificateId": "CS-0001",
      "type": "STOCK",
      "status": "ACTIVE",
      "stakeholderId": "stk_founder1",
      "stockClassId": "sc_common01",
      "quantity": "5000000",
      "pricePerShare": "0.0001",
      "grantDate": "2022-03-01"
    }'
  ```
</CodeGroup>

### Request body

<ParamField body="certificateId" type="string" required>
  Your internal certificate or grant identifier. Maximum 50 characters (e.g., `"CS-0001"`, `"OPT-0042"`).
</ParamField>

<ParamField body="type" type="string" required>
  Security type: `STOCK`, `STOCK_OPTION`, `WARRANT`, or `CONVERTIBLE`.
</ParamField>

<ParamField body="status" type="string" default="ACTIVE">
  Initial lifecycle status. One of `ACTIVE`, `CANCELLED`, `EXERCISED`, `CONVERTED`, `REPURCHASED`, `TRANSFERRED`.
</ParamField>

<ParamField body="stakeholderId" type="string" required>
  UUID of the stakeholder receiving this security.
</ParamField>

<ParamField body="stockClassId" type="string">
  UUID of the share class this security belongs to.
</ParamField>

<ParamField body="stockPlanId" type="string">
  UUID of the equity plan this security is issued under. Required for options and RSUs.
</ParamField>

<ParamField body="quantity" type="string" required>
  Number of shares or units as a positive numeric string.
</ParamField>

<ParamField body="pricePerShare" type="string">
  Per-share price at issuance, as a numeric string.
</ParamField>

<ParamField body="exercisePrice" type="string">
  Strike price for options and warrants, as a numeric string.
</ParamField>

<ParamField body="totalConsideration" type="string">
  Total purchase price paid, as a numeric string.
</ParamField>

<ParamField body="optionType" type="string">
  Option tax treatment: `ISO` (incentive) or `NSO` (non-qualified). Required when `type` is `STOCK_OPTION`.
</ParamField>

<ParamField body="grantDate" type="string" required>
  Date the security was granted, in `YYYY-MM-DD` format.
</ParamField>

<ParamField body="expirationDate" type="string">
  Expiry date for options and warrants, in `YYYY-MM-DD` format.
</ParamField>

<ParamField body="vestingTermsId" type="string">
  UUID of the vesting terms to apply.
</ParamField>

<ParamField body="vestingStartDate" type="string">
  Vesting commencement date, in `YYYY-MM-DD` format. Defaults to `grantDate` if omitted.
</ParamField>

<ParamField body="valuationId" type="string">
  UUID of the 409A or board valuation in effect at grant date.
</ParamField>

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

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

<ParamField body="sourceDocumentId" type="string">
  UUID of the grant agreement or other source document.
</ParamField>

### Response

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

***

## Get a security

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

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

***

## Update a security

Partial update — include only the fields you want to change.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH https://launchboard.xyz/api/v1/securities/abc123 \
    -H "Authorization: Bearer pg_live_your_key" \
    -H "Content-Type: application/json" \
    -d '{
      "status": "CANCELLED",
      "comments": "Cancelled upon employee departure."
    }'
  ```
</CodeGroup>

### Request body

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

Returns `200 OK` with the updated security object.

***

## Delete a security

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

Returns `204 No Content` on success.

***

## 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 security with the given `id` exists, or a referenced `stakeholderId`, `stockClassId`, or `stockPlanId` does not exist. |
| `422`  | Request body failed schema validation. The response includes a field-level `errors` array.                                |

<Note>
  Decimal amounts (`quantity`, `pricePerShare`, `exercisePrice`, etc.) are always serialized as strings in both requests and responses to preserve numeric precision.
</Note>