Skip to Content
DevelopmentCreate Stakeholder

Create a Stakeholder

Stakeholders are the equity holders on your cap table: founders, employees, investors, or any entity that holds shares.

In the app

Open the company and choose Shareholders (/app/companies/<issuerId>?view=stakeholders). Your wallet calls createStakeholder. After the transaction confirms, the app saves the details with POST /stakeholder/register-onchain, using the same id it sent onchain.

The contract stores only the stakeholder’s id, type, and relationship. Names and contact details live in MongoDB.

With the API

POST /stakeholder/create creates the stakeholder onchain with the server key, then saves it in MongoDB under the same id. The server key needs OPERATOR or ADMIN on the cap table; see Server-signed routes.

The smallest valid request names the stakeholder and sets its type and relationship:

curl -s -X POST "$API/stakeholder/create" \ -H "Content-Type: application/json" \ -d @- <<JSON { "issuerId": "$ISSUER_ID", "data": { "name": { "legal_name": "Jordan Lee" }, "stakeholder_type": "INDIVIDUAL", "current_relationship": "FOUNDER" } } JSON
Full request with contact details
curl -s -X POST "$API/stakeholder/create" \ -H "Content-Type: application/json" \ -d @- <<JSON { "issuerId": "$ISSUER_ID", "data": { "name": { "legal_name": "Jordan Lee", "first_name": "Jordan", "last_name": "Lee" }, "issuer_assigned_id": "EMP-0001", "stakeholder_type": "INDIVIDUAL", "current_relationship": "FOUNDER", "primary_contact": { "name": { "legal_name": "Jordan Lee" }, "emails": [{ "email_type": "PERSONAL", "email_address": "jordan@example.com" }], "phone_numbers": [{ "phone_type": "MOBILE", "phone_number": "+1 555 555 0100" }] }, "contact_info": { "emails": [{ "email_type": "BUSINESS", "email_address": "jordan@example.org" }] }, "comments": [] } } JSON

The response is the saved stakeholder, with _id, the fields you sent, issuer, is_onchain_synced: false, tx_hash: null, and timestamps. On this route, is_onchain_synced turns true when the poller processes the StakeholderCreated event.

export STAKEHOLDER_ID="<your stakeholder _id>"

Fields

FieldRequiredNotes
issuerIdYesThe issuer _id from Create an Issuer.
data.name.legal_nameYesFull legal name. first_name and last_name are optional.
data.stakeholder_typeYesINDIVIDUAL (a person) or INSTITUTION (a company or fund).
data.current_relationshipYes, for TAPSent onchain with the stakeholder. OCF marks it optional.
data.issuer_assigned_idNoYour own id for the person, such as an employee number.
data.primary_contact, data.contact_infoNoPhone numbers use OCF’s format: +1 555 555 0100, with spaces and no dashes.

Relationship values

current_relationship takes one of these OCF values: ADVISOR, BOARD_MEMBER, CONSULTANT, EMPLOYEE, EX_ADVISOR, EX_CONSULTANT, EX_EMPLOYEE, EXECUTIVE, FOUNDER, INVESTOR, NON_US_EMPLOYEE, OFFICER, or OTHER.

What’s next?

Last updated on