Overview

Custom Attributes let you bring your own data into Switchboard and use it to target and personalize your outreach.

You decide what each attribute is: a donor tier, an engagement score, a county, a polling place, an ID from another system you use. You give it a type, so Switchboard knows whether the values are text, numbers, dates, or true/false. Then you add values for individual phone numbers and email addresses.

Once your values are in Switchboard, you can:

• Target on them in Audience Builder

• Personalize with them in a text or email, the same way you use a reusable field

• Export them as columns when you export a list

You can set all of this up in Switchboard on the Custom Attributes page under "Tools", or through our Public API. See the Switchboard API documentation for endpoints, limits, and error codes.

How are Custom Attributes different from Reusable Fields and List Fields?

Custom Attributes are the only one of the three that you define yourself and can target on.

Custom Attributes do not replace or change Reusable Fields or List Fields. Everything you have set up today keeps working exactly as it does now, and you can use all three in the same message. For a refresher on the other two, see How to Use Reusable Fields.

How do I create a Custom Attribute?

Go to Tools › Custom Attributes and click New attribute.

Each attribute needs four things:

1. Name. What you and your team will see throughout Switchboard. "Donor Tier", "Engagement Score".

2. Key. How you refer to the attribute when you add values, and what you type into a message: {{donor_tier}}. Keys use lowercase letters, numbers, and underscores.

3. Type. Text, Number, Score, True/false, Date, or Date and time. The type decides how you can filter on it later (e.g. a Number gives you greater than and less than, a Date gives you before and after).

4. Example value. A stand-in that shows in message previews and test sends, so you can see what your text will look like before any real values are in.

A description is optional, and worth filling in if more than one person on your team will be using the attribute.

The key and the type are permanent. You can rename an attribute, change its example value, and update its description whenever you want, but you cannot change its key or its type after you create it. If you need a different key or type, create a new attribute.

How do I edit or archive a Custom Attribute?

Editing

Click the edit icon on any row of the Custom Attributes page. You can change the name, the example value, and the description.

The key and the type can't be changed. Renaming an attribute doesn't change its key, so any message or saved search already using {{donor_tier}} keeps working.

Archiving

Custom Attributes can't be deleted, only archived. If you created an attribute by mistake, or you've stopped using one, archive it with the archive icon on its row.

Archiving tidies up your menus, but it doesn't delete anything:

• Saved searches and messages already using the attribute keep working

• Values from an archived attribute stay on the phone and emails, and you can still apply that attribute's values in this state as well.

• You can't add it to a new audience or a new message

• You can restore it at any time

Archived attributes are hidden from the table by default. Turn on Show archived to see them, then use the restore icon to bring one back.

How do I add values to my phone numbers and emails?

Once you've created and defined your custom attribute(s), you can apply it to phones and emails: click Apply Attributes on the Custom Attributes page and upload a CSV.

First tell Switchboard whether your file holds phone numbers or email addresses, one file can't do both. Files can be up to 100MB.

Four columns, and one row for each phone number and attribute combination:

• phone_number (or email_address, if that's what you picked)

• attribute — the attribute's key, exactly as you created it

• value — what you want stored

• action — set to add or update a value, remove to clear one

phone_number,attribute,value,action
+12025550142,donor_tier,Gold,set
+12025550142,last_gift_date,2026-03-04,set
+12025550199,legacy_segment,,remove

A few things worth knowing before you upload:

• Uploading won't wipe out your other data. Only the attributes in your file change. Everything else on that phone number stays as it is.

• Blank values are skipped, not cleared. If you want to erase a value, use remove in the action column.

• Opt-in to add phone numbers and emails that aren't in Switchboard yet. Your file can bring in new people as well as update people you already have.

How do I know my upload worked?

Check the Uploads tab on the Custom Attributes page. Every upload your organization has run is listed there, newest first, with the file name, whether it was phone numbers or emails, and the date.

While an upload is running it shows as Processing. You don't have to wait on the page — you can navigate away and come back.

When it finishes you'll see two counts:

• Rows applied: values that landed

• Rows skipped: rows Switchboard couldn't use, usually because the attribute key doesn't match one you created, the value doesn't fit the attribute's type, or the phone number isn't in a format we recognize. If rows were skipped, you can download a file listing them and why, fix those rows, and upload just that file again.

If the whole upload shows as Failed, it's almost always the file itself (e.g. a missing or misspelled column header, or a file of emails uploaded as phone numbers).

New values can take up to a minute to show up across Switchboard after an upload completes.

How do I target an audience with a Custom Attribute?

In Audience Builder, add a Custom Attributes filter step and pick your attribute. The options you get depend on the attribute's type.

Checking your coverage

On a Saved Search or a list, you can see how many phones or emails have a value for each attribute, like 500 / 1,000.

How do I personalize a message with a Custom Attribute?

The same way you use a Reusable Field. In a Broadcast or an Email Blast, open the Fields menu in the composer and pick your attribute from the Custom Attributes group.

The menu shows you the coverage count next to each attribute, so you can see what you're working with as you write.

Learn more about how to personalize messages here.

What happens when someone has no value

Always give your token a fallback, so a missing value doesn't leave a hole in your text:

Hi {{sb_first_name}}, as a {{donor_tier or "valued"}} supporter...

Switchboard will also warn you before you send if some of your audience is missing a value for a token you used.

In your preview and test sends, an attribute with no value shows its example value.

Can I export Custom Attributes?

Yes. When you export a list, you'll see a Custom Attributes section in the export options alongside the Reusable Fields.

Toggle it on and each attribute will appear in the csv as its own column. The column header is the attribute's key, so donor_tier key in Switchboard is a donor_tier column in your file. People with no value for that attribute get an empty cell.

This is also a practical way to spot-check a big upload: with the attribute as filter criteria, convert a saved search to a list and compare that list’s export against the file you sent.

Things to know

A value belongs to the exact phone number or email address you gave it to

For example, if you add a donor tier to someone's phone number, you can filter a phone audience on that score and find them. Filtering an email audience on the same score will not find them, even if Switchboard knows that phone number and that email address belong to the same person.

Let us know if you'd like us to support matching values across phone numbers and email addresses in a future update.

Lists you've already built won't change

A list is a snapshot of the people in it at the moment you built it. Adding new attribute values doesn't update existing lists.

Saved searches do pick up new values, each time they refresh.

You can use the page and the API together

You don't have to pick one. An attribute someone creates on the Custom Attributes page can be filled by a nightly sync running against the API, and values you upload on the page sit alongside values pushed through it. There's one set of attributes and one set of values for your organization, however they got there.

API read responses now include an attributes object so integrations can confirm the current values Switchboard has stored. If a phone number or email address has no attribute values, the response includes an empty attributes object.

Not available yet

• Uploading attributes as part of creating a list. The attribute upload and the list upload are separate steps today.

• Seeing attribute values on an individual phone number or email page. To check what's on a specific person right now, with the attribute as filter criteria, convert a saved search to a list and export it.

• SQL Mirror access.

These are on our list. If one of them is blocking you, let us know.

Questions about Custom Attributes, or something not working the way you expected? Reach out to support@oneswitchboard.com.