BetterTicketsAPI Docs

#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:

RequirementError when missing
Custom Lists enabled on your account403 partner_lists_disabled
API Access turned on in the list's settings403 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

Shell
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.

JSON
{
  "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

Shell
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 typeCleaning
Key (any type)Trimmed and lower-cased; at most 255 characters after cleaning
EmailLower-cased; must be a valid email address
PhoneSpaces, parentheses, dots and dashes removed; 7–15 digits with an optional leading +
NumberMust be a number
Date2027-01-21, 1/21/2027 or Jan 21, 2027
Booleantrue/false, yes/no, y/n, 1/0
TextLeading 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:

JSON
{
  "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

WhatLimit
Rows per POST500 (413 too_many_rows above)
Cell value2,000 characters
Row key after cleaning255 characters
Rows per list50,000 per data set (Staging and Production each); new keys beyond that are rejected as list_full