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"
}
}
JSONFull 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": []
}
}
JSONThe 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
| Field | Required | Notes |
|---|---|---|
issuerId | Yes | The issuer _id from Create an Issuer. |
data.name.legal_name | Yes | Full legal name. first_name and last_name are optional. |
data.stakeholder_type | Yes | INDIVIDUAL (a person) or INSTITUTION (a company or fund). |
data.current_relationship | Yes, for TAP | Sent onchain with the stakeholder. OCF marks it optional. |
data.issuer_assigned_id | No | Your own id for the person, such as an employee number. |
data.primary_contact, data.contact_info | No | Phone 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.