Vesting terms and milestones API reference

Launchboard models vesting in two complementary resources. Vesting terms define a reusable vesting schedule — the allocation method, vesting conditions, cliff, and total duration — that you attach to a security at grant time via vestingTermsId. Vesting milestones track discrete events tied to an individual security (for example, “product launch” or “Series A close”) that trigger a percentage of the grant to vest when you mark them complete. The two resources can be used independently or together depending on the grant structure.

Vesting terms endpoints

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

Vesting milestones endpoints

Method	Path	Description
`GET`	`/api/v1/vesting-milestones`	List vesting milestones (cursor-paginated)
`POST`	`/api/v1/vesting-milestones`	Create a vesting milestone
`GET`	`/api/v1/vesting-milestones/{id}`	Get a single vesting milestone
`PATCH`	`/api/v1/vesting-milestones/{id}`	Partially update a vesting milestone
`DELETE`	`/api/v1/vesting-milestones/{id}`	Delete a vesting milestone
`POST`	`/api/v1/vesting-milestones/{id}/complete`	Mark a milestone as completed

List vesting terms

Returns a cursor-paginated list of all vesting term records for your organization.

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

Query parameters

number

default:"25"

Maximum results per page. Capped at 100.

string

Opaque cursor from the previous response’s nextCursor field.

Response

object[]

Array of vesting terms objects.

Show Vesting terms fields

string

UUID of the vesting terms record.

string

UUID of the owning organization.

string

Human-readable name (e.g., "4-year / 1-year cliff").

string | null

Longer description of the vesting schedule.

string

How share quantities are rounded across periods. One of CUMULATIVE_ROUNDING, CUMULATIVE_ROUND_DOWN, FRONT_LOADED, BACK_LOADED, FRONT_LOADED_TO_SINGLE_TRANCHE, BACK_LOADED_TO_SINGLE_TRANCHE, or FRACTIONAL.

string

Unit of time for each vesting period (e.g., "MONTHS").

number

Length of each period in the above units.

number

Total number of vesting periods.

number

Number of periods before the first vesting event.

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.

Create vesting terms

Creates a reusable vesting schedule. Once saved, reference the record by its id in vestingTermsId when issuing securities.

curl -X POST https://launchboard.xyz/api/v1/vesting-terms \
  -H "Authorization: Bearer pg_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-4yr1yr-cliff" \
  -d '{
    "name": "4-year / 1-year cliff",
    "description": "Standard employee vesting: 25% after 12 months, then monthly over 36 months.",
    "allocationMethod": "CUMULATIVE_ROUNDING",
    "triggerType": "TIME_BASED",
    "totalVestingMonths": 48,
    "cliffMonths": 12,
    "vestingConditions": [
      {
        "id": "cond-cliff",
        "trigger": {
          "type": "TIME_BASED",
          "periodLength": 12,
          "periodType": "MONTHS"
        },
        "portion": { "numerator": 1, "denominator": 4 }
      },
      {
        "id": "cond-monthly",
        "trigger": {
          "type": "TIME_BASED",
          "periodLength": 1,
          "periodType": "MONTHS"
        },
        "portion": { "numerator": 1, "denominator": 36 },
        "cliffConditionId": "cond-cliff"
      }
    ],
    "schedule": {
      "totalMonths": 48,
      "cliffMonths": 12,
      "cliffPercent": 25,
      "vestingFrequency": "MONTHLY"
    }
  }'

Request body

string

required

Human-readable name. Maximum 100 characters.

string

required

Description of the vesting schedule. Used in the Launchboard UI and grant notices.

string

default:"CUMULATIVE_ROUNDING"

Rounding strategy for share quantities across vesting periods. One of: CUMULATIVE_ROUNDING, CUMULATIVE_ROUND_DOWN, FRONT_LOADED, BACK_LOADED, FRONT_LOADED_TO_SINGLE_TRANCHE, BACK_LOADED_TO_SINGLE_TRANCHE, FRACTIONAL.

string

default:"TIME_BASED"

Whether vesting is driven by time, events, or a combination: TIME_BASED, EVENT_BASED, or HYBRID.

object[]

required

Array of vesting condition objects. At least one is required.

Show Vesting condition fields

string

required

A UUID you assign to identify this condition (used to link cliff and continuation conditions).

object

required

Trigger definition.

Show trigger fields

string

required

TIME_BASED or EVENT_BASED.

number

Length of the time period (used when type is TIME_BASED).

string

Time unit: DAYS, MONTHS, or YEARS.

string

Description of the event (used when type is EVENT_BASED).

object

required

Fractional share of the grant that vests on this condition.

Show portion fields

number

required

Non-negative integer numerator.

number

required

Positive integer denominator.

string

UUID of the cliff condition that must be satisfied before this condition begins.

string

UUID of the condition that repeats after this one (for recurring monthly/quarterly conditions).

object

Simplified schedule summary for display purposes.

Show schedule fields

number

required

Total vesting duration in months.

number

required

Cliff duration in months.

number

required

Percentage that vests at the cliff (0–100).

string

required

Post-cliff frequency: MONTHLY, QUARTERLY, or ANNUALLY.

object[]

Optional acceleration events.

number

Total vesting duration in months. Convenience field that mirrors schedule.totalMonths.

number

Cliff duration in months. Convenience field that mirrors schedule.cliffMonths.

string

Free-text notes.

Response

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

Get vesting terms

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

Returns the vesting terms object.

Update vesting terms

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

curl -X PATCH https://launchboard.xyz/api/v1/vesting-terms/abc123 \
  -H "Authorization: Bearer pg_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "4-year / 1-year cliff (revised)",
    "comments": "Updated allocation method to FRACTIONAL per legal review."
  }'

All fields from the create body are accepted; all are optional for PATCH. Returns 200 OK with the updated object.

Delete vesting terms

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

Returns 204 No Content on success.

List vesting milestones

Returns a cursor-paginated list of all vesting milestones for your organization.

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

Query parameters

number

default:"25"

Maximum results per page. Capped at 100.

string

Opaque cursor from the previous response’s nextCursor field.

Response

object[]

Array of vesting milestone objects.

Show Vesting milestone fields

string

UUID of the milestone.

string

UUID of the owning organization.

string

UUID of the security this milestone is attached to.

string

Description of the milestone event.

string

Expected completion date, in YYYY-MM-DD format.

string | null

Timestamp when the milestone was completed. null while still pending.

string

Number of shares that vest on completion, as a decimal string.

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.

Create a vesting milestone

Creates a new milestone for a security. The milestone starts in PENDING status.

curl -X POST https://launchboard.xyz/api/v1/vesting-milestones \
  -H "Authorization: Bearer pg_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Series A close",
    "description": "25% of grant vests upon closing a Series A financing of at least $5M.",
    "targetDate": "2024-12-31"
  }'

Request body

string

required

Short name for the milestone. Maximum 100 characters.

string

Detailed description of the milestone condition. Maximum 500 characters.

string

Expected completion date in YYYY-MM-DD format.

Response

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

Get a vesting milestone

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

Returns the milestone object.

Update a vesting milestone

Partial update for pending milestones. Use this to adjust the target date or description before the milestone is completed.

curl -X PATCH https://launchboard.xyz/api/v1/vesting-milestones/abc123 \
  -H "Authorization: Bearer pg_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "targetDate": "2025-03-31",
    "description": "25% vests on Series A close (updated deadline)."
  }'

All fields from the create body are accepted; all are optional for PATCH. Returns 200 OK with the updated milestone object.

Delete a vesting milestone

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

Returns 204 No Content on success.

Mark a milestone as completed

Transitions a PENDING milestone to COMPLETED and records a completedAt timestamp. Optionally attach an evidence note describing how the milestone was satisfied.

curl -X POST https://launchboard.xyz/api/v1/vesting-milestones/abc123/complete \
  -H "Authorization: Bearer pg_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "evidenceNote": "Series A closed on 2024-11-15. Wire confirmation #TXN-88420."
  }'

Request body

string

Optional note documenting how the milestone was satisfied. Maximum 1000 characters.

Response

Returns 200 OK with the updated milestone object. The completedAt field will be populated with the current timestamp and status will be COMPLETED.

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 all write operations.
`404`	No record with the given `id` exists in your organization.
`409`	Attempting to complete a milestone that is already `COMPLETED`.
`422`	Request body failed schema validation. The response includes a field-level `errors` array.

Completing a milestone is an irreversible action. If you need to correct a milestone that was completed in error, contact support or delete the milestone and recreate it.

Overview

Cap Table

Transactions

Data & Export

Webhooks

Vesting terms and milestones API reference

Vesting terms endpoints

Vesting milestones endpoints

List vesting terms

Query parameters

Response

Create vesting terms

Request body

Response

Get vesting terms

Update vesting terms

Delete vesting terms

List vesting milestones

Query parameters

Response

Create a vesting milestone

Request body

Response

Get a vesting milestone

Update a vesting milestone

Delete a vesting milestone

Mark a milestone as completed

Request body

Response

Common errors

​Vesting terms endpoints

​Vesting milestones endpoints

​List vesting terms

​Query parameters

​Response

​Create vesting terms

​Request body

​Response

​Get vesting terms

​Update vesting terms

​Delete vesting terms

​List vesting milestones

​Query parameters

​Response

​Create a vesting milestone

​Request body

​Response

​Get a vesting milestone

​Update a vesting milestone

​Delete a vesting milestone

​Mark a milestone as completed

​Request body

​Response

​Common errors

Vesting terms endpoints

Vesting milestones endpoints

List vesting terms

Query parameters

Response

Create vesting terms

Request body

Response

Get vesting terms

Update vesting terms

Delete vesting terms

List vesting milestones

Query parameters

Response

Create a vesting milestone

Request body

Response

Get a vesting milestone

Update a vesting milestone

Delete a vesting milestone

Mark a milestone as completed

Request body

Response

Common errors