# Corporate actions and shareholder voting

> Discover authoritative issuer events, determine customer entitlement, submit elections and votes, and retain custodian-confirmation evidence.

The Corporate Governance API covers the full instruction lifecycle for corporate actions and shareholder
meetings. List endpoints are suitable for discovery; always retrieve a record by ID immediately before
displaying terms or accepting an instruction. The detail response is the authoritative MyStocks record and
includes the source version, options, deadlines, default treatment, and supporting documents.

## Corporate-action workflow

| Step | Endpoint | Purpose |
| --- | --- | --- |
| Discover | `GET /corporate-actions` | List events across symbols and exchanges; filter by `symbol`, `exchange`, `type`, or `status`. |
| Retrieve terms | `GET /corporate-actions/{actionId}` | Obtain the current authoritative terms, documents, election options, deadline, and default. |
| Check entitlement | `GET /users/{userId}/corporate-actions/{actionId}/entitlement` | Return the frozen record-date position and any existing instruction. |
| Track instruction | `GET /users/{userId}/corporate-actions/{actionId}/elections` | Read the latest revision and custodian status. |
| Submit or amend | `POST /users/{userId}/corporate-actions/{actionId}/elections` | Submit rights, tender, merger, or dividend instructions. Repeating the operation with a new key creates a new revision. |

Writes require an `Idempotency-Key`. Use a stable key for retries of the same request and a new key only
when the customer intentionally changes the instruction. An accepted or rejected response is not inferred
from HTTP success: a successful write initially returns `PENDING_CUSTODIAN`. Poll the election resource
until it becomes `ACCEPTED` or `REJECTED`, and retain `custodianReference`, `acceptedAt`, and
`confirmationDocumentUrl` when supplied.

```bash
curl -X POST "https://mystocks.africa/api/v1/partner/users/usr_123/corporate-actions/ca_123/elections" \
  -H "Authorization: Bearer pk_live_..." \
  -H "Idempotency-Key: election-ca-123-revision-1" \
  -H "Content-Type: application/json" \
  -d '{
    "optionId": "SUBSCRIBE",
    "units": 250,
    "acknowledgement": "Customer reviewed the issuer terms, deadline and default treatment."
  }'
```

## Shareholder-meeting workflow

| Step | Endpoint | Purpose |
| --- | --- | --- |
| Discover | `GET /shareholder-meetings` | List AGM, EGM, court, class, and other meetings. |
| Retrieve meeting | `GET /shareholder-meetings/{meetingId}` | Obtain resolutions, meeting dates, and proxy documents. |
| Check ballot | `GET /users/{userId}/shareholder-meetings/{meetingId}/ballot` | Return record-date voting units, ballot choices, and an existing vote. |
| Track vote | `GET /users/{userId}/shareholder-meetings/{meetingId}/votes` | Read the latest vote revision and custodian evidence. |
| Submit or amend | `POST /users/{userId}/shareholder-meetings/{meetingId}/votes` | Submit resolution-level choices or replace them before the deadline. |

```ts
const meetings = await client.corporateGovernance.listMeetings({ exchange: "NSE", status: "OPEN" });
const ballot = await client.corporateGovernance.getBallot("usr_123", meetings.meetings[0].id);

const result = await client.corporateGovernance.submitVote(
  "usr_123",
  ballot.meeting.id,
  {
    ballots: ballot.ballot.map((resolution) => ({ resolutionId: resolution.id, choice: "FOR" })),
    acknowledgement: "Customer reviewed the proxy materials and confirmed these choices.",
  },
  { idempotencyKey: `vote-${ballot.meeting.id}-revision-1` },
);
```

## Entitlement and cut-offs

Entitlement is based on the position snapshot captured for the issuer record date, not the customer's
current portfolio. A current holding does not prove entitlement, and a current zero balance does not remove
a previously captured entitlement. MyStocks publishes a customer deadline before the downstream custodian
or registrar cut-off so instructions can be validated and aggregated. If no valid instruction is accepted by
that deadline, the event's `defaultOptionId` or meeting `defaultTreatment` applies.

## Operational controls

- Display issuer documents and the latest detail response before collecting an instruction.
- Record the customer acknowledgement and your own case or journey reference in `note` where applicable.
- Never treat submission as downstream acceptance; use the returned instruction status.
- Preserve every revision, idempotency key, custodian reference, timestamp, and confirmation document.
- Stop accepting new instructions when the event or meeting is closed, cancelled, or past its deadline.
- Reconcile aggregate submitted units and voting units to the custodian or registrar confirmation.

The sandbox base URL exposes the same routes and idempotency rules. Sandbox records and confirmation
evidence are simulated and must never be used as proof of a live market instruction.

See [Webhooks](/partners/docs/webhooks), [Custody](/partners/docs/custody), and
[Complaints, reversals, corporate actions, and insolvency](/partners/docs/complaints-corporate-actions-insolvency).