Shareholder Verification

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

Status	Body	When
`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.

Get started

Core concepts

Verifications

Reference

Shareholder Verification

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

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

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

Field rules

Errors

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

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

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

​Field rules

​Errors

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

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

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

Field rules

Errors