Upland Waterfall

Sync subscriber data and manage list membership in Upland Waterfall, an enterprise mobile messaging platform for SMS/MMS campaigns. Zeotap upserts subscriber metadata to Waterfall subscriber lists and manages audience membership through the Waterfall Subscriber API.

Prerequisites

An active Upland Waterfall account with API access enabled
A Waterfall API key (contact your Upland Waterfall account manager if you do not have one)
At least one subscriber list configured in your Waterfall account
Source data must include subscriber phone numbers (MSISDN)

Authentication

Upland Waterfall uses API Key authentication.

Log in to your Upland Waterfall account
Contact your Upland Waterfall account manager to obtain an API key if you do not already have one
In Zeotap, navigate to Destinations and click Add Destination
Select Upland Waterfall and enter your API key

Zeotap verifies your API key by calling the Waterfall authentication endpoint during the connection test.

Configuration

Field	Type	Required	Description
Default List ID	text	No	Default subscriber list ID applied to all syncs created with this destination. Can be overridden per sync in target settings.

Target Settings

Field	Type	Required	Description
Subscriber List	text	Conditional	The Waterfall subscriber list ID to sync data to. Required if no default list ID is set on the destination.

Supported Operations

Sync Modes

Mode	Supported	Description
Upsert	Yes	Create or update subscriber metadata on the configured list
Insert	—	Not supported — use upsert mode
Update	—	Not supported — use upsert mode
Mirror	—	Not supported for data syncs — use audience sync mirror mode instead

Audience Sync Modes

Mode	Supported	Description
Add	Yes	Add audience members to the subscriber list
Remove	Yes	Remove audience members from the subscriber list (blacklist)
Mirror	Yes	Full sync — adds new members and removes departed members
Upsert	—	Not applicable for audience syncs — use add mode

Features

Feature	Supported
Field Mapping	Yes
Schema Introspection	No

Required Mapping Fields

Field	Description
msisdn	Subscriber mobile phone number. All Waterfall subscribers must have an MSISDN. Map a column from your model containing phone numbers to this field.

Default Destination Fields

Field	Type
`msisdn`	string
`first_name`	string
`last_name`	string
`email`	string
`custom_field_1`	string
`custom_field_2`	string

Additional metadata fields beyond the defaults can be mapped using field mapping. Any non-reserved field is sent as subscriber metadata to Waterfall.

How It Works

Field Mapping — Zeotap maps your source model columns to Waterfall subscriber fields. The msisdn field is required for every row.
List Resolution — The target subscriber list is determined from the sync target settings, falling back to the destination-level default list ID.
API Dispatch — For each row in the batch, Zeotap calls the appropriate Waterfall v2 Subscriber API endpoint:
- Upsert mode: POST /v2/subscriber/upsertListsMetadata — creates or updates subscriber metadata on the list
- Add mode: POST /v2/subscriber/addToListTagKeyword — adds the subscriber to the list
- Remove mode: POST /v2/subscriber/addToBlacklist — blacklists the subscriber from the list
- Mirror mode: Uses upsert for new/existing members and blacklist for removed members (based on diff operations)
Error Handling — Failed rows are tracked individually with per-row error details. Transient errors (timeouts, 429 rate limits, 5xx server errors) are retried automatically up to 3 times with backoff.

Rate Limits

Upland Waterfall enforces rate limits on API requests. Zeotap processes rows sequentially to avoid overwhelming the API. If you encounter rate limit errors (HTTP 429), consider:

Reducing sync frequency
Splitting large audiences into smaller syncs
Contacting your Upland Waterfall account manager to increase your rate limit quota

Best Practices

Always map the MSISDN field — Every Waterfall subscriber requires a phone number. Ensure your source data includes valid phone numbers.
Use a default list ID on the destination to simplify sync configuration and avoid errors from missing list IDs.
Use mirror mode for audiences — Mirror mode keeps your Waterfall subscriber lists in sync with your Zeotap audiences, automatically adding and removing members.
Include metadata fields — Map additional subscriber attributes (name, email, custom fields) to enrich your Waterfall subscriber profiles for better segmentation and personalization.
Test with a small audience first — Verify field mapping and list configuration with a small test audience before syncing your full subscriber base.

Troubleshooting

Connection test fails with “authentication failed”

The API key is invalid or has been revoked. Contact your Upland Waterfall account manager to verify your API key is active and has the correct permissions.

”list_id is required” error

No subscriber list ID was configured. Either set a Default List ID on the destination or specify a Subscriber List in the sync target settings.

”msisdn is required” error on individual rows

Rows without a phone number mapped to the msisdn field are rejected. Ensure your source model has a phone number column and it is mapped to msisdn in the field mapping configuration.

Subscribers not appearing in Waterfall lists

After syncing, subscribers may take a few minutes to appear in the Waterfall UI. If subscribers are still missing after 15 minutes, check the sync run details in Zeotap for per-row errors and verify the list ID is correct.

Rate limit errors (HTTP 429)

Your account has exceeded the Waterfall API rate limit. Reduce sync frequency or contact your account manager to request a higher rate limit. Zeotap automatically retries rate-limited requests up to 3 times.

Removed audience members still receiving messages

The remove/mirror sync mode blacklists subscribers from the list, but previously scheduled messages may still be delivered. Allow time for Waterfall to process the blacklist update before expecting message delivery to stop.