> ## Documentation Index
> Fetch the complete documentation index at: https://docs.politicalcomms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Step 3: Upload & Organize Contacts

> Import voter lists via CSV, validate with carrier lookup, segment for targeting, and manage opt-out lists.

<Info>
  **Estimated time:** 15–30 minutes
</Info>

## Overview

Import your contact lists and organize them for targeted messaging. Use carrier lookup to validate numbers and filter out landlines.

## Tasks to complete

<Steps>
  <Step title="Prepare Your Contact List (CSV)">
    Format as CSV with a `phone` column (required, 10-digit format) and any other columns you want to use as merge tags, such as first name, last name, city, state, and zip. Use a clear header on every column.
  </Step>

  <Step title="Upload Contacts">
    Navigate to **Contacts → Import** and upload your CSV file. Choose who owns the list and which column holds the phone number. By default every other column becomes a merge tag automatically; you can choose which columns to map instead (see [Merge tags from your columns](#merge-tags-from-your-columns)). Maximum 1 million rows per upload. System automatically validates phone number format.
  </Step>

  <Step title="Run Carrier Lookup (Recommended)">
    Enable carrier lookup during import to identify landlines, validate numbers, and detect carrier information. Prevents wasted sends to landlines. A list cannot be used on a project until its analysis finishes.
  </Step>

  <Step title="Create Contact Segments">
    Organize contacts into groups based on location, voter data, or custom fields for targeted campaigns.
  </Step>

  <Step title="Manage Opt-Outs">
    Review and maintain opt-out lists. System automatically manages STOP keywords, but you can manually add numbers if needed.
  </Step>
</Steps>

## Pro tips

<Tip>
  * Always run **carrier lookup** to filter landlines before sending - it saves money.
  * Keep opt-out lists clean - never message opted-out contacts.
  * Use **custom fields** to store voter data, polling responses, or donation history.
  * Segment contacts **before** creating projects for better targeting.
  * Raising money on WinRed? Create a **WinRed list** under Contact Management and paste the generated webhook URL into WinRed's integration settings - donors and leads flow into the list automatically, with donor details available as merge tags.
  * Use the **By Area Code** segment operation to carve a list geographically, and **org-wide segments** ("All brands" / "All projects") to build audiences like "everyone who clicked a link in any project."
</Tip>

## Merge tags from your columns

When you upload a text list, **Map all columns automatically** is selected, and every column except the phone column becomes a merge tag.

* A column whose header matches a standard field gets the standard tag. Standard fields are first name, last name, address, address line 2, city, state, and zip. Common aliases match too, such as "First", "FName", and "Zip Code". A first name column gets `{first_name}`.
* Every other column gets a tag named after its header, in lowercase with underscores. `SURVEY_LINK` becomes `{survey_link}` and `Donor Tier` becomes `{donor_tier}`.
* A header that starts with a digit gets a `field_` prefix, so `2024 Vote` becomes `{field_2024_vote}`.
* A name that would repeat gets a numeric suffix, such as `_2`.

To decide for yourself, select **Choose which columns to map**. Only the columns you map get a merge tag. If you map none, all columns are mapped automatically.

The list's page has a **Fields** section that shows each column and its merge tag. Select **Edit fields** to rename a tag, switch a column to a standard tag, or remove a tag. This works for uploaded lists and segments.

This applies to lists created from now on. Lists you uploaded earlier are unchanged. Opt-out list uploads have no merge tags. Importing through the API? See `merge_tags` on [Import Contact List](/api-reference/introduction). Reading a list through the API returns its available merge tags.

## Segment and split by carrier

In the Segment Builder, the **By Carrier** operation groups a list by mobile carrier: AT\&T, Verizon, T-Mobile, Other carriers, and Unknown, each with its contact count. It combines with the other operations, so you can, for example, keep one area code and only Verizon numbers.

On an analyzed list's page, the **Split by carrier** card creates one new list for each carrier you select. The new lists keep the source list's analysis, so there is no second analysis charge. A list that has not been analyzed shows all of its contacts under Unknown; run carrier lookup first to get real groups.

## Next step

<Card title="Step 4: Create Your First Messaging Project" icon="message" href="/onboarding/first-project">
  With contacts organized, you're ready to create your first messaging project.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.