Documentation
Your guide to Mandate Vote
Step-by-step help for running elections and events, managing nominations and payments, and keeping your account secure.
Getting started
Create your organization
Sign up with your work email. The organization you name becomes the workspace every election, member and result belongs to.
Verify your phone
Under Your profile, confirm the number you can be reached on. It is how you recover the account if you lose your password, and it is what lets you test the SMS channel before an election day depends on it.
Add your members
One at a time, or a spreadsheet of thousands. See Your member roll.
Build and open an election
Draft it, check the ballot, then open it. Nothing is sent to anyone while an election is a draft.
Vote and Events
Mandate Vote is two things over one set of members. The switcher at the top of the sidebar moves between them.
| Product | For |
|---|---|
| Mandate Vote | Elections and decisions: ballots, positions, candidates, secrecy, tallies, certification. |
| Mandate Events | Conferences, AGMs and anything people turn up to: tickets, registration, and checking them in at the door. |
They share an organization, a member roll, an audit trail and one account. That sharing is the point rather than a convenience: an AGM is a single day on which members register, are checked in, and then vote, and making them exist twice would defeat it.
Attendance and ballots stay apart
Checking in at a door is a fact about a person. A ballot is not attached to one. The two systems share who is entitled to what, and nothing else — being marked present says nothing about how anybody voted.
Your member roll
The Members page is a searchable data table. Choose 25, 50, 100 or 200 rows per page. Select individual checkboxes or select the current page; selections remain as you move between pages, up to 500 members per batch. A new search clears the selection. Delete selected opens a confirmation. Deletion is permanent and the batch is atomic: if any selected member belongs to an election, nobody is deleted. Remove unused members from draft electorates first; started election records remain protected.
The roll is everybody who belongs to your organization. It is not the same thing as the people voting in a particular election — that is chosen per election.
A member needs a name and one way to be reached: a phone number, an email address, or both. Someone with only a phone number can vote over USSD on a supported mobile network. WhatsApp voting requires internet access and a verified number on the member account.
| Field | What it is for |
|---|---|
| Name | What the ballot greets them by, and what an officer checks against a list. |
| Phone | SMS invitations, USSD voting, WhatsApp voting, and password recovery. Any format — 024…, +233…, 00233… all normalise to the same number. |
| Emailed invitations and ballot links. | |
| Member ID | Student or staff number. Optional, but it is what voters are asked for at the ballot, so a roll with them is easier to vote on. |
Adding somebody who is already on the roll
If the email, phone or member ID already belongs to another member, the add is refused and names them. This is deliberate: an add that quietly rewrote an existing person would lose whoever was there. Edit that member instead.
A CSV import maps your columns to these fields, and a dry run tells you exactly what would happen — how many new, how many updated, which rows are unusable — before anything is written.
Building an election
An election is the event: “KNUST SRC General Election 2026”. It has a title, an optional banner, a schedule and a ballot.
| Setting | What it decides |
|---|---|
| Opens / closes | When the ballot accepts votes. Leave closing blank to end it by hand. |
| Audience | Members-only draws an electorate from your roll and makes each voter prove who they are. Open is a public straw poll anybody with the link can answer. |
| Secret ballot | On by default. The roll records that somebody voted, never what they chose. |
Draft first
A draft sends nothing and accepts no votes. Invitations only become available once the election is open, because telling somebody to vote in an election that has not started would not be true yet.
An election moves between three states, and mistakes are undoable until somebody votes. Opened the wrong one? Put it back to draft. Closed too early? Reopen it. Both are offered while the ballot count is zero, and both disappear the moment a single vote is cast — from then on rewinding would discard or silently recontest somebody’s ballot.
| State | What you can do |
|---|---|
| Draft | Edit anything, add and remove candidates, delete the election. Nothing is sent and nothing is billed. |
| Open | Voting runs on every channel. The ballot locks so cast votes cannot be orphaned, but you can still change who may vote, and close at any time. |
| Closed | Results are final. You can declare them, reopen or return to draft if nobody voted, and delete the election if you need to. |
An election can be deleted at any point except while voting is open — deleting mid-vote would discard ballots cast minutes earlier by people holding receipts. Deleting a finished election destroys its results too, so you are asked to confirm the exact ballot count first.
Positions and candidates
Most real elections decide several things at once. A student election picks a President, a General Secretary and a PRO in the same sitting — one ballot, one verification, one turnout figure. Each of those is a position, and each position has its own candidates.
A new election starts as a single unnamed race, which is all a straightforward yes/no vote needs. Press Split into positions to name races and add more.
| Per position | Meaning |
|---|---|
| Choices per voter | How many candidates one voter may pick in this race. |
| Seats | How many are elected. A committee may let you choose three of eight and elect all three. |
| To win outright | The share a candidate must exceed. Leave blank for most-votes-wins. Set 50 for the rule where falling short sends the top two to a run-off. |
| Running mate | A presidential ticket is one choice and two names. Both appear on the ballot; the tally counts the pair. |
Give each candidate a one-line pitch as well as a manifesto. The pitch is the only thing a voter on a basic phone sees, because a USSD screen holds about 160 characters including its own menu.
Once an election leaves draft
Candidates and positions can no longer be added or removed — ballots already cast refer to them, and a removal would orphan real votes. Editing is locked while voting is open. Close voting before correcting details; all changes are recorded in the audit trail.
Who votes
Choose who votes opens a wide, paginated member table. Search the complete organization roll, select members across pages and choose Add selected. Existing election members and suspended members cannot be selected for addition. Adding people does not send messages; use Send invitations separately.
You can still add voters after voting starts
Who may vote is not the ballot. Adding somebody cannot change what an already-cast vote meant, so a member who turns up on polling day with a valid card can be put on the roll and vote there and then. What locks when voting opens is the ballot itself — candidates and positions — because votes already cast refer to them. The electorate becomes final when the election closes, since after that it would change the turnout the result was read against. Anybody who has already voted can never be removed.
The roll belongs to the organization. The electorate belongs to one election. Being on one does not put you in the other.
On an election’s page, under Voters:
| Action | What it does |
|---|---|
| Add everyone | Draws the whole roll into this election. Safe to re-run after importing more people. |
| Choose who votes | Search the roll and add or remove individuals. This is how a by-election for one hall, or a vote only the executive takes part in, leaves the rest of the roll alone. |
You can also do it as you go: the Add member dialog and the CSV import both offer Let them vote in, which puts the people you are adding straight into the elections you pick.
Somebody who has already voted cannot be removed
Their ballot is in the box and carries no voter, so it cannot be found and taken out again. Removing them would leave more ballots than voters, with nothing able to explain the difference.
Invitations and voting codes
Delivery status on the election page separates queued invitations, provider-accepted messages and failures. Provider acceptance does not guarantee inbox delivery; spam filtering and bounces must be checked with the email provider. For a pending message without a durable job, an organizer must explicitly choose “Resend to members already invited on these channels” and then “Resend and replace voting codes.” Resending replaces the voting code, so voters should use the newest invitation.
Once an election is open, invite its electorate over email, SMS or WhatsApp. Each person gets a link to the ballot and two credentials:
| Credential | What it is |
|---|---|
| Voter ID | Their member ID, or their phone or email if you keep no member numbers. |
| Voting code | Eight letters, printed in two groups like VKQD MHRT. Case and spacing do not matter when they type it back. |
The code is stored hashed: nobody, including you, can read it back out of the system afterwards. Re-sending an invitation issues a new code and retires the old one.
Five wrong tries and that code stops working
The cap is per voter, so somebody working through a published list of membership numbers cannot simply keep guessing. If a voter locks themselves out, re-send their invitation to issue a fresh code.
How people vote
Every channel runs on the same election engine, the same ballot and the same tally. A vote by USSD is not a lesser vote counted separately; it is the same vote arriving a different way.
| Channel | What the voter needs |
|---|---|
| Web | The link from the invitation. They sign in with their voter ID and code, or ask for a one-time code instead. |
| USSD | Any handset. They dial the short code — no internet, no app, no data bundle. |
| A message from the verified phone number on their active membership, plus eligibility for the selected election. WhatsApp requires internet access. | |
| Assisted | A supervised station, for anyone the first three miss. Same ballot, run by an officer. |
On the web ballot a voter chooses in each race, then sees a review step listing their choices by name and saying plainly which positions they are abstaining from, before anything becomes final.
On-site voting
A polling station is a desk where people vote in person, run the way a national election runs it. An officer finds the voter on the register, checks their card, and hands over the device. The voter chooses alone.
Those are two different jobs, and Mandate Vote keeps them apart on purpose. The moment a voter is checked in, the screen clears to a hand the device over page that only the voter dismisses — so a ballot is never on screen while the officer is still holding the tablet. When the ballot is cast the screen shows a receipt reference and nothing else, then returns itself to the register. An officer never sees a choice, going in or coming out.
Create the station
Under the election, add a station and name it after what is painted on the wall — Great Hall, Table 3. The name goes on the sheet you reconcile at close.
Assign your officers
An officer is an ordinary member given one job at one desk. They can work their own station and read its own counts. They cannot see another station’s register, cannot read the tally, and cannot change the ballot.
Open the station
A station cannot open before its election does, and once closed it cannot reopen — the same reason a paper station seals its box. Nobody can be checked in outside those hours.
Reconcile at close
The desk shows checked in against voted. A gap is people who were handed a ballot and walked away without finishing, which is a normal thing that happens and a number worth being able to state.
Assigning voters to a particular station is optional. A station with nobody assigned serves the whole roll, which is what a one-table church or union election actually is.
Somebody who has already voted cannot be checked in again, on any channel. A member who voted by WhatsApp in the morning is turned away at the desk in the afternoon, by the same rule that stops a second ballot anywhere else.
Vote receipts
After voting, every voter is given a short reference such as DC6B8494E6. They can check it later at /receipt, or from the link in the confirmation screen.
The check answers one question: was this ballot recorded, in which election, and on what day. It cannot answer how they voted — the selections live in a different table with nothing joining the two. That is the difference between a receipt and a tool for buying votes, because the first thing a vote buyer asks for is the receipt.
Results and certification
Where billing and election permissions allow access, results update as ballots arrive, per position, with each candidate’s share. Where a position has a winning threshold, the result says outright whether it was met or whether the race goes to a run-off.
A certificate is the formal statement of the outcome. It refuses to certify while voting is still open, and lists any other blockers rather than producing a document that looks final and is not.
The Audit trail records every administrative act — who opened the election, who changed the electorate, who sent invitations, when. It never records a ballot choice; there is no field for one.
Declaring a result
Every figure in Mandate Vote is recounted from the ballots each time you open the page. That is the right way to produce a result and the wrong way to preserve one: if a tally were ever changed, the recount would simply report the new number.
Declaring fixes that. It signs the figures as they stand and stores them where they are never recomputed. From then on the page answers a question it could not answer before: do the ballots still produce what was declared?
| What you see | What it means |
|---|---|
| Result declared and signed | The ballots today reproduce exactly the figures that were signed, and the signature checks out. |
| The ballots no longer match | The declared result and the current one have diverged. Mandate Vote cannot say why — a restored backup and an edited tally look identical — but somebody needs to account for the difference. |
| Could not be rechecked | The recount did not run, usually because results are behind an unpaid invoice. Not a sign of tampering. |
A result can be declared once. Re-signing changed figures is exactly what this is meant to prevent, so it is not offered — not even to an organization admin.
The declaration is checkable by people who have no Mandate Vote account and no reason to trust one. The verification page carries the signature, the exact bytes it covers and the public key, so a losing candidate’s agent can verify it with any Ed25519 tool. A voter can also check their own receipt reference was among the ballots the signature covers — without it revealing, to them or anyone, how they voted.
What is guaranteed
| Guarantee | How |
|---|---|
| One person, one vote | Entitlement is claimed on the voter's row the moment a ballot is accepted, so two attempts cannot both succeed even if they arrive together. |
| Ballots carry no voter | A cast ballot has no column pointing at a person. Turnout is answerable because a separate table records that somebody voted, never what they chose. |
| A receipt proves nothing about a choice | It is derived from the voting grant, not from the selections, and is stored where no query can reach a candidate. |
| Codes are never readable | Voting codes and one-time codes are stored hashed. A copy of the database does not hand anybody a working credential. |
| Every administrative act is recorded | Append-only. There is no path in the application that edits or deletes an audit entry. |
Admins and roles
Use the name or email search and role filter to find a member. Previous and Next move through the paginated list. Choose a new role to save it; the list and role counts refresh after the server confirms the change. Role changes are recorded in the audit trail and apply to subsequent API requests, including requests from devices already signed in. You cannot demote yourself.
| Role | May |
|---|---|
| Organization admin | Everything: members, settings, billing, elections, results. |
| Election manager | Run elections — build ballots, manage the electorate, send invitations, read results. Cannot change who belongs to the organization. |
| Auditor | Read tallies and the audit trail, and nothing else. An auditor who could edit an election could not meaningfully attest to it. |
| Voter | Cast a ballot and see their own receipt. |
When something looks wrong
A member says they never got an invitation.
Check Channels for people with no verified phone or an unconfirmed email — they cannot be reached on those channels. Then check the election’s Voters panel: being on the roll does not put somebody in an election.
A voter says their code does not work.
Codes are case- and space-insensitive, so that is rarely it. More often the invitation was re-sent, which retires the earlier code — they should use the most recent message. After five wrong tries the code stops working; re-send to issue a new one.
Turnout looks lower than the number of people I invited.
Invited, verified and voted are three different counts and the Voters panel shows all three. An invitation that failed to send appears against that member with the reason.
Can I change a candidate's manifesto mid-election?
No. Editing is locked while voting is open. Close the election before changing its details. The candidate list remains protected after voting has started.
Can I see how a particular person voted?
No. Not through the interface, not through the database, not by asking us. The system is built so that the question has no answer.
Running an event
An event follows the same shape as an election: build it as a draft, publish it when it is ready, and nothing reaches anybody until you do.
Create the event
Go to Events → New event. Add a name, description, cover image, event type, venue or private meeting link, and schedule. Select the event timezone before entering times. It starts as a draft; uploaded covers are stored securely and shown on the published page.
Add ticket types
Early Bird, Regular, VIP, Student — each with a price, how many exist, and how many one person may take. A price of zero is a free ticket, which is a real ticket here: it still has a code and is still checked in at the door.
Publish
Only possible once there is at least one ticket type. Publishing a page nobody can book from would be a page that wastes their time.
Check people in
Check-in is one screen somebody stands at a door with. Scan or type a code; the field clears itself so a queue can be worked through without touching anything else.
| The door says | Meaning |
|---|---|
| Let them in | A valid ticket, not used before. It is now used. |
| Already used | Somebody came through on this code. The screen shows when, and at which gate — the difference between a double scan and a shared ticket is the time. |
| Cancelled ticket | Refunded or cancelled. Do not admit. |
| Not a ticket for this event | The code is unknown here. Check they are at the right event before turning them away. |
Register and complete payment
Choose a ticket and enter the required attendee details. If the organizer requires an account, select Sign in and return to the same event after authentication. Paid tickets continue to Paystack; use Continue payment if checkout was interrupted. A browser redirect alone does not confirm a payment: your ticket is confirmed after the server verifies it. Keep your registration reference and ticket link.
Free registrations do not require a payment. If capacity is full and the organizer enables a waitlist, join it instead. Check your registration status before travelling. Staff can search by reference or scan your QR code; the code verifies a registration without publishing your contact details.
For online and hybrid events, the organizer controls when the meeting link becomes available. Open your attendee page near the event time. Confirmation messages and scheduled reminders use the contact details provided during registration.
Nominations and awards
Create a category
Open Nominations in your workspace or the event management page. Add a category name, description and optional image. Link it to the relevant event and draft election.
Add and review nominees
Create nominees inside the category. Each receives a unique NOM reference for lookup. Check names, descriptions and images before making the category available.
Close nominations and prepare voting
Close the category before exporting nominees to the linked draft ballot. Review the candidates and voter eligibility in the election before opening voting.
What visitors can see
Published public events show their open, closed and exported nomination categories. Draft categories remain private. Publishing an event does not automatically open its linked election or give attendees voting eligibility.
Voting through WhatsApp
WhatsApp voting is available when your organization has enabled its connected WhatsApp number. Use the number supplied by your organizer. Your WhatsApp phone number must match a verified, active member account, and that member must be eligible for the particular election.
Start a conversation
Send a message to the organization’s connected number. The assistant lists elections currently available to your verified membership.
Tap your way through the ballot
Elections and candidates arrive as tappable menus — one position at a time, with photos where there are few enough to be worth sending, and an Abstain row on every race. You never have to know a keyword. Typing a number still works on handsets that cannot show a menu, and so does a ballot with more candidates than a menu holds.
Check and cast
Your selections are read back to you, then Cast my ballot and Start over are buttons rather than words to spell. Eligibility and whether you have already voted are checked again before the ballot is accepted. Keep the receipt you are sent.
No election appears
Ask the organizer to check your verified phone number, active membership and election eligibility. An invitation or event registration alone is not proof of eligibility. Closed elections and elections you have already voted in are unavailable. For ballots too long for the chat flow, follow the web ballot link provided.
Reply CANCEL to abandon a ballot you have not cast and start again. Reply STOP to leave entirely: that number gets no further messages from us, including invitations to later elections, until it replies START. The two are deliberately different, so cancelling a half-finished ballot does not quietly unsubscribe you.
If you scroll up and tap a menu from an earlier position, the assistant re-sends the one you are actually on rather than counting your tap against the wrong office.
Invoices and result access
Your organization’s billing mode determines when charges are settled. For postpaid elections, results stay locked until the election ends and its invoice is settled. Changing the workspace billing mode does not remove an existing election’s settlement requirement.
Review the invoice
Organization administrators can open Billing to find election invoices, their amounts, due dates and payment status.
Pay securely
Choose Pay invoice to continue to Paystack. If a checkout is already available, resume it. Return to the application after payment and wait for server verification.
Open results
Once payment is verified and the invoice is marked paid, authorized users can access election results. Certificates still require the election to be closed and all certification conditions to be met.
Unpaid invoice reminders are scheduled for days 1, 3, 7, 14, 21 and 28 after issue and sent to active organization administrators through their available email and SMS contacts. Pending reminders are checked again before delivery so a settled invoice does not need further reminders.
Where ticket revenue is paid
Organization administrators can open Settings → Ticket payment destination. Choose the platform account, connect your organization’s own Paystack account, or enter a subaccount code created under the platform’s Paystack account.
Choose and verify the destination
For a connected account, enter its Paystack secret key. The server validates and encrypts it; it is never shown again. For a subaccount, enter its ACCT code and confirm the beneficiary with the platform administrator. Its Paystack settlement percentage and default fee rules apply.
Configure payment notifications
For a connected account, copy the webhook URL shown in Settings into that account’s Paystack dashboard. Use test-mode credentials to verify checkout and ticket issuance before accepting live payments.
Authorize the change
Enter your current password and, if enabled, an authenticator or recovery code. Changes affect new checkouts only. Existing payments retain their original destination, so do not revoke old keys while payments still need verification.
Event revenue and platform billing are separate
This setting routes event ticket payments. Election invoices and wallet top-ups still use the platform’s existing payment integration.
Your name on messages
By default your SMS arrives from the platform’s sender name. You can ask for your own — up to 11 characters — under SMS sender IDs.
Two approvals stand between a request and a live sender name, and they are different things. First Mandate Vote reads it: your name is registered under our account with the network, so one that reads like a bank or a public body puts every organization’s messages at risk, not just yours. Then the provider decides, which takes days and is outside our hands.
Your request shows which of the two it is waiting on. Explain clearly what you will send — that explanation is what gets read, so a vague one is slower. If we cannot clear a name you are told why, and you can ask again with a different one.
Protect your account
Your profile also lists renewable sessions, five per page. Review the device, last refresh and expiry time, then choose Revoke and confirm to stop a device from renewing access. An existing access token remains valid until its short expiry; the sessions panel shows the configured maximum delay. Refresh the list if a session has rotated since it was displayed. Revoking this browser signs you out.
Open Your profile → Account security. Security changes require your current password and, when a second factor is already enabled, an authenticator or unused recovery code. Accounts created through Google must set a password through password reset before changing these settings.
| Option | How to use it |
|---|---|
| Authenticator | Choose Set up authenticator, scan the QR code in your authenticator app, then enter its current six-digit code to finish. Keep your device clock set automatically. |
| Passkey | Name the device, choose Add passkey, and complete your browser’s device verification. Passkeys require a supported browser and HTTPS (localhost is supported for development). |
| Recovery codes | Save the codes shown after setup in a private password manager or another safe place. Each works once. Generating replacement codes invalidates all previous ones. |
After setup, sign in again. Enter your authenticator code, use a registered passkey, or enter an unused recovery code when asked. For a passkey-only account, a recovery code is required to authorize changes to security settings.
Unexpected sign-in alert
Alerts show the time in UTC and an approximate browser and operating system derived from the device header. If you do not recognize the activity, change your password and contact your administrator. Never forward recovery codes, voting codes or password-reset links.
Account deletion is available in Your profile. Read the confirmation carefully: access is revoked and profile information is anonymized, while required election and audit records are preserved. Draft election and event deletion is restricted when records or dependencies make removal unsafe.
Messages and service status
Confirmations, invitations and reminders are queued before delivery. Temporary provider failures are retried; a queued message is not the same as a delivered message. If a message is missing, check the recipient details and the delivery status before resending.
SMS uses the configured primary provider with a fallback where available. Custom organization sender IDs need provider approval before use. Contact your organization administrator about sender-ID eligibility and registration.
Use the public service-status page to check reported availability before troubleshooting a connection problem. For an unresolved payment or delivery issue, send Support the election or event name, reference and approximate time. Do not include passwords, payment-card details or verification codes.
Getting help
Support in the dashboard opens a ticket. The thread stays there, so whoever picks it up next — a colleague, next year’s committee — can read what was asked and what the answer was, instead of it living in one person’s inbox.
| Field | Why it helps |
|---|---|
| Subject | A few words. It is what a list of tickets shows. |
| Category | Routes it to someone who can answer: voting, elections, members, results, billing. |
| Which election | Optional, but it is the single most useful thing you can add. |
| What happened | What you did, what you expected, what happened instead. A voter ID or a receipt reference makes it far quicker to trace. |
A ticket about a live election is urgent automatically
If you name an election that is currently open, the ticket is raised as urgent without you having to ask. Somebody with a hall full of waiting voters should not have to argue for priority.
Every ticket has a short reference like TKT-8F3A2C that you can quote on a phone call. Mark a ticket This is sorted when it is done, and reopen it if the problem comes back.