API reference

Equity awards

Option, RSA and RSU grants: recorded with their vesting, expensed straight line by every close, and forfeited when the holder leaves.

GET/v1/equity_awardsList equity awards
POST/v1/equity_awardsRecord an equity award
GET/v1/equity_awards/{award_id}Get an equity award month by month
PATCH/v1/equity_awards/{award_id}Change an equity award
DELETE/v1/equity_awards/{award_id}Delete an equity award no close has expensed
POST/v1/equity_awards/{award_id}/forfeitForfeit what has not vested

Guides: Record equity awards and expense them

List equity awards

GET/v1/equity_awards

client.equityAwards.list()

Equity awards, the newest first: who holds each, what it is worth, how much has vested and what the closes have expensed.

Parameters

Name	Type	Description
`status`Query	string or null	Only awards in this state. One of `active`, `forfeited`
`holder_party_id`Query	string or null	An id that starts with `party_`.
`limit`Query	integer	Page size, 1–200. Default 50
`cursor`Query	string or null	The `next_cursor` of the previous page.

Response

200EquityAwardPage

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl "https://api.ledgerit.ai/v1/equity_awards" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Record an equity award

POST/v1/equity_awards· Idempotent

client.equityAwards.create()

Record an option, RSA or RSU grant.

Nothing posts now. Every close from the grant date expenses it straight line over its vesting, split by its department; service before the grant is caught up at the first close after it. Refused with equity_award_terms for a holder, department or account not of these books, or a cliff longer than its vesting.

Request body

EquityAwardCreate

Response

201EquityAwardDetailOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X POST "https://api.ledgerit.ai/v1/equity_awards" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"department_value_id":"…","fair_value":0,"grant_date":"2026-09-30","holder_party_id":"…","shares":0,"type":"iso","vesting_starts_on":"2026-09-30"}'

Get an equity award month by month

GET/v1/equity_awards/{award_id}

client.equityAwards.get()

An equity award month by month: shares vested and expense to date, and every close that expensed it.

Parameters

Name	Type	Description
`award_id`Path · Required	string	An id that starts with `award_`.

Response

200EquityAwardDetailOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl "https://api.ledgerit.ai/v1/equity_awards/{award_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Change an equity award

PATCH/v1/equity_awards/{award_id}· Idempotent

client.equityAwards.update()

Change an award's memo, or its terms until a close expenses it. Refused with equity_award_in_use for a term once its expense is in the books: forfeit it and grant it again.

Parameters

Name	Type	Description
`award_id`Path · Required	string	An id that starts with `award_`.

Request body

EquityAwardChange

Response

200EquityAwardDetailOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X PATCH "https://api.ledgerit.ai/v1/equity_awards/{award_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Delete an equity award no close has expensed

DELETE/v1/equity_awards/{award_id}· Idempotent

client.equityAwards.delete()

Delete an award recorded in error, before any close has expensed it. Refused with equity_award_in_use after: forfeit it instead.

Parameters

Name	Type	Description
`award_id`Path · Required	string	An id that starts with `award_`.

Response

204No content

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X DELETE "https://api.ledgerit.ai/v1/equity_awards/{award_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Forfeit what has not vested

POST/v1/equity_awards/{award_id}/forfeit· Idempotent

client.equityAwards.forfeit()

The holder left: forfeit what had not vested by their last day.

The expense comes down to the fair value of the shares that vested, and the next close takes the rest back. Final. Refused with equity_award_not_forfeitable when it was already forfeited or the day is before the grant.

Parameters

Name	Type	Description
`award_id`Path · Required	string	An id that starts with `award_`.

Request body

ForfeitureIn

Response

200EquityAwardDetailOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X POST "https://api.ledgerit.ai/v1/equity_awards/{award_id}/forfeit" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"forfeited_on":"2026-09-30"}'

Objects

The objects these operations take and return.

EquityAwardPage

Name	Type	Description
`data`Required	array of EquityAwardOut
`has_more`Required	boolean
`next_cursor`Required	string or null

EquityAwardCreate

Name	Type	Description
`cliff_months`	integer	Months before anything vests; 0 for no cliff. Default 12
`department_value_id`Required	string	The department its expense belongs to: a value of `department`.
`expense_account_id`	string or null	An id that starts with `gla_`.
`fair_value`Required	number \| string	One share's fair value on the grant date: an option's Black-Scholes value, an RSU's price.
`grant_date`Required	string (date)	The day the board granted it.
`holder_party_id`Required	string	Who holds it: a counterparty of these books.
`memo`	string or null
`reserve_account_id`	string or null	An id that starts with `gla_`.
`shares`Required	integer	How many shares it grants.
`type`Required	string	`iso`, `nso`, `rsa` or `rsu`. One of `iso`, `nso`, `rsa`, `rsu`
`vesting_months`	integer	How many months it vests over. Default 48
`vesting_starts_on`Required	string (date)	The vesting start date.

EquityAwardDetailOut

Name	Type	Description
`created_at`Required	string (date-time)
`currency`Required	string
`department`Required	DepartmentRef	The department its expense is reported under.
`expense_account`Required	AccountRef	Where it is expensed, 6295 Stock-based compensation by default.
`expensed`Required	string	What the closes have expensed for it so far.
`fair_value`Required	string	One share's fair value on the grant date, in the books' currency.
`forfeited_on`Required	string (date) or null	The day it was forfeited.
`grant_date`Required	string (date)	The day the board granted it. Nothing is expensed before it.
`grant_value`Required	string	Shares times fair value: what it costs in all if it fully vests.
`holder`Required	HolderRef	Who holds it: a person among the books' counterparties.
`id`Required	string	An id that starts with `award_`.
`memo`Required	string or null
`months`Required	array of AwardMonthOut	Every month from the grant to the last vesting date (or the forfeiture), oldest first.
`reserve_account`Required	AccountRef	What it is expensed against, 3400 by default.
`runs`Required	array of AwardRunOut	Every close that expensed it, oldest first.
`shares`Required	integer	How many shares it grants.
`status`Required	string	`active`, or `forfeited` once the holder left before it all vested. One of `active`, `forfeited`
`type`Required	string	`iso` incentive stock option, `nso` non-qualified option, `rsa` restricted stock award, `rsu` restricted stock unit. One of `iso`, `nso`, `rsa`, `rsu`
`vested_shares`Required	integer	Shares vested today.
`vesting_schedule`Required	VestingSchedule
`vests_fully_on`Required	string (date)	The day its last shares vest.

EquityAwardChange

Only what is sent changes. Terms change only while none of its expense is in the books.

Name	Type	Description
`cliff_months`	integer or null
`department_value_id`	string or null	An id that starts with `dimv_`.
`expense_account_id`	string or null	An id that starts with `gla_`.
`fair_value`	number \| string or null
`grant_date`	string (date) or null
`holder_party_id`	string or null	An id that starts with `party_`.
`memo`	string or null
`reserve_account_id`	string or null	An id that starts with `gla_`.
`shares`	integer or null
`type`	string or null	One of `iso`, `nso`, `rsa`, `rsu`
`vesting_months`	integer or null
`vesting_starts_on`	string (date) or null

ForfeitureIn

Name	Type	Description
`forfeited_on`Required	string (date)	The holder's last day: what had not vested by then is forfeited.

EquityAwardOut

Name	Type	Description
`created_at`Required	string (date-time)
`currency`Required	string
`department`Required	DepartmentRef	The department its expense is reported under.
`expense_account`Required	AccountRef	Where it is expensed, 6295 Stock-based compensation by default.
`expensed`Required	string	What the closes have expensed for it so far.
`fair_value`Required	string	One share's fair value on the grant date, in the books' currency.
`forfeited_on`Required	string (date) or null	The day it was forfeited.
`grant_date`Required	string (date)	The day the board granted it. Nothing is expensed before it.
`grant_value`Required	string	Shares times fair value: what it costs in all if it fully vests.
`holder`Required	HolderRef	Who holds it: a person among the books' counterparties.
`id`Required	string	An id that starts with `award_`.
`memo`Required	string or null
`reserve_account`Required	AccountRef	What it is expensed against, 3400 by default.
`shares`Required	integer	How many shares it grants.
`status`Required	string	`active`, or `forfeited` once the holder left before it all vested. One of `active`, `forfeited`
`type`Required	string	`iso` incentive stock option, `nso` non-qualified option, `rsa` restricted stock award, `rsu` restricted stock unit. One of `iso`, `nso`, `rsa`, `rsu`
`vested_shares`Required	integer	Shares vested today.
`vesting_schedule`Required	VestingSchedule
`vests_fully_on`Required	string (date)	The day its last shares vest.

DepartmentRef

Name	Type	Description
`id`Required	string	An id that starts with `dimv_`.
`name`Required	string

AccountRef

Name	Type	Description
`code`Required	string
`id`Required	string	An id that starts with `gla_`.
`name`Required	string

HolderRef

Name	Type	Description
`id`Required	string	An id that starts with `party_`.
`name`Required	string

AwardMonthOut

Name	Type	Description
`ends_on`Required	string (date)	The month's last day.
`expense_to_date`Required	string	What it should have cost by the end of the month, in all.
`vested_shares`Required	integer	Shares vested by the end of the month.

AwardRunOut

Name	Type	Description
`amount`Required	string	What the run expensed for this award; below zero when it took expense back.
`entry_id`Required	string	The entry that posted it.
`period_ends_on`Required	string (date)	The month the run expensed.
`reversed`Required	boolean	Whether that entry was reversed; a reversed run counts for nothing.
`run_id`Required	string	An id that starts with `sbc_run_`.

VestingSchedule

Name	Type	Description
`cliff_months`Required	integer	Months before anything vests: 12 for a one-year cliff, 0 for none.
`months`Required	integer	How many months it vests over: 48 for four years.
`starts_on`Required	string (date)	The vesting start date, often the day the holder started work.