Securities API reference

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.

curl https://launchboard.xyz/api/v1/securities \
  -H "Authorization: Bearer pg_live_your_key"

curl "https://launchboard.xyz/api/v1/securities?type=STOCK_OPTION&stakeholderId=abc123" \
  -H "Authorization: Bearer pg_live_your_key"

Query parameters

string

Filter by security type. One of STOCK, STOCK_OPTION, WARRANT, or CONVERTIBLE.

string

Return only securities belonging to this stakeholder UUID.

number

default:"25"

Maximum results per page. Capped at 100.

string

Opaque cursor from the previous response’s nextCursor field.

Response

object[]

Array of security objects.

Show Security fields

string

UUID of the security.

string

UUID of the owning organization.

string

STOCK, STOCK_OPTION, WARRANT, or CONVERTIBLE.

string

Lifecycle status: ACTIVE, CANCELLED, EXERCISED, CONVERTED, REPURCHASED, or TRANSFERRED.

string | null

UUID of the stakeholder who holds this security.

string | null

UUID of the associated share class.

string | null

UUID of the associated equity plan (options and RSUs).

string | null

UUID of the vesting terms applied to this security.

string | null

Your internal certificate or grant number.

string | null

Number of shares or units, as a decimal string.

Per-share price at issuance, as a decimal string.

string | null

Total purchase consideration paid, as a decimal string.

string | null

Date the security was granted, in YYYY-MM-DD format.

string | null

Date the security expires (options and warrants), in YYYY-MM-DD format.

string | null

Free-text notes.

string

UNVERIFIED or VERIFIED.

string

ISO-8601 timestamp with timezone offset.

string

ISO-8601 timestamp with timezone offset.

string | null

Cursor for the next page. null on the last page.

Issue a security

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

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"
  }'

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"
  }'

Request body

string

required

Your internal certificate or grant identifier. Maximum 50 characters (e.g., "CS-0001", "OPT-0042").

string

required

Security type: STOCK, STOCK_OPTION, WARRANT, or CONVERTIBLE.

string

default:"ACTIVE"

Initial lifecycle status. One of ACTIVE, CANCELLED, EXERCISED, CONVERTED, REPURCHASED, TRANSFERRED.

string

required

UUID of the stakeholder receiving this security.

string

UUID of the share class this security belongs to.

string

UUID of the equity plan this security is issued under. Required for options and RSUs.

string

required

Number of shares or units as a positive numeric string.

Per-share price at issuance, as a numeric string.

string

Strike price for options and warrants, as a numeric string.

string

Total purchase price paid, as a numeric string.

string

Option tax treatment: ISO (incentive) or NSO (non-qualified). Required when type is STOCK_OPTION.

string

required

Date the security was granted, in YYYY-MM-DD format.

string

Expiry date for options and warrants, in YYYY-MM-DD format.

string

UUID of the vesting terms to apply.

string

Vesting commencement date, in YYYY-MM-DD format. Defaults to grantDate if omitted.

string

UUID of the 409A or board valuation in effect at grant date.

string

Date the board approved this grant, in YYYY-MM-DD format.

string

Free-text notes. Maximum 2000 characters.

string

UUID of the grant agreement or other source document.

Response

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

Get a security

curl https://launchboard.xyz/api/v1/securities/abc123 \
  -H "Authorization: Bearer pg_live_your_key"

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.

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."
  }'

Request body

All fields from the create request body are accepted (except sourceDocumentId); all are optional for PATCH. Returns 200 OK with the updated security object.

Delete a security

curl -X DELETE https://launchboard.xyz/api/v1/securities/abc123 \
  -H "Authorization: Bearer pg_live_your_key"

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.

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

Overview

Cap Table

Transactions

Data & Export

Webhooks

Securities API reference

Endpoints

List securities

Query parameters

Response

Issue a security

Request body

Response

Get a security

Update a security

Request body

Delete a security

Common errors

​Endpoints

​List securities

​Query parameters

​Response

​Issue a security

​Request body

​Response

​Get a security

​Update a security

​Request body

​Delete a security

​Common errors

Endpoints

List securities

Query parameters

Response

Issue a security

Request body

Response

Get a security

Update a security

Request body

Delete a security

Common errors