Corporate actions and shareholder voting

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

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.

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

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, Custody, and Complaints, reversals, corporate actions, and insolvency.