API product catalogCorporate Actions & Shareholder Governance

Submit or amend a corporate-action election

Corporate Actions & Shareholder Governance

POST

/users/{userId}/corporate-actions/{actionId}/elections

Sandbox availablesubmitCorporateActionElection

Reusing the same sub-account and action amends the instruction while voting remains open. Every accepted revision returns to PENDING_CUSTODIAN.

Parameters

userIdstringpathRequired

actionIdstringpathRequired

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Idempotency-KeystringheaderRequired

Unique string that makes write calls safe to retry on network failure. Required for money movement, trading, KYC, subscriptions, and webhook creation. Deduplicated for 24 hours -- duplicate keys return the cached response. HTTP 409 if a concurrent request with the same key is still in progress.

Example: dep_user42_1743152580

Request body

optionIdstringRequired

unitsnumber

notestring

acknowledgementstringRequired

Response fields

messagestring

electionobject

election.statusPENDING_CUSTODIAN | ACCEPTED | REJECTED

election.revisioninteger

election.submittedAtstring | null

election.amendedAtstring | null

election.custodianReferencestring | null

election.custodianReasonstring | null

election.acceptedAtstring | null

election.confirmationDocumentUrlstring | null

Response codes

200Election revision queued for custodian acceptance

Request reference

Sandbox available

userId Required · pathactionId Required · path

Use the API Tester for write requests, including request bodies and idempotency keys.

https://mystocks.africa/api/sandbox/v1/partner/users/%7BuserId%7D/corporate-actions/%7BactionId%7D/elections

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string"
    },
    "election": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "PENDING_CUSTODIAN",
            "ACCEPTED",
            "REJECTED"
          ]
        },
        "revision": {
          "type": "integer",
          "minimum": 1
        },
        "submittedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "amendedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "custodianReference": {
          "type": [
            "string",
            "null"
          ]
        },
        "custodianReason": {
          "type": [
            "string",
            "null"
          ]
        },
        "acceptedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "confirmationDocumentUrl": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri"
        }
      }
    }
  }
}

curl -X POST 'https://mystocks.africa/api/sandbox/v1/partner/users/%7BuserId%7D/corporate-actions/%7BactionId%7D/elections' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "optionId": "SUBSCRIBE",
  "units": 10,
  "acknowledgement": "Customer reviewed and confirmed the issuer terms."
}'

GET /users/{userId}/corporate-actions/{actionId}/elections

GET /users/{userId}/corporate-actions/{actionId}/entitlement