broadcasts

• id - Unique identifier for the broadcast.

• created_at - ISO 8601 timestamp for when the broadcast was created.

• modified_at - ISO 8601 timestamp for when the broadcast was last modified (such as a status update).

• start_time - ISO 8601 timestamp for when the broadcast started.

• scheduled_time - ISO 8601 timestamp for the broadcast’s scheduled start time, if any.

• phone_list_id - The unique identifier of the phone list used in this broadcast, or null if no phone list associated.

• title - Name of the broadcast. This is shown in the Switchboard app to help identify broadcasts similar to a file name.

• description - Description of the broadcast. This is shown in the Switchboard app when you open a broadcast as a place to store notes and additional details that the title does not cover.

• creator - Identifier for the user who created the phone list. Generally an email address.

• status - The current state of the broadcast.

  • draft: The broadcast has been created but not scheduled or sent.

  • error: The broadcast failed to send.

  • scheduled: The broadcast has been scheduled for sending at a later date and/or time.

  • sending: The broadcast is actively sending.

  • paused: The broadcast was paused during sending.

  • sent: The broadcast has completed sending its messages.

  • stopped: The broadcast has been paused permanently.

• clicks - The number of times someone has clicked on a Switchboard-tracked link originating from this broadcast.

• donations - The number of times someone has donated to the campaign using a Switchboard-tracked donation link originating from this broadcast. You must have an integration with a donation provider configured in Switchboard for this to work.

• amount_raised - The amount of money donated to the campaign that Switchboard was able to tie to this broadcast in US dollars. You must have an integration with a donation provider configured in Switchboard for this to work.

• cost_estimate - The amount Switchboard estimates this broadcast to cost the organization if sent in US dollars.

• total_messages - The number of messages sending or sent for this broadcast.

• previously_opted_out - The number of phones who opted out before the broadcast and whom Switchboard will not attempt to send messages to.

• skipped - The number of phones who Switchboard will skip for reasons other than opt-out (e.g. being a landline).

• failed_to_deliver - The number of messages that could not be delivered.

• delivered - The number of messages that were successfully delivered.

• opt_outs - The number of phones who have opted out after receiving this broadcast but before receiving another.

• replies - The number of phones who have replied since this broadcast was sent.

• message_text - The text template that is being sent for this broadcast.

• media_urls - Public urls that were sent in this broadcast.

phone_lists

• id - Unique identifier for the phone list.

• created_at - ISO 8601 timestamp for when the list was created.

• modified_at - ISO 8601 timestamp for when the list was last modified (such as a status update).

• name - Shown in the Switchboard app to help identify phone lists, similar to a file name.

• description - Shown in the Switchboard app when you open a phone list. A place to store notes and additional details that the name does not cover.

• creator - Identifier for the user who created the phone list. Generally an email address.

• status - The current state of the phone list.

  • processing: The phone list is currently being processed.

  • error: The phone list failed to process.

  • ready: The phone list has completed processing and is ready for sending.

• num_contacts - Total number of contacts in the phone list.

phone_messages

• unique_key - Unique identifier for a phone message.

• modified_at - ISO 8601 timestamp for when the phone message was last modified.

• broadcast_id - Unique identifier for the broadcast that sent this message.

• to_number - Phone number of the receiver of the message in E.164 format.

• from_number - Phone number of the sender of the message in E.164 format.

• status - The current state of the message.

  • created: The message has been created in the system but sending has not begun.

  • presend: The message is being prepared for send.

  • optedout: The message is not going to be sent because the receiver opted out.

  • skipped: The message is not going to be sent (e.g. because the receiver is a landline).

  • paused: The message send process has been paused.

  • holding: The message is being held for some reason.

  • accepted: The message has been accepted by the vendor.

  • scheduled: The message has been scheduled to be sent at a later date.

  • queued: The message is on the queue waiting to be sent.

  • sending: The message is actively sending.

  • sent: The message has been sent but we have not received a delivery notification.

  • receiving: This is an incoming message that we are processing.

  • received: This is an incoming message that we have processed.

  • delivered: The message was delivered successfully. Not all phones send this information, so the phone may stay in sent.

  • undelivered: The message was not delivered. See error_code for details.

  • failed: The message failed to send. See error_code for details.

  • read: The message was read by the receiver. Not all phones send this information.

  • cancelled: The message send was cancelled.

• error_code - If the message failed to send, this is the error code indicating what happened. These are Switchboard-maintained error codes. Learn more →

• message_type - The type of message.

  • unknown: The message type is unknown. This can only happen for incoming messages.

  • mms: This is an MMS message.

  • sms: This is an SMS message.

• message_direction - Either "inbound" or "outbound", indicates an incoming or an outgoing message.

  "inbound" indicates a message sent to one of your organization's numbers. "outbound" messages can be a few different types of messages:

  • Outgoing broadcast message (broadcast_id will be populated).

  • A test send from the broadcast page.

  • Manual sends from the inbox.

  • Switchboard-default auto responses, like "You have been opted out" (Note: you are never charged for these).

  • Automated responses from custom keywords. Learn more →

  • Automated new donor/subscriber messages. Learn more →

• count_message_segments - Number of message segments sent for this message. Will always be 1 if message_type = 'mms', but may be more than 1 for message_type = 'sms'.

  NOTE: This field is only updated nightly (~1-2AM), when we confirm and finalize the correct number of segments to be billed.

• sent_at - When the message was sent.

• received_at - When the message was received, if an inbound message.

• is_opt_out - If true, this is an incoming opt-out message that resulted in opting out this phone (if not already opted out).

• text - The message text sent (or received).

• media_urls - Public urls that were sent in the message.

  NOTE: These last four fields are included for easy compatibility with our exports and API, but are not always fully up-to-date. They increment for about 2 weeks after a message is sent, but then are only refreshed once per week. This statistically captures 99.97% of actions, but if you want the the most recent counts, please aggregate yourself using joins to phone_message_actions or actblue_donations.

• clicks - The number of times a Switchboard-tracked link in this message has been clicked.

• donations - The number of times someone has donated via a Switchboard-tracked link in this message that we detected. You must have an integration with a donation provider configured in Switchboard for this to work.

• donation_amount - The amount of money donated to the campaign using a Switchboard-tracked link in this message in US dollars. You must have an integration with a donation provider configured in Switchboard for this to work.

• replies - The number of replies received to this message.

phones

• phone_number - E.164 Formatted number

• created_at - ISO 8601 timestamp for when the phone was added in this organization.

• modified_at - ISO 8601 timestamp for when the phone was last modified.

• carrier_name - The name of the carrier who owns the to number.

• is_opted_out - Is this phone opted out

• phone_type - The type of phone number.

  • landline: Landline

  • mobile: Mobile phone

  • voip: Voice over Internet Protocol

  • unknown: Could not be determined

• is_valid - Phone number has been validated as real

• first_name - The first name associated with the phone

• middle_name - The middle name associated with the phone

• last_name - The last name associated with the phone

• preferred_name - The preferred name associated with the phone

• city - The city associated with the phone

• street_address - The street address associated with the phone

• state_abbr - US 2 letter state abbreviation associated with the phone

• zip_code - US zip code associated with the phone

• custom_source - The custom source associated with the phone

• custom_score - The custom score associated with the phone

• custom_id - The custom id associated with the phone

phone_message_actions

• broadcast_id - Unique identifier for the broadcast that sent the message that prompted this action.

• to_number - Phone number of the recipient that took this action.

• created_at - ISO 8601 timestamp for when the action was recorded.

• action - What action was recorded.

  • CLICK - Message recipient clicked on tracked link in the message.

  • BOT_CLICK - A click on tracked link in the message was recorded, but Switchboard has identified it as a non-human click.

  • DONATION - Message recipient donated via tracked link in the message.

  • FORM_RESPONSE - Message recipient responded to Switchboard form linked in the message.

  • REPLY - Message recipient replied to a message.

• user_agent - Any recorded user agent data recorded when receiving clicks or form responses. Can be parsed to extract information on user device types.

  Note: user_agent data only available for clicks & form responses

phone_list_phones

• phone_list_id - Parent phone list

• phone_number - Phone number included on this list. Unique per phone_list_id.

• created_at - ISO 8601 timestamp for when the mapping record was generated.

token_data

• token - Tracking token used to link phone numbers to their donations

• created_at - ISO 8601 timestamp for when the token was generated.

• broadcast_id - Unique identifier for the broadcast that generated this tracking token

• to_number - Phone number of the recipient that this token was generated for and sent to.

email_blasts

• id - Unique identifier for the email blast.

• created_at - ISO 8601 timestamp for when the email blast was created.

• modified_at - ISO 8601 timestamp for when the email blast was last modified (such as a status update).

• start_time - ISO 8601 timestamp for when the email blast started.

• scheduled_time - ISO 8601 timestamp for the email blast’s scheduled start time, if any.

• email_list_id - The unique idenfier of the email list used in this blast, or null if no email list associated.

• title - Name of the email blast. This is shown in the Switchboard app to help identify email blasts similar to a file name.

• description - Description of the email blast. This is shown in the Switchboard app when you open an email blast as a place to store notes and additional details that the title does not cover.

• status - The current state of the email blast.

  • draft: The email blast has been created but not scheduled or sent.

  • error: The email blast failed to send.

  • scheduled: The email blast has been scheduled for sending at a later date and/or time.

  • sending: The email blast is actively sending.

  • paused: The email blast was paused during sending.

  • sent: The email blast has completed sending its messages.

  • stopped: The email blast has been paused permanently.

• email_sender - The email address to send the email blast from.

• email_sender_reply_to - The email address to tell email clients to reply to instead of the sender, if applicable.

• opens - The number of times someone has opened an email that we detected.

• unique_opens - The same as opens but not counting the same person opening the same email more than once.

• clicks - The number of times someone has clicked on a Switchboard-tracked link originating from this email blast.

• unique_clicks - The same as clicks but not counting clicking the link from the same email more than once.

• spam_reports - The number of times someone has reported an email from this blast as spam that we detected.

• donations - The number of times someone has donated to the campaign using a Switchboard-tracked donation link originating from this email blast. You must have an integration with a donation provider configured in Switchboard for this to work.

• amount_raised - The amount of money donated to the campaign that Switchboard was able to tie to this email blast in US dollars. You must have an integration with a donation provider configured in Switchboard for this to work.

• total_messages - The number of messages sending or sent for this email blast.

• previously_unsubscribed - The number of emails who were unsubscribed before the email blast and whom Switchboard will not attempt to send messages to.

• skipped - The number of emails who Switchboard will skip for reasons other than being unsubscribed (e.g. invalid emails).

• failed_to_deliver - The number of messages that could not be delivered.

• delivered - The number of messages that were successfully delivered.

• unsubscribes - The number of emails who have unsubscribed after receiving this email blast.

• subject - The subject line template of the email being sent for this email blast.

• html_content - HTML template of the email being sent for this email blast.

• text_content - Text template of the email being sent for this email blast.

email_lists

• id - Unique identifier for the email list.

• created_at - ISO 8601 timestamp for when the list was created.

• modified_at - ISO 8601 timestamp for when the list was last modified (such as a status update).

• name - Shown in the Switchboard app to help identify an email list, similar to a file name.

• description - Shown in the Switchboard app when you open an email list. A place to store notes and additional details that the name does not cover.

• creator - Identifier for the user who created the email list. Generally an email address.

• status - The current state of the email list.

  • processing: The email list is currently being processed.

  • error: The email list failed to process.

  • ready: The email list has completed processing and is ready for sending.

• num_contacts - Total number of contacts in the phone list.

email_messages

• email_blast_id - Unique identifier for the email blast that sent this message.

• to_email - Email address of the receiver of the message.

• from_email - Email address of the sender of the message.

• status - The current state of the message.

  • created: The message has been created in the system but sending has not begun.

  • presend: The message is being prepared for send.

  • optedout: The message is not going to be sent because the receiver opted out.

  • skipped: The message is not going to be sent (e.g. because the receiver does not exist).

  • paused: The message send process has been paused.

  • queued: The message is on the queue waiting to be sent.

  • accepted: The message has been accepted by the vendor.

  • deferred: The receiver is not yet ready to receive the message. The vendor will retry shortly.

  • failed: The message failed to send. See error_code for details.

  • delivered: The message was delivered successfully.

  • infer_delivered: We believe the message was delivered successfully but have not seen definitive proof.

  • undelivered: The message was not delivered. See error_code for details.

• error_code - If the message failed to send, this is the error code indicating what happened.

• sent_time - When the message was sent.

• unsubscribed - If true, the user unsubscribed using a link in this message.

• opens - How many times this message has been opened that we could detect.

• clicks - The number of times a Switchboard-tracked link in this message has been clicked.

• spam_reports - The number of times someone has reported this email as spam that we detected.

• donations - The number of times someone has donated via a Switchboard-tracked link in this message that we detected. You must have an integration with a donation provider configured in Switchboard for this to work.

• donation_amount - The amount of money donated to the campaign using a Switchboard-tracked link in this message in US dollars. You must have an integration with a donation provider configured in Switchboard for this to work.

• subject - Subject line for this email.

• html_content - Raw HTML content for this email.

• text_content - Raw plaintext content for this email.

emails

• email_address - The email address

• created_at - ISO 8601 timestamp for when the email was added in this organization.

• modified_at - ISO 8601 timestamp for when the email was last modified.

• valid_email - Whether this switchboard has determined this email is valid or not. A valid email has a higher deliverability.

• unsubscribed - Whether this email unsubscribed from receiving emails

• first_name - The first name associated with the email address

• middle_name - The middle name associated with the email address

• last_name - The last name associated with the email address

• preferred_name - The preferred name associated with the email address

• city - The city associated with the email address

• street_address - The street address associated with the email

• state_abbr - US 2 letter state abbreviation associated with the email address

• zip_code - US zip code associated with the email address

• custom_source - The custom source associated with the email address

• custom_score - The custom score associated with the email address

• custom_id - The custom id associated with the email address

actblue_donations

• entity_id - ActBlue Entity ID for the donation.

• order_number - ActBlue order number for the donation, consistent across recurring donations in the same sequence of donations.

• lineitem_id - ActBlue Line Item ID, unique to this particular donation

• paid_at - ISO 8601 timestamp recorded by ActBlue for when the donation occurred.

• recurring_period - Frequency of recurrence for recurring ActBlue donations. One of once, weekly, or monthly.

• amount - Dollar amount of the donation.

• donor_firstname - Donor first name

• donor_lastname - Donor last name

• donor_addr1 - Donor street address

• donor_city - Donor city

• donor_state - Donor state

• donor_zip - Donor postal code

• donor_phone - Donor phone number

• donor_email - Donor email

• donor_employer - Donor employer name

• donor_occupation - Donor occupation

• donor_employer_addr1 - Donor employer street address

• donor_employer_city - Donor employer city

• donor_employer_state - Donor employer state

• donor_employer_country - Donor employer country

• refcode_values - Array with any refcodes recorded for the donation

• refcode - Value for the refcode parameter for this donation. Also available in above array, but pulled out for convenience.

• token - Switchboard tracking token for this donation. Can be used to link donations back to Switchboard Broadcasts.

• committee_name - ActBlue committee name.

• contribution_form_name - Source ActBlue contribution form for the donation.

• form_managing_entity_name - Name of the ActBlue entity that created and manages the source form for this donation.

• form_managing_entity_committee_name - Name of the ActBlue committee that created and manages the source form for this donation.

• ab_test_name - AB test name, if any.

• ab_test_variation - AB test variant identifier.

• is_paypal - Whether this was a PayPal donation.

• is_mobile - Whether this was a mobile donation.

• is_express - Whether the donor is an ActBlue Express user.

• donor_is_eligible_for_express_lane - Whether the donor is eligible to donate through Express Lane.

• is_with_express_lane - Whether the contribution was made through ActblueExpress Lane.

• is_express_signup - Whether the donor chose to sign up for ActBlue express after making the contribution.

labels

• id - Unique identifier for the label.

• created_at - ISO 8601 timestamp for when the label was created.

• modified_at - ISO 8601 timestamp for when the label was last modified.

• archived_at - ISO 8601 timestamp for when the label was archived.

• name - Label name

phone_labels

• label_id - ID of the label applied to this phone - see labels

• phone_number - The phone number that the label was applied to.

• created_at - ISO 8601 timestamp for when the label was applied to the phone.

email_labels

• label_id - ID of the label applied to this email - see labels

• email_address - The email address that the label was applied to.

• created_at - ISO 8601 timestamp for when the label was applied to the email.

phone_opt_outs

• phone_number - The phone number that the label was applied to.

• created_at - ISO 8601 timestamp for when this phone opt-out was logged.

• opt_out_source - Where or how the phone was opted out.

  • CONTACT_REQUEST - Opt-out via keyword from a incoming text.

  • USER_LIST - Opt-outs via CSV list upload from Switchboard UI.

  • SB_USER - Manual opt-out by Switchboard user from the Inbox or All Phones pages.

  • NGPVAN - Opt-out synced via integration with NGPVAN.

  • ACTBLUE_DONATION - Opt-out synced via integration with ActBlue.

  • ADMIN_PANEL - Manual opt-out by Switchboard administrator or engineer.

    NOTE: Logging SB_USER opt-outs began in June 2025, before that any manual opt-outs in product were classified as CONTACT_REQUEST

saved_searches

• id - Unique identifier for the saved search.

• created_at - ISO 8601 timestamp for when the saved search was created.

• modified_at - ISO 8601 timestamp for when the saved search was last modified (such as a status update or name change).

• archived_at - ISO 8601 timestamp for when the saved search was archived.

• name - Name of the saved search.

• audience_type - Type of audience for the search, either phone or email.

• creator - Email of the original creator of the saved search.

• description - User-added description for the search, if any.

• last_refreshed_at - ISO 8601 timestamp for when the most recent evaluation of the saved search was initiated.

• num_contacts - Count of contacts in the latest evaluation of the search, if any.

saved_search_result_phones

NOTE: This model has all phones from the LATEST successful saved search evaluation. That means that rows CAN be deleted from this tables when you re-run a saved search. This may affect the way you sync this table, you may want to avoid syncing incrementally.

• saved_search_id - Identifier for the saved search that this phone maps to.

• phone_number - Phone number included in the saved search.

• created_at - ISO 8601 timestamp for when this saved search result was created.

saved_search_result_emails

NOTE: This model has all emails from the LATEST successful saved search evaluation. That means that rows CAN be deleted from this tables when you re-run a saved search. This may affect the way you sync this table, you may want to avoid syncing incrementally.

• saved_search_id - Identifier for the saved search that this email address maps to.

• email_address - Email address included in the saved search.

• created_at - ISO 8601 timestamp for when this saved search result was created.

charges_daily

• date_eastern - The date of the charges in Eastern timezone (YYYY-MM-DD format).

  • NOTE: This is currently specifically in "America/New_York" time to match the way that charges display in our Organization Settings -> Billing page, it is not yet set per account timezone.

• modified_at - ISO 8601 timestamp for when the record was last modified

• message_type - The type of message charged

  • sms: SMS message

  • mms: MMS message

• broadcast_id - The public ID of the broadcast associated with the charges (null for non-broadcast messages)

• description - Description of the charge (only populated when not associated with a broadcast, e.g., inbox or test messages)

• count_messages_charged - The number of messages charged for this day/type/broadcast combination

• count_segments_charged - The number of message segments charged. If message_type is mms, will match count_messages_charged

• count_messages_refunded - The number of messages refunded for this day/type/broadcast combination

• count_segments_refunded - The number of message segments refunded. If message_type is mms, will match count_messages_refunded

• amount_charges_gross - The gross amount charged (before refunds)

• amount_charges_refunded - The amount that has been refunded

• amount_charges_net - The net amount charged (gross minus refunded)

credits_daily

• payment_date - The date the credit was applied in UTC (YYYY-MM-DD format)

• credit_type - The type of credit applied

  • ACH Payment: Payment via ACH transfer

  • Wire Payment: Payment via wire transfer

  • Check Payment: Payment via check

  • Plastiq Payment: Payment via Plastiq

  • Stripe Payment: Payment via Stripe

  • Refund from Switchboard: Refund issued by Switchboard

  • Credit from Switchboard: Credit issued by Switchboard

  • Balance Withdrawal: Withdrawal from balance

  • Undelivered Messages: Credit for undelivered messages

  • Fractional Adjustment Credit: Fractional adjustment

• description - Additional description for the credit

• modified_at - ISO 8601 timestamp for when the record was last modified

• amount_credits - The total credit amount for this day/type/description combination