# 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](https://docs.bettertickets.com/test-vs-live.md).

## Looking up a row

```bash
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](https://docs.bettertickets.com/reference/lookup-list-row.md).

## Adding or updating rows

```bash
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](https://docs.bettertickets.com/reference/upsert-list-rows.md).

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

```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

| 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` |
