> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vouchmark.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Shareholder Verification

> Add, update, and remove a company's shareholders, with optional ID document checks.

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`.

```bash With an ID document theme={null}
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"
```

```json Response theme={null}
{
  "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`.

```bash theme={null}
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.

```bash theme={null}
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"}'
```

```json Response theme={null}
{
  "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.   |