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

query.limit

number

default:"25"

Maximum results per page. Capped at 100.

query.cursor

string

Opaque cursor from the previous response’s nextCursor field.

Response

items

object[]

Array of vesting terms objects.

Show Vesting terms fields

string

UUID of the vesting terms record.

orgId

string

UUID of the owning organization.

name

string

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

description

string | null

Longer description of the vesting schedule.

allocationType

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.

periodLengthUnits

string

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

periodLength

number

Length of each period in the above units.

totalPeriods

number

Total number of vesting periods.

cliffPeriods

number

Number of periods before the first vesting event.

createdAt

string

ISO-8601 timestamp with timezone offset.

updatedAt

string

ISO-8601 timestamp with timezone offset.

nextCursor

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

name

string

required

Human-readable name. Maximum 100 characters.

description

string

required

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

allocationMethod

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.

triggerType

string

default:"TIME_BASED"

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

vestingConditions

object[]

required

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

Show Vesting condition fields

vestingConditions[].id

string

required

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

vestingConditions[].trigger

object

required

Trigger definition.

Show trigger fields

trigger.type

string

required

TIME_BASED or EVENT_BASED.

trigger.periodLength

number

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

trigger.periodType

string

Time unit: DAYS, MONTHS, or YEARS.

trigger.eventDescription

string

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

vestingConditions[].portion

object

required

Fractional share of the grant that vests on this condition.

Show portion fields

portion.numerator

number

required

Non-negative integer numerator.

portion.denominator

number

required

Positive integer denominator.

vestingConditions[].cliffConditionId

string

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

vestingConditions[].nextConditionId

string

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

schedule

object

Simplified schedule summary for display purposes.

Show schedule fields

schedule.totalMonths

number

required

Total vesting duration in months.

schedule.cliffMonths

number

required

Cliff duration in months.

schedule.cliffPercent

number

required

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

schedule.vestingFrequency

string

required

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

schedule.accelerationTriggers

object[]

Optional acceleration events.

totalVestingMonths

number

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

cliffMonths

number

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

comments

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

query.limit

number

default:"25"

Maximum results per page. Capped at 100.

query.cursor

string

Opaque cursor from the previous response’s nextCursor field.

Response

items

object[]

Array of vesting milestone objects.

Show Vesting milestone fields

string

UUID of the milestone.

orgId

string

UUID of the owning organization.

securityId

string

UUID of the security this milestone is attached to.

description

string

Description of the milestone event.

targetDate

string

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

completedAt

string | null

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

quantity

string

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

createdAt

string

ISO-8601 timestamp with timezone offset.

updatedAt

string

ISO-8601 timestamp with timezone offset.

nextCursor

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

name

string

required

Short name for the milestone. Maximum 100 characters.

description

string

Detailed description of the milestone condition. Maximum 500 characters.

targetDate

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

evidenceNote

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

Overview

Cap Table

Transactions

Data & Export

Webhooks

Documentation Index

​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