BetterTicketsAPI Docs

Custom Lists

Look up one list row by key

GET/lists/{id}/rows
Scope
lists:read
Base URL
https://app.bettertickets.com/api/partner/v1
Auth
Bearer API key

Finds the row whose key column equals key. Returns only the columns the list exposes to the API. Test keys read the list's Staging rows, live keys Production rows.

404 row_not_found also when the row was removed or is inactive, and for Production reads while the list's Production switch is off.

Key cleaning. key is cleaned the same way imported keys are, by the key column's type:

Key column typeCleaning
AnyTrimmed and lower-cased
EmailMust be a valid email address
PhoneSpaces, parentheses, dots and dashes removed; 7–15 digits with an optional leading + must remain ((555) 010-1234 finds 5550101234)
Date2027-01-21, 1/21/2027 or Jan 21, 2027

A missing or blank key, or one over 2,000 characters, gets 400 invalid_key "Pass ?key=…". A key that does not fit the column type, or is over 255 characters after cleaning, gets 400 invalid_key "The key does not match the type of the list key column."

#Request

Headers

NameTypeRequiredDescription
AuthorizationstringrequiredBearer <key>. A btk_live_… or btk_test_… key.

Path parameters

NameTypeRequiredDescription
idintegerrequiredCustom List id (shown in the list's settings). Send plain digits. Other numeric forms, such as 1e1 or 0x10, may be read as a different list id, so build the path only from the id as shown. (min 1) Example: 4001

Query parameters

NameTypeRequiredDescription
keystringrequiredValue of the list's key column. URL-encode it (for example with encodeURIComponent, URLSearchParams or requests params), so + and @ arrive intact. Cleaned before matching (see the operation description). (min length 1, max length 2000) Example: fan@example.com

#Responses

StatusMeaningError codes
200The row.—
400Bad list id or key.invalid_list_id invalid_key
401No key, or the key was checked and is unknown, revoked, expired or has the wrong prefix. The same invalid_api_key is returned for every kind of bad key. Do not retry it. A temporary problem checking the key answers 503 auth_unavailable instead. Repeated requests with a missing or invalid key from one IP address are answered 429 partner_rate_limited instead of 401.missing_api_key invalid_api_key
403The key lacks the required scope, API access or Custom Lists is off for the account, or API Access is off for this list.insufficient_scope partner_api_disabled partner_lists_disabled list_api_disabled
404No such list on your account (or it is archived), or no active row with that key.list_not_found row_not_found
405The HTTP method is not supported on this path.method_not_allowed
429Too many requests from this key or from your IP address, or repeated requests with a missing or invalid key from one IP address (answered 429 instead of 401). Wait Retry-After seconds. See Rate Limits.partner_rate_limited
502upstream_error: BetterTickets could not complete the call; retry with backoff and a small cap on attempts. request_refused: the call was refused for an unlisted reason; do not retry the same request, and contact BetterTickets if it persists. request_refused can also arrive with a 4xx status; branch on error, not only on the status.upstream_error request_refused
503BetterTickets could not check the key (auth_unavailable) or confirm the account's settings (FEATURE_GATE_UNAVAILABLE) for a moment. Safe to retry after Retry-After seconds; if the header is missing, wait 5 seconds. Retrying auth_unavailable faster than Retry-After gets 429 partner_rate_limited. On Custom Lists calls, FEATURE_GATE_UNAVAILABLE can also arrive as a bare { "error": "FEATURE_GATE_UNAVAILABLE" } with no Retry-After, retryable or retry_after_seconds; wait 5 seconds before retrying.auth_unavailable FEATURE_GATE_UNAVAILABLE

200 The row.

Schema: ListRowLookupResponse

  • list_idintegerrequired
  • rowobjectrequired
    Child attributes
    • row_keystringrequired

      The cleaned key (trimmed, lower-cased).

    • added_atinteger (int64)required

      When the row first arrived, epoch milliseconds. Never reset by later writes.

    • updated_atinteger (int64)required

      Last change, epoch milliseconds.

    • dataobjectrequired

      Only the columns the list exposes to the API (chosen in the list's settings).

Example: row

JSON
{
  "list_id": 4001,
  "row": {
    "row_key": "fan@example.com",
    "added_at": 1795456800000,
    "updated_at": 1795460400000,
    "data": {
      "email": "fan@example.com",
      "tier": "VIP"
    }
  }
}
400 Bad list id or key.

Schema: Error

Example: invalid_list_id

JSON
{
  "error": "invalid_list_id"
}

Example: missing_key — No key, a blank key, or a key over 2,000 characters.

JSON
{
  "error": "invalid_key",
  "message": "Pass ?key=<value of the list key column>."
}

Example: invalid_key — The key does not fit the key column type, or is over 255 characters after cleaning.

JSON
{
  "error": "invalid_key",
  "message": "The key does not match the type of the list key column."
}
401 No key, or the key was checked and is unknown, revoked, expired or has the wrong prefix. The same invalid_api_key is returned for every kind of bad key. Do not retry it. A temporary problem checking the key answers 503 auth_unavailable instead. Repeated requests with a missing or invalid key from one IP address are answered 429 partner_rate_limited instead of 401.

Schema: Error

Example: missing_api_key

JSON
{
  "error": "missing_api_key",
  "message": "Authorization: Bearer btk_… required"
}

Example: invalid_api_key

JSON
{
  "error": "invalid_api_key"
}
403 The key lacks the required scope, API access or Custom Lists is off for the account, or API Access is off for this list.

Schema: Error

Example: insufficient_scope

JSON
{
  "error": "insufficient_scope",
  "required": "lists:read"
}

Example: partner_api_disabled

JSON
{
  "error": "partner_api_disabled"
}

Example: partner_lists_disabled

JSON
{
  "error": "partner_lists_disabled",
  "message": "Custom Lists is not enabled for this account."
}

Example: list_api_disabled

JSON
{
  "error": "list_api_disabled",
  "message": "API access is turned off for this list. Turn it on in the list settings."
}
404 No such list on your account (or it is archived), or no active row with that key.

Schema: Error

Example: list_not_found

JSON
{
  "error": "list_not_found"
}

Example: row_not_found

JSON
{
  "error": "row_not_found"
}
405 The HTTP method is not supported on this path.

Schema: Error

Example: method_not_allowed

JSON
{
  "error": "method_not_allowed"
}
429 Too many requests from this key or from your IP address, or repeated requests with a missing or invalid key from one IP address (answered 429 instead of 401). Wait Retry-After seconds. See Rate Limits.

Headers

NameTypeDescription
Retry-AfterintegerSeconds to wait before retrying (at least 1).

Schema: Error

Example: partner_rate_limited

JSON
{
  "error": "partner_rate_limited",
  "message": "Too many Partner API requests. Slow down and retry after Retry-After seconds.",
  "retry_after_seconds": 42
}
502 upstream_error: BetterTickets could not complete the call; retry with backoff and a small cap on attempts. request_refused: the call was refused for an unlisted reason; do not retry the same request, and contact BetterTickets if it persists. request_refused can also arrive with a 4xx status; branch on error, not only on the status.

Schema: Error

Example: upstream_error

JSON
{
  "error": "upstream_error"
}

Example: request_refused

JSON
{
  "error": "request_refused"
}
503 BetterTickets could not check the key (auth_unavailable) or confirm the account's settings (FEATURE_GATE_UNAVAILABLE) for a moment. Safe to retry after Retry-After seconds; if the header is missing, wait 5 seconds. Retrying auth_unavailable faster than Retry-After gets 429 partner_rate_limited. On Custom Lists calls, FEATURE_GATE_UNAVAILABLE can also arrive as a bare { "error": "FEATURE_GATE_UNAVAILABLE" } with no Retry-After, retryable or retry_after_seconds; wait 5 seconds before retrying.

Headers

NameTypeDescription
Retry-AfterintegerSeconds to wait before retrying.

Schema: Error

Example: auth_unavailable

JSON
{
  "error": "auth_unavailable",
  "message": "API key check is temporarily unavailable. Retry after Retry-After seconds.",
  "retryable": true,
  "retry_after_seconds": 5
}

Example: FEATURE_GATE_UNAVAILABLE

JSON
{
  "error": "FEATURE_GATE_UNAVAILABLE",
  "retryable": true,
  "retry_after_seconds": 5
}

Example: FEATURE_GATE_UNAVAILABLE_bare

JSON
{
  "error": "FEATURE_GATE_UNAVAILABLE"
}

#Code samples

Set BETTERTICKETS_API_KEY on your server. Never send a key from a browser.

cURL
curl "https://app.bettertickets.com/api/partner/v1/lists/4001/rows?key=fan%40example.com" \
  -H "Authorization: Bearer $BETTERTICKETS_API_KEY"