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

# Corporate actions API reference

> Record and manage company-level equity events — stock splits, reverse splits, financing rounds, instrument conversions, and option pool changes.

Corporate actions are company-level equity events that affect the cap table broadly rather than targeting an individual security. They capture board-approved decisions such as stock splits, reverse splits, option pool increases, financing rounds, and SAFE or note conversions. Recording a corporate action in Launchboard creates an auditable history of these events alongside your transaction ledger.

Corporate actions do not automatically mutate securities. They serve as governance records — you record the action, track its status through a review workflow, and then apply the underlying ledger mutations separately using the Transactions API.

***

## List corporate actions

Returns a cursor-paginated list of corporate actions for your organization, ordered most-recent first.

**`GET /api/v1/corporate-actions`**

Requires role: **VIEWER**.

| Query param | Type    | Description                                          |
| ----------- | ------- | ---------------------------------------------------- |
| `limit`     | integer | Page size. Defaults to 25, maximum 100.              |
| `cursor`    | string  | Opaque cursor from the previous page's `nextCursor`. |

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

**Response**

```json theme={null}
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440070",
      "orgId": "550e8400-e29b-41d4-a716-446655440000",
      "type": "Stock Split",
      "title": "2-for-1 forward split — Series A close",
      "summary": "All outstanding common shares split 2-for-1 effective March 1.",
      "status": "Finalized",
      "effectiveDate": "2024-03-01",
      "metadata": {
        "boardApprovalDate": "2024-02-28",
        "stockholderApprovalDate": null,
        "documentIds": []
      },
      "createdAt": "2024-02-20T10:00:00.000Z",
      "updatedAt": "2024-03-01T08:00:00.000Z"
    }
  ],
  "nextCursor": null
}
```

<ResponseField name="data[].type" type="string">
  Corporate action type. One of: `Stock Split`, `Reverse Split`, `Option Pool Change`, `Financing Round`, `Instrument Conversion`, `Termination`.
</ResponseField>

<ResponseField name="data[].status" type="string">
  Current status. One of: `Draft`, `In Review`, `Approved`, `Finalized`.
</ResponseField>

<ResponseField name="data[].effectiveDate" type="string">
  Date the corporate action takes effect (`YYYY-MM-DD`).
</ResponseField>

<ResponseField name="data[].metadata" type="object | null">
  Optional supplementary data: `boardApprovalDate`, `stockholderApprovalDate`, `documentIds`, and free-text `notes`.
</ResponseField>

***

## Create a corporate action

Records a new corporate action. New records start in **Draft** status by default unless you explicitly set `status` to another value.

**`POST /api/v1/corporate-actions`**

Requires role: **EDITOR**. Idempotent with an `Idempotency-Key` header.

<ParamField body="type" type="string" required>
  Corporate action type. One of: `Stock Split`, `Reverse Split`, `Option Pool Change`, `Financing Round`, `Instrument Conversion`, `Termination`.
</ParamField>

<ParamField body="title" type="string" required>
  Short descriptive title (e.g. `"2-for-1 forward split — Series A close"`). Maximum 200 characters.
</ParamField>

<ParamField body="effectiveDate" type="string" required>
  Date the action takes effect (`YYYY-MM-DD`).
</ParamField>

<ParamField body="summary" type="string">
  Longer description of the action. Maximum 2000 characters.
</ParamField>

<ParamField body="status" type="string">
  Initial status. One of `Draft`, `In Review`, `Approved`, `Finalized`. Defaults to `Draft`.
</ParamField>

<ParamField body="metadata" type="object">
  Optional supplementary data.

  <Expandable title="metadata fields">
    <ParamField body="metadata.notes" type="string">
      Internal notes.
    </ParamField>

    <ParamField body="metadata.boardApprovalDate" type="string">
      Date the board approved the action (`YYYY-MM-DD`).
    </ParamField>

    <ParamField body="metadata.stockholderApprovalDate" type="string">
      Date stockholder approval was obtained (`YYYY-MM-DD`).
    </ParamField>

    <ParamField body="metadata.documentIds" type="string[]">
      Array of document IDs (UUIDs) from your dataroom that evidence this action.
    </ParamField>
  </Expandable>
</ParamField>

<CodeGroup>
  ```bash cURL — stock split theme={null}
  curl -X POST https://launchboard.xyz/api/v1/corporate-actions \
    -H "Authorization: Bearer pg_live_your_key" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: split-2for1-series-a-2024" \
    -d '{
      "type": "Stock Split",
      "title": "2-for-1 forward split — Series A close",
      "effectiveDate": "2024-03-01",
      "summary": "All outstanding common shares split 2-for-1 in connection with the Series A financing.",
      "status": "Draft",
      "metadata": {
        "boardApprovalDate": "2024-02-28",
        "notes": "Approved unanimously at the February board meeting."
      }
    }'
  ```

  ```bash cURL — financing round theme={null}
  curl -X POST https://launchboard.xyz/api/v1/corporate-actions \
    -H "Authorization: Bearer pg_live_your_key" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: financing-series-a-close-2024" \
    -d '{
      "type": "Financing Round",
      "title": "Series A preferred — $8M at $2.00/share",
      "effectiveDate": "2024-03-15",
      "status": "Approved",
      "metadata": {
        "boardApprovalDate": "2024-03-10"
      }
    }'
  ```
</CodeGroup>

**Response — `201 Created`**

```json theme={null}
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440070",
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "type": "Stock Split",
    "title": "2-for-1 forward split — Series A close",
    "status": "Draft",
    "effectiveDate": "2024-03-01",
    "createdAt": "2024-02-20T10:00:00.000Z",
    "updatedAt": "2024-02-20T10:00:00.000Z"
  }
}
```

The `Location` response header points to `GET /api/v1/corporate-actions/{id}`.

***

## Get a corporate action

Retrieves a single corporate action by ID.

**`GET /api/v1/corporate-actions/{id}`**

Requires role: **VIEWER**.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://launchboard.xyz/api/v1/corporate-actions/550e8400-e29b-41d4-a716-446655440070 \
    -H "Authorization: Bearer pg_live_your_key"
  ```
</CodeGroup>

***

## Update a corporate action

Updates any field of an existing corporate action. All fields are optional — only the fields you include are changed.

**`PATCH /api/v1/corporate-actions/{id}`**

Requires role: **EDITOR**. Idempotent with an `Idempotency-Key` header.

<ParamField body="type" type="string">
  Updated type.
</ParamField>

<ParamField body="title" type="string">
  Updated title. Maximum 200 characters.
</ParamField>

<ParamField body="summary" type="string">
  Updated summary. Maximum 2000 characters.
</ParamField>

<ParamField body="effectiveDate" type="string">
  Updated effective date (`YYYY-MM-DD`).
</ParamField>

<ParamField body="status" type="string">
  Updated status. One of `Draft`, `In Review`, `Approved`, `Finalized`.
</ParamField>

<ParamField body="metadata" type="object">
  Updated metadata. Replaces the existing metadata object.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH https://launchboard.xyz/api/v1/corporate-actions/550e8400-e29b-41d4-a716-446655440070 \
    -H "Authorization: Bearer pg_live_your_key" \
    -H "Content-Type: application/json" \
    -d '{
      "status": "Finalized",
      "metadata": {
        "boardApprovalDate": "2024-02-28",
        "notes": "All ledger mutations applied and reconciled."
      }
    }'
  ```
</CodeGroup>

**Response — `200 OK`**

Returns the full updated corporate action object.

***

## Delete a corporate action

Permanently deletes a corporate action. Use this to remove draft records created in error.

**`DELETE /api/v1/corporate-actions/{id}`**

Requires role: **EDITOR**.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://launchboard.xyz/api/v1/corporate-actions/550e8400-e29b-41d4-a716-446655440070 \
    -H "Authorization: Bearer pg_live_your_key"
  ```
</CodeGroup>

**Response — `204 No Content`**

***

## Error codes

| Status | When it occurs                                                                    |
| ------ | --------------------------------------------------------------------------------- |
| `401`  | Missing or invalid API key.                                                       |
| `403`  | Key role is below the required level (`EDITOR`).                                  |
| `404`  | Corporate action not found, or does not belong to your organization.              |
| `422`  | Request body failed validation. Check the `errors` field for field-level details. |