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

# Stakeholders API reference

> Create and manage equity holders — founders, employees, investors, and advisors — on your Launchboard cap table using the Stakeholders API.

Stakeholders are the equity holders on your cap table — founders, employees, investors, advisors, and institutional entities. Every security must be linked to a stakeholder, so creating stakeholders is typically the first step when building out your cap table programmatically. The API supports cursor-based pagination and free-text search across `displayName` and `email`.

## Endpoints

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

***

## List stakeholders

Returns a cursor-paginated list of all stakeholders belonging to your organization. Filter by `type`, `status`, or search by name and email with the `q` parameter.

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

  ```bash With filters theme={null}
  curl "https://launchboard.xyz/api/v1/stakeholders?type=INDIVIDUAL&status=CURRENT&limit=25" \
    -H "Authorization: Bearer pg_live_your_key"
  ```
</CodeGroup>

### Query parameters

<ParamField path="query.q" type="string">
  Free-text search against `displayName` and `email`. Case-insensitive partial match.
</ParamField>

<ParamField path="query.type" type="string">
  Filter by stakeholder type. One of `INDIVIDUAL` or `INSTITUTION`.
</ParamField>

<ParamField path="query.status" type="string">
  Filter by stakeholder status. One of `CURRENT` or `FORMER`.
</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 a previous response's `nextCursor` field. Omit to fetch from the beginning.
</ParamField>

### Response

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

  <Expandable title="Stakeholder fields">
    <ResponseField name="id" type="string">UUID of the stakeholder.</ResponseField>
    <ResponseField name="orgId" type="string">UUID of the owning organization.</ResponseField>
    <ResponseField name="displayName" type="string">Short display name shown in the Launchboard UI.</ResponseField>

    <ResponseField name="name" type="object">
      Legal name details.

      <Expandable title="name fields">
        <ResponseField name="legalName" type="string">Full legal name.</ResponseField>
        <ResponseField name="firstName" type="string">First name (individuals only).</ResponseField>
        <ResponseField name="lastName" type="string">Last name (individuals only).</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="type" type="string">`INDIVIDUAL` or `INSTITUTION`.</ResponseField>
    <ResponseField name="status" type="string">`CURRENT` or `FORMER`.</ResponseField>

    <ResponseField name="relationships" type="string[]">
      Array of relationship labels. Possible values: `ADVISOR`, `BOARD_MEMBER`, `CONSULTANT`, `EMPLOYEE`, `EX_ADVISOR`, `EX_CONSULTANT`, `EX_EMPLOYEE`, `EXECUTIVE`, `FOUNDER`, `INVESTOR`, `OTHER`.
    </ResponseField>

    <ResponseField name="email" type="string | null">Contact email address.</ResponseField>
    <ResponseField name="issuerAssignedId" type="string | null">Your internal identifier for this stakeholder.</ResponseField>
    <ResponseField name="comments" type="string | null">Free-text notes.</ResponseField>
    <ResponseField name="sourceDocumentId" type="string | null">UUID of the source document this stakeholder was extracted from.</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">
  Pass this value as `cursor` on the next request to retrieve the following page. `null` when you are on the last page.
</ResponseField>

***

## Create a stakeholder

Creates a new stakeholder. Supports the `Idempotency-Key` request header — if you retry with the same key, the API returns the previously created stakeholder instead of creating a duplicate.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://launchboard.xyz/api/v1/stakeholders \
    -H "Authorization: Bearer pg_live_your_key" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: create-stakeholder-alice-2024" \
    -d '{
      "displayName": "Alice Chen",
      "name": {
        "legalName": "Alice Chen",
        "firstName": "Alice",
        "lastName": "Chen"
      },
      "type": "INDIVIDUAL",
      "status": "CURRENT",
      "email": "alice@example.com",
      "relationships": ["FOUNDER", "EMPLOYEE"],
      "issuerAssignedId": "EMP-001"
    }'
  ```
</CodeGroup>

### Request body

<ParamField body="displayName" type="string" required>
  Short display name. Maximum 100 characters.
</ParamField>

<ParamField body="name" type="object" required>
  Legal name object.

  <Expandable title="name fields">
    <ParamField body="name.legalName" type="string" required>Full legal name.</ParamField>
    <ParamField body="name.firstName" type="string">First name (individuals).</ParamField>
    <ParamField body="name.lastName" type="string">Last name (individuals).</ParamField>
  </Expandable>
</ParamField>

<ParamField body="type" type="string" required>
  `INDIVIDUAL` or `INSTITUTION`.
</ParamField>

<ParamField body="status" type="string" default="CURRENT">
  `CURRENT` or `FORMER`.
</ParamField>

<ParamField body="email" type="string">
  Contact email address.
</ParamField>

<ParamField body="relationships" type="string[]" default="[]">
  Array of relationship labels. Valid values: `ADVISOR`, `BOARD_MEMBER`, `CONSULTANT`, `EMPLOYEE`, `EX_ADVISOR`, `EX_CONSULTANT`, `EX_EMPLOYEE`, `EXECUTIVE`, `FOUNDER`, `INVESTOR`, `OTHER`.
</ParamField>

<ParamField body="issuerAssignedId" type="string">
  Your internal identifier for this stakeholder. Maximum 100 characters.
</ParamField>

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

<ParamField body="sourceDocumentId" type="string">
  UUID of a source document to associate with this stakeholder.
</ParamField>

### Response

Returns `201 Created` with the full stakeholder object and a `Location` header pointing to the new resource.

***

## Get a stakeholder

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

Returns the stakeholder object. Field schema is identical to the list response items. Returns `404` if the stakeholder does not exist in your organization.

***

## Update a stakeholder

Partial update — only include the fields you want to change. All body fields are optional.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH https://launchboard.xyz/api/v1/stakeholders/abc123 \
    -H "Authorization: Bearer pg_live_your_key" \
    -H "Content-Type: application/json" \
    -d '{
      "status": "FORMER",
      "relationships": ["EX_EMPLOYEE"]
    }'
  ```
</CodeGroup>

### Request body

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

Returns `200 OK` with the updated stakeholder object.

***

## Delete a stakeholder

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://launchboard.xyz/api/v1/stakeholders/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 stakeholder with the given `id` exists in your organization.                                 |
| `422`  | Request body failed schema validation. The response includes a field-level `errors` array.      |

<Note>
  Use the `Idempotency-Key` header on all `POST` requests to safely handle network retries without creating duplicate stakeholders.
</Note>