BetterTicketsAPI Docs

Custom Lists

Add or update list rows

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

Adds or updates 1–500 rows by the list's key column. Test keys write the list's Staging rows, live keys Production rows. New rows are what the list's automations pick up.

Row rules:

  • Every row needs the key column. The key is trimmed and lower-cased; at most 255 characters after cleaning.
  • Only the list's columns are stored; other keys are ignored, except two reserved keys: if a row has a data key holding an object, the row's values are read from that object and its other top-level keys are dropped; an integer source_row replaces the row's position in problems[].row.
  • An update replaces the row's data: a column you leave out is stored empty. Send every column each time.
  • Cells the organizer edited and locked in BetterTickets keep their value; your value for that column is ignored until the lock is cleared.
  • Values are cleaned by column type: email (lower-cased, must be valid), phone (7–15 digits, optional leading +), number, date (2027-01-21, 1/21/2027, Jan 21, 2027), boolean (true/false, yes/no, y/n, 1/0), text. Each value at most 2,000 characters. Required columns must have a value.
  • The same key twice in one call: the later valid row wins (deduplicated); a later row that is rejected does not replace an earlier valid one.
  • If the list has a status column, 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.
  • A list holds at most 50,000 rows per data set (Staging and Production each); new keys beyond that are rejected as list_full.

Bad rows do not fail the call: they are counted in rejected and described (first 50) in problems. Safe to repeat.

#Request

Headers

NameTypeRequiredDescription
AuthorizationstringrequiredBearer <key>. A btk_live_… or btk_test_… key.
Content-Typestringrequiredapplication/json

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

#Request body

ListRowsUpsertRequest · application/json · required

Only rows is read; other top-level keys are ignored.

  • rowsarray of objectrequiredmin items 1max items 500

    1–500 rows. Each row is an object of column key → value and must contain the list's key column. Reserved keys: data (an object; when present, the values are read from it and the other top-level keys are dropped) and source_row (an integer that replaces the row's position in problems[].row). String values can be up to 2,000 characters; a longer value does not fail the request, and that row is rejected in problems as <column>:too_long.

    Child attributes
    • dataobject

      Optional. Column key → value. When present, values are read from here and the other top-level keys are dropped. Values inside must be strings, numbers, booleans or null.

    • source_rowinteger

      Optional. Replaces the row's position in problems[].row.

Example

JSON
{
  "rows": [
    {
      "email": "fan@example.com",
      "first_name": "Sam",
      "last_name": "Rivera",
      "tier": "VIP",
      "wristband": "W-1042"
    },
    {
      "email": "kim@example.com",
      "first_name": "Kim",
      "last_name": "Lee",
      "tier": "GA",
      "wristband": ""
    }
  ]
}

#Responses

StatusMeaningError codes
200Rows processed (some may be rejected; check rejected and problems).—
400Bad list id, or rows missing or empty. A bad key inside a row is not a 400: it is reported in the 200 (rejected, problems).invalid_list_id rows_required
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).list_not_found
405The HTTP method is not supported on this path.method_not_allowed
409The list has no valid columns yet.list_not_ready
413More than 500 rows.too_many_rows
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 Rows processed (some may be rejected; check rejected and problems).

Schema: ListRowsUpsertResponse

  • list_idintegerrequired
  • receivedintegerrequired

    Rows in your request.

  • addedintegerrequired

    New keys.

  • updatedintegerrequired

    Existing keys whose data (or status) changed.

  • unchangedintegerrequired

    Existing keys sent with identical data.

  • rejectedintegerrequired

    Rows not written. Details (first 50) in problems.

  • deduplicatedintegerrequired

    Valid rows dropped because a later valid row in the same request had the same key (the later one wins). A rejected row never replaces an earlier valid one.

  • problemsarray of ListRowProblemrequiredmax items 50
    Child attributes
    • rowintegerrequired

      1-based position in your rows, or the row's own integer source_row when it sends one.

    • keystring | nullrequired

      The cleaned row key, when it could be read.

    • reasonstringrequired

Example: result

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"
    }
  ]
}
400 Bad list id, or rows missing or empty. A bad key inside a row is not a 400: it is reported in the 200 (rejected, problems).

Schema: Error

Example: invalid_list_id

JSON
{
  "error": "invalid_list_id"
}

Example: rows_required

JSON
{
  "error": "rows_required",
  "message": "Send {\"rows\": [...]} with 1-500 rows."
}
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:write"
}

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

Schema: Error

Example: list_not_found

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

Schema: Error

Example: method_not_allowed

JSON
{
  "error": "method_not_allowed"
}
409 The list has no valid columns yet.

Schema: Error

Example: list_not_ready

JSON
{
  "error": "list_not_ready",
  "message": "This list has no valid columns yet."
}
413 More than 500 rows.

Schema: Error

Example: too_many_rows

JSON
{
  "error": "too_many_rows",
  "message": "Send at most 500 rows per call.",
  "max_rows": 500
}
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 -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","last_name":"Rivera","tier":"VIP","wristband":"W-1042"},{"email":"kim@example.com","first_name":"Kim","last_name":"Lee","tier":"GA","wristband":""}]}'