Skip to main content
Shareholder management records who is behind a company. Each shareholder is added with their personal details and, optionally, a government-issued ID document that is verified and stored. Adding the first shareholder sets the company’s shareHolderVerified flag. This flow is handled by company management, not the verification endpoints. The path parameter is companyId.

​
Add a shareholder — POST /v1/company/{companyId}/shareholder

name and email are required. To attach an ID document, include the file in the identificationDocument field along with name, identificationNumber, and idType (all three are required when a document is present). The request is multipart/form-data.
With an ID document
curl -X POST https://api.vouchmark.com/v1/company/cmp_aBcD.../shareholder \
  -H "Authorization: Bearer $TOKEN" \
  -F "name=Jane Doe" \
  -F "email=jane@example.com" \
  -F "address=14 Marina Road" \
  -F "dateOfBirth=1984-02-12" \
  -F "nationality=Nigerian" \
  -F "idType=NIN" \
  -F "identificationNumber=12345678901" \
  -F "roleInCompany=Director" \
  -F "percentageOfOwner=40" \
  -F "noOfShares=4000" \
  -F "identificationDocument=@./jane-nin.pdf"
Response
{
  "success": true,
  "message": "Shareholder added successfully",
  "shareholder": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "address": "14 Marina Road",
    "dateOfBirth": "1984-02-12T00:00:00.000Z",
    "nationality": "Nigerian",
    "idType": "NIN",
    "roleInCompany": "Director",
    "percentageOfOwner": 40,
    "noOfShares": 4000,
    "identificationNumber": "12345678901",
    "phoneNumber": null,
    "identificationDocumentUrl": "https://..."
  }
}

​
Update a shareholder — PUT /v1/company/{companyId}/shareholder/{shareholderId}

Send the fields to change. A replacement ID document can be supplied in the identificationDocument field. The request is multipart/form-data. 
curl -X PUT https://api.vouchmark.com/v1/company/cmp_aBcD.../shareholder/sh_eFgH... \
  -H "Authorization: Bearer $TOKEN" \
  -F "percentageOfOwner=45" \
  -F "noOfShares=4500"

​
Remove a shareholder — DELETE /v1/company/{companyId}/shareholder

Identify the shareholder with either shareholderId or email in the request body. Removing the last shareholder clears the company’s shareholder-verified flag. 
curl -X DELETE https://api.vouchmark.com/v1/company/cmp_aBcD.../shareholder \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com"}'
Response
{
  "success": true,
  "message": "Shareholder removed successfully",
  "data": null
}

​
Field rules

  • name and email are always required; a duplicate email on the same company is rejected.
  • When an ID document is attached, name, identificationNumber, and idType must all be present.
  • A person recorded as a director must hold a non-zero number of shares, otherwise the entry is rejected.

​
Errors

StatusBodyWhen
400{ "success": false, "error": "Missing required fields", "message": "Name and email are required", ... }name or email omitted.
400{ "success": false, "error": "Duplicate email", "message": "A shareholder with email ... already exists", ... }The email is already on the company.
400{ "message": "Either shareholderId or email must be provided" }Remove called with no identifier.
404{ "success": false, "error": "Company not found", ... } / { "message": "Company not found" }The company is missing or not yours.
404{ "message": "Shareholder not found with email: ..." }No matching shareholder to remove.