CapableDocs

Search the API docs

Find an endpoint or guide

Get an API key

SecuritiesCreate a security

Securities

Create a security

Record a grant or issuance. It is a draft unless you mark it outstanding.
POST/api/v1/securities

Requires an API key with the securities:write scope · How keys work

Body

Send JSON with Content-Type: application/json.

  • typestringrequired

    Kind of security.

    One ofshareoptionrsarsusafenotewarrant

  • stakeholderIdstringrequired

    The holder. Create them first with POST /stakeholders.

  • quantitynumberrequired

    Shares or units, greater than 0. For a SAFE or note, the principal in US dollars.

  • issueDatedaterequired

    Issue or grant date, YYYY-MM-DD.

  • statusstringdefault: draft

    draft lands in Drafts for an admin to review and publish. outstanding records it on the cap table straight away.

    One ofdraftoutstanding

  • shareClassIdstring

    Share class. For plan awards it defaults to the plan's class.

  • equityPlanIdstring

    Equity plan for an option, RSA or RSU.

  • vestingScheduleIdstring

    Vesting schedule, from the schedules set up in the app.

  • vestingCommencementDatedate

    Vesting start date, YYYY-MM-DD. Defaults to the issue date when a vesting schedule is given.

  • exercisePricenumber

    Exercise price per share for an option or warrant, in US dollars.

  • pricePerSharenumber

    Purchase price per share for shares or an RSA, in US dollars.

  • optionTypestring

    Tax type of an option.

    One ofisonsoiso_nso

  • certificateIdstring

    Your own certificate id. Leave it out and the next id for the class or plan prefix is assigned, such as OPT-10.

  • valuationCapnumber

    SAFE or note valuation cap, in US dollars.

  • discountPercentnumber

    SAFE or note discount, as a percentage such as 20.

  • safeTypestring

    Kind of SAFE.

    One ofpost_moneypre_moneymfnuncapped

  • notesstring

    A note kept on the security.

Response 201

The new security's id, its certificate id and its status.

  • idstring

    The new security's id.

  • certificateIdstring

    The certificate id given or assigned.

  • statusstring

    The status it was created with.

    One ofdraftoutstanding

Example

Request
curl -X POST https://capable.so/api/v1/securities \
  -H "Authorization: Bearer $CAPABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "option",
    "stakeholderId": "stk_b2j6nq0ve8rc",
    "quantity": 40000,
    "issueDate": "2026-11-17",
    "equityPlanId": "pln_2024plan7b",
    "vestingScheduleId": "vst_4y1c_month",
    "exercisePrice": 0.42,
    "optionType": "iso"
  }'
Response · 201 Created
JSON
{
  "id": "sec_m3w8yk1t0hxa",
  "certificateId": "OPT-10",
  "status": "draft"
}

Good to know

  • An issue transaction is recorded with the security, so it appears in GET /transactions.
  • API writes take effect without the approval step the AI connector uses: an admin chose the key's scopes when creating it. Send drafts when a person should review a grant before it reaches the cap table.
  • The write is recorded in the company's activity log as created by the API, and a security.created webhook is sent.

Errors

StatusWhen
400 Bad requestThe body is not JSON.
401 UnauthorizedThe key is missing, invalid or revoked, or its creator lost access.
402 Payment requiredThe company has no active plan in good standing.
403 ForbiddenThe key does not have the securities:write scope.
429 Too many requestsThe key went over its rate limit. Wait for Retry-After seconds.
422 UnprocessableA field is missing or invalid, or stakeholderId is not a stakeholder of the company.

Every error has the same shape. See Errors, limits and conventions.