Importing a List from an ActionKit Report

Last updated: July 23, 2026

Overview

The ActionKit List Import lets you build a Switchboard phone list or email list directly from an ActionKit query report. Instead of exporting a CSV from ActionKit and re-uploading it by hand, you point Switchboard at a report you've already built in ActionKit, and Switchboard runs it and imports the results for you.

This is a one-time import (not a recurring sync). To bring in fresh results later, run the import again.

Before you start

You'll need:

An ActionKit integration connected to your Switchboard organization. If you haven't connected ActionKit yet, follow these steps to get set up:
- Create a new ActionKit “staff” member using the following information. This will be how our requests to ActionKit are authenticated.
  - Email: developers+{orgname}@oneswitchboard.com (use your Switchboard Organization Name with no spaces). For example: developers+barbie@oneswitchboard.com
  - Username: we will send this to you via Signal!
  - Password: we will send this to you via Signal!
    - Contact support@oneswitchboard.com to ask a member of the Customer Experience team to create a username and password for you. Provide a cell phone # so that they can Signal you the username and password.
    - If you've created an ActionKit integration in Switchboard for a campaign already and are looking to set it up for a different instance (short code, voter contact only, etc.), use the username and password that was given to you previously.
- Give the user superuser access. If you would rather not give the user superuser user access then we need at least "all read" access.
A query report in ActionKit that returns the people you want to import. The report's columns determine what data comes into Switchboard (see "How report columns are handled" below).

Set up your report in ActionKit

Before importing, build a query report in ActionKit that returns the people you want, with columns that match what Switchboard expects:

In ActionKit, go to the Reports tab and click Add a Query (or copy an existing query from Browse All). Switchboard imports from query reports only, dashboard reports can't be used. We recommend using the “Users” report type.
Build the query with the point-and-click Query Builder or with Custom SQL, either works. While editing SQL, the Tables link above the SQL field lists the available tables and columns, which helps when finding the right phone field.
Include a phone column with a number on every row (for email lists, include an email column instead). See the phone-column guidance under "How report columns are handled" below.
Name or alias your columns to the recognized names so they map to standard Switchboard fields automatically; any other column comes in as a custom field you can still use.
Add any other columns you want to bring along (e.g. VAN ID, address, custom scores) — they'll import as custom fields.
Keep the report under ~1 GB. ActionKit can't produce a report larger than about 1 GB, and reports over that can't be imported. ActionKit doesn't show a report's size up front, so if you have a large universe, split it into smaller reports (filter by a field (like state or region), or use LIMIT/OFFSET in your SQL) and import them one at a time.
Give the report a Name and Short name, then save it. Saved query reports appear in the picker when you import (newest first).

These steps follow ActionKit's own interface, which may change over time — see ActionKit's Reports documentation for the latest on building and running reports.

How to import a list from an ActionKit report

Click the New Audience button from the Phone Audiences or Broadcast pages and then click Import from ActionKit.
Select the ActionKit report you want to import from the list of available reports.
Confirm and start the import.

Switchboard runs the report on ActionKit's side, which can take time for large universes. When it's done, Switchboard downloads the results and processes them into your list. You can watch progress (and pause or cancel) from the list's import status, just like other imports.

How report columns are handled

The columns in your ActionKit report decide what data Switchboard imports.

Recognized columns map automatically to standard Switchboard fields. These include user_id, first_name, middle_name, last_name, address1, city, state, and zip. See the phone-column note below for how phone fields are matched.
Any other column is imported as a custom field on the list contacts, so you can use it for targeting and message personalization. See How to Use Reusable Fields for how custom fields work across integrations.

Switchboard Tip: Because column names are the contract, alias the columns in your report SQL to one of the recognized names (e.g., SELECT cell AS phone) so they map cleanly into Switchboard.

Required columns:

A phone list import requires a recognized phone column.
An email list import requires a recognized email column.

If the required column is missing, the import stops with an error before any contacts are created, so you can fix the report and try again.

Your report needs a phone column, with a number on every row.

ActionKit's "Most Recent Mobile" column works as-is, or you can alias another column to phone or phone_number.
Different phone fields are populated to different degrees from one ActionKit instance to the next — use whichever phone column is most completely filled in for your organization.
Filter the report so your phone column "Is Not Empty," so every row has a number to import.
The multi-number "List of Numbers" column can't be used as the phone source.

Opt-in and subscription status

A report import is treated like a CSV upload, not like an ActionKit form submission. Form submissions are an affirmative opt-in and come in as opted in; a report import is not, so imported contacts use the same opt-in and subscription defaults as a manually uploaded CSV. Make sure you have the appropriate consent to contact the people in your report before messaging them.

Good to know

This is a one-way import. Texting or emailing contacts you imported from ActionKit does not send any data (opt-outs, action results, canvass responses) back to ActionKit. The report import only pulls data into Switchboard.
Imported contacts live in Switchboard independently. Once a report has been imported, those contacts exist in your Switchboard account on their own. Editing or deleting the report in ActionKit later won't change contacts that were already imported, and it won't affect messages you've already sent them.
To refresh your list, run the import again. Because this is a one-time import rather than a live sync, re-running the report is how you pull in new or updated people.
If a person has more than one phone number in your report, each phone row becomes its own contact in Switchboard (the same way a CSV upload with multiple rows would), so one person could receive more than one text. Build your report to return a single preferred phone per person if you want to avoid that.

Troubleshooting

"Report failed to run." This usually means an error in the report's SQL on the ActionKit side. Switchboard surfaces ActionKit's error message, open the report in ActionKit, fix it, and re-run the import.
"No phone/email column found." Add (or alias) a recognized phone or email column to your report and try again.
Import is taking a long time. Large reports take time to run on ActionKit before Switchboard can download them. The import will continue in the background; you can leave the page and check back.
Your report isn't in the list to pick from. ActionKit shows all of your query reports with the newest first, so page through the list to find yours. Also confirm it's saved as a query report (dashboard reports won't appear). If it's still missing, the connected ActionKit account may not have permission to run reports.
The import finished but no contacts were added. The report likely returned zero rows — open it in ActionKit and confirm it returns the people you expect.
Your report is too large to import. ActionKit caps report downloads at ~1 GB, and Switchboard imports by downloading the report, so a very large universe can't come through in one report. Split your audience into smaller reports (filter by a field, or use LIMIT/ OFFSET in the SQL) and import them separately.