#Custom Lists
Custom Lists are tables of people or records in your BetterTickets account, keyed by one column (for example an email address). The API lets your server look up one row by key and add or update rows in batches of up to 500. New rows are what the list's automations pick up.
#Before you start
All three must be in place, or the call answers 403:
| Requirement | Error when missing |
|---|---|
| Custom Lists enabled on your account | 403 partner_lists_disabled |
| API Access turned on in the list's settings | 403 list_api_disabled |
The key has lists:read (lookups) or lists:write (upserts) | 403 insufficient_scope |
Ask your BetterTickets contact to enable Custom Lists and to add list scopes to your key. The list id is shown in the list's settings.
#Staging and Production
Test keys (btk_test_…) read and write the list's Staging rows. Live keys (btk_live_…) read and write Production rows. See Test vs Live.
#Looking up a row
curl -G https://app.bettertickets.com/api/partner/v1/lists/4001/rows \
--data-urlencode "key=fan@example.com" \
-H "Authorization: Bearer $BETTERTICKETS_API_KEY"URL-encode key (for example with encodeURIComponent, URLSearchParams or requests params). Unencoded, a + in an email address arrives as a space and the lookup misses.
{
"list_id": 4001,
"row": {
"row_key": "fan@example.com",
"added_at": 1795456800000,
"updated_at": 1795460400000,
"data": { "email": "fan@example.com", "tier": "VIP" }
}
}Only the columns the list exposes to the API are returned in data. 404 row_not_found is returned when there is no active row with that key. Full reference: Look up one list row.
#Adding or updating rows
curl -X POST https://app.bettertickets.com/api/partner/v1/lists/4001/rows \
-H "Authorization: Bearer $BETTERTICKETS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"rows":[{"email":"fan@example.com","first_name":"Sam","tier":"VIP"}]}'The call is an upsert by the list's key column:
- A new key adds a row; an existing key updates it.
- An update replaces the row's data. A column you leave out is stored empty, so send every column each time.
- Cells locked in BetterTickets keep their value. If the organizer edited and locked a cell, your value for that column is ignored until the lock is cleared.
- Only the list's columns are stored; other keys are ignored.
- The same key twice in one call: the later valid row wins and the earlier one is counted in
deduplicated. - Status column: if the list has one, a value set as inactive in the list's settings marks the row inactive (it stops driving automations); any other value makes it active again.
- Safe to repeat. Re-sending the same rows reports them as
unchanged.
Full reference: Add or update list rows.
#Value cleaning
Keys and values are cleaned by column type before they are stored or matched.
| Column type | Cleaning |
|---|---|
| Key (any type) | Trimmed and lower-cased; at most 255 characters after cleaning |
| Lower-cased; must be a valid email address | |
| Phone | Spaces, parentheses, dots and dashes removed; 7–15 digits with an optional leading + |
| Number | Must be a number |
| Date | 2027-01-21, 1/21/2027 or Jan 21, 2027 |
| Boolean | true/false, yes/no, y/n, 1/0 |
| Text | Leading and trailing spaces trimmed; blank counts as empty |
Every value is at most 2,000 characters. Required columns must have a value.
#Partial success
Bad rows do not fail the call. The response counts them in rejected and describes the first 50 in problems:
{
"list_id": 4001,
"received": 2,
"added": 1,
"updated": 0,
"unchanged": 0,
"rejected": 1,
"deduplicated": 0,
"problems": [{ "row": 2, "key": "kim@example.com", "reason": "wristband:required" }]
}row is the 1-based position in your rows array, or the row's own integer source_row if you send one. reason is one of invalid_row, missing_key, key_too_long, list_full, or <column>:<problem> where problem is required, too_long, not_a_value, invalid_email, invalid_phone, invalid_number, invalid_date or invalid_boolean. Other reasons may be added; treat unknown ones as a rejected row.
#Limits
| What | Limit |
|---|---|
Rows per POST | 500 (413 too_many_rows above) |
| Cell value | 2,000 characters |
| Row key after cleaning | 255 characters |
| Rows per list | 50,000 per data set (Staging and Production each); new keys beyond that are rejected as list_full |