Skip to main content

CiviCRM

Connect your CiviCRM site to keep your members synced into Talvo, then add them to a voter roll without uploading a spreadsheet.

Before you start​

  • Member import must be switched on for your organisation. If you can't see Integrations in Settings, get in touch and we'll switch it on.
  • You need to be an administrator in your Talvo organisation to connect CiviCRM. Election managers can add synced members to a voter roll once it's connected.
  • Your site needs CiviCRM 5.36 or later.
  • Your CiviCRM administrator needs to set up an API key for Talvo first. The steps are below.

Set up CiviCRM for Talvo​

Your CiviCRM administrator should do this once.

  1. Create a CiviCRM user for Talvo with only these permissions:
    • access CiviCRM
    • view all contacts
    • access CiviMember (needed to import current members)
    • authenticate with api key
  2. Give that user's contact an API key, for example with the API Key extension, or with Contact.update in the API Explorer.
  3. Allow API keys in the X-Civi-Auth header. Go to Administer, System Settings, Authentication (CiviCRM 5.47 or later), then tick API key under the X-Header flow.
  4. Leave the authentication guards at their defaults (site_key and perm).
  5. If your site is behind a firewall or Cloudflare, allow requests to /civicrm/ajax/api4/*.

Using a separate user with only these permissions means Talvo can read your contacts and memberships but can't change anything.

Talvo works with CiviCRM on WordPress, Drupal and Joomla, and works out the right address format by itself when you connect.

Connect CiviCRM​

  1. In Talvo, go to Settings, then Integrations.
  2. Enter your CiviCRM site address, for example https://members.example.org.uk.
  3. Paste the key from the Talvo user's contact into CiviCRM API key.
  4. Select Connect CiviCRM.

Talvo tests the connection before saving anything. If it's refused, nothing is stored.

Choose who to import​

  1. Under Who to import, select Change who to import.
  2. In Import from, choose:
    • Current members: people with a membership whose status counts as current (by default New, Current and Grace). To import only some membership types, choose them in Membership types. Leave it empty to import every type.
    • A group: everyone in one CiviCRM group, including smart groups.
  3. Decide whether to tick Include members who have opted out of emails. This is off by default. Election invitations are usually service emails rather than marketing, but members who opted out may not expect them.
  4. Select Save choices.

People who are marked as deceased or deleted in CiviCRM are never imported.

Sync your members​

  • Select Preview to see what a sync would do. Nothing is saved.
  • Select Sync now to import your members. You can leave the page: the sync carries on in the background. If you stay on the page and it pauses, select Carry on syncing.

After the first sync, Talvo syncs once a day by itself.

Sync history shows each sync and what happened. If some people couldn't be imported, you can download a list of their CiviCRM contact IDs and the reason.

Add members to a voter roll​

  1. Open a draft election, or one in review, and go to the Voters tab.
  2. Find Add members from Action Network / CiviCRM.
  3. To add only some members, such as one membership type, choose them under Only these groups. Leave it empty to add everyone.
  4. Select Add all CiviCRM members to the roll, or Add groups to the roll.

What a sync does​

What you seeWhat it means
NewThe person wasn't in Talvo yet.
UpdatedSomething about them changed, such as their email address.
Not includedThey're outside the people you chose to import, deceased, deleted, or their email is bouncing.
Opted out of emailsThey opted out of emails, and you haven't chosen to include them.
Erased at their requestThey asked to be erased from Talvo. They are never imported.
Email already usedAnother member already has this email address. Merge the duplicate contacts in CiviCRM.

People who leave, or no longer match your choices, are archived rather than deleted, and are left off new voter rolls. If they come back, so do they.

If a sync finds nobody at all, Talvo doesn't archive anyone. This usually means the API key or group has changed.

If something goes wrong​

MessageWhat to do
Couldn't connectCheck the site address and API key, and that API keys are allowed in the X-Civi-Auth header.
Talvo can't read memberships on this site. Check the CiviMember permission.Give the Talvo user the access CiviMember permission, or import from a group instead.
The sync stoppedSelect Test connection. If your firewall blocks Talvo, allow /civicrm/ajax/api4/*.

Change the API key or disconnect​

  • To use a new key or site address, select Change the API key, enter the details, then select Save new key.
  • To check the connection, select Test connection.
  • To stop syncing, select Disconnect CiviCRM. Talvo deletes the API key, the sync history and the members it imported. Voter rolls you've already built are not changed.

Your data​

Talvo only keeps each member's name, email address, membership type or group, and CiviCRM contact ID. Everything else is dropped before it's stored. Your API key is encrypted, and disconnecting deletes it.