Custom postal code lookup databases

From time to time you may want to set up a list of advocacy targets that is not one of those that we maintain as shared databases.

Using a custom database with a match field

The easiest way to achieve this is to set up a custom database. This is a custom database that you set up and upload via your dashboard. Contacts are returned to supporters based on a “match field” they submit. This is typically a value selected by a drop-down field on page 1 of an action. For example, in the US you might provide a drop-down field where supporters can choose their state, and then on page 2 pull up different contacts based on the state chosen. Or perhaps supporters choose their broadband supplier on the first page, and the appropriate CEO is targeted on the 2nd page.

Custom postcode-enabled databases

You might prefer to have a custom database that brings back contacts based on postcode, ZIP or postal code. This is sometimes possible, if we already have an appropriate lookup table, but is generally a more complicated process. It requires some extra work both for you and for us, and in some cases may involve a setup cost, depending on the scale of the project.

Nevertheless, you may decide that a properly geographically mapped database really is what you need. This page sets out the kinds of mapping that are achievable, the typical process we’ll need to go through with you, and what we will need from you in order to get you up and running.

What kinds of database can we map?

Here’s a list of the geographical divisions we are currently able to map. If your list of targets corresponds to one of these, then we may be able to help.

UK

• Government office regions
• Individual nations within the UK
• Westminster MP constituencies
• Devolved assembly constituencies and regions
• District, unitary, borough and county council areas

US

• US states
• US congressional districts
• State legislature electoral districts

Canada

• Federal MP electoral districts
• Provincial parliament/assembly electoral districts

The rest of the world

• Australian MP districts
• German MEP constituencies

How the process works

Here are the typical steps for setting up a mapped database. This process will be explained in detail in the later sections of this document.

1. Tell us what you want to do. This should be the very first thing you do before you start any work on your custom list. We’ll be able to let you know whether it’s technically possible, and give you any specific guidance you’ll need for your particular project. Some technically complex projects will require some extra work on our end, for which we may need to charge. We will also need advance warning so that we can schedule some time to set up your database once you have the data ready. Typically we need at least a few weeks notice, but the more warning you can give us, the better.
2. You collect all the contact details for your advocacy targets, and format the data in an XLS file as explained below.
3. We give you a list of “Search IDs”, which are alphanumeric codes linked to geographical areas.
4. You map each target to a geographical area by inserting the appropriate ID in the data row for that target.
5. You send your completed XLS file over to us. We then load your data and make some configuration changes behind the scenes to link your contacts to a lookup table.

The particular order of steps here is not set in stone – for example you might find it easier for you to map each contact (step 4) at the same time as you are collecting and formatting the data (step 2).

Formatting the contact data file

Please take a look at this file to see the columns that need to be included in your contact data file. It also includes a single example row for an email target. You’ll need to populate your own file with as many rows as you have contacts you wish to target by email.

The following important fields must be filled in for all rows, for any contact database:

• Constituency/Organization
• Search ID (we’ll explain how to populate this below)
• Title
• First Name
• Last Name
• Salutation
• Email (every single row must have an email address)

The other fields can optionally be left blank, but all 28 columns must be present and in the correct order.

These fields are standard contact data fields that can, for example, be inserted into message content:

• Suffix
• Position Held
• Address 1
• Address 2
• Address 3
• City
• Region
• Postcode

There are also eight “biography” fields. These can be used in the normal way with our format biography functionality when setting up advocacy pages. They can also be used as criteria to filter contacts using redirect and filter.

Two final things to know:

• The file must be in XLS format, and not, say, CSV or XLSX.
• The values entered in each column must all be plain text, with no formulae or special formatting. Email addresses need to have hyperlinks cleared.

Populating the Search ID column

When your contact database is in use in an advocacy campaign, we need some way to find the right targets for a given supporter, based on their ZIP, postal code or postcode. We do this by means of a “Search ID”. Each geographical area that we are able to map is uniquely identified by one of these codes.

As an example, here is a table showing all the search IDs we use for UK MP constituencies.

When you speak to us about setting up your own custom database, we’ll provide you with a similar file for the areas you wish to map.

For each contact in your list you’ll then need to:

1. Look through the table we provide for the relevant geographical division, and pick out the corresponding Search ID.
2. Insert that ID into the Search ID field in the corresponding row in your custom contact data file.

Once all rows have been populated with Search IDs, the file contains all necessary contact data, and you’ve formatted it as described in the previous section, send it through to us, and we’ll load and configure it according to the schedule we’ve agreed with you.

After the initial upload

In some cases you may need to make updates to the database after the initial list has been uploaded. Again, please get in touch with us so that we can arrange time to load these updates for you. In particular, if you anticipate needing to make regular changes, it’s good to agree on a schedule for making these updates.

Please don’t make updates directly to the file you have already sent us for the initial upload. When we load the file for the first time, each row is assigned a unique ID in our database, so we’ll need to send you a file with these numbers inserted for you to make changes to. The same applies after each subsequent upload – you’ll need us to send you the updated file before you can make further changes.

Once you have the latest version of the database ready for editing, you can make changes in the following way:

• To edit an existing record, simply make the necessary changes to the existing record, leaving the numeric code in the first column intact.
• To add a new record, add a new row, leaving the first column blank as in your initial list.
• If you want to remove any records, please pull them out and send them to us in a separate file, making clear that they need to be deleted from your database. (Just removing them from the update file is not enough – we need to run a separate upload to tell the software to remove them.)