FAQ
      Back to home
      1. BallotReady Support
      2. Customers
      3. FAQ

      Prepare Links with CivicEngine

      Introduction


      CivicEngine products all require an address to show voters their most accurate information. Generally, voters enter their address into an embeddable widget to access the tool, but if their address is known, they can access the tool by clicking a prepare link like this: 

      https://www.ballotready.org/w/prepare?address=332%20S%20michigan,%20chicago,%20IL,%2060605&utm_source=demo&default_locale=vi
      The above link has three parameters: address, utm_source, and default_locale. Using these parameters, the BallotReady engine will behave exactly like someone has entered through the widget and entered the address ‘332 S Michigan, Chicago IL’ and chosen the Vietnamese language option at a link with the utm_source parameter in the URL. Every time that link is clicked, it’ll create a new ballot record with those parameters, but with separate ballot_ids. 

      Structure

      The prepare link should be formatted like this: 

      https:// + instance_url + /w/prepare? + address= + address input + & + any optional parameters 
      Your instance_url will be given to you by your onboarding manager, and will be the way to access your CivicEngine product without a widget or prepare link. The format the instance_urls follow is usually app.customername.civicengine.com. Go Ballot’s instance_url is app.goballot.civicengine.com. 

      Parameters


      These are the parameters you can build into your prepare link. Note that any prepare links will not pass any UTM codes from the page they are hyperlinked into, they will only pass the UTM codes built into the link. The address parameter is the only required parameter and should always come first, immediately after the ?.

      The parameters are the same as the ones used in our embed widget. See our widget documentation for additional details about these parameters.

      Parameter User Data Field Widget Connection Notes
      address address address required
      first_name first_name data-input-first-name  
      last_name last_name data-input-last-name  
      email email data-input-email  
      phone phone data-input-phone  
      custom custom data-input-custom-field custom dropdown field in the widget
      utm_term utm_term data-utm-term Go Ballot should use this field to pass unique IDs
      utm_source utm_source data-utm source  
      utm_medium utm_medium data-utm medium  
      utm_campaign utm_campaign data-utm campaign  
      utm_content utm_content data-utm content  
      default_locale locale data-default locale Only functional if your civic center is translation enabled.

      Link Creation

      You can create your link by inputting the following code into your browser’s console, substituting any of the parameters you wish:

      encodeURI('https://www.ballotready.org/w/prepare?address=332 S Michigan Ave, Chicago IL&first_name=Sandra&last_name=Smith&phone=888-888-8888&utm _term=demo_alloy_id') 

      Passing UTM codes without a prepare link 

      If you’d like to direct someone to the tool with a certain UTM code, but there’s no address you have for them, you can give them a link to your landing page with that UTM parameter in the URL and the UTM code will be passed through the widget, as long as there are no UTM parameters defined for that widget. More information about using UTM codes with the CivicEngine widget can be found here.