PATCH/lists/{id}

PATCH /lists/{id}

Rename a list, describe it, or change its rules or type.

View as Markdown

Request

curl -X PATCH 'https://api.sendheron.com/api/v1/lists/{id}' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json'

Required scopes

The key must carry these:

  • contacts:write

Path parameters

NameTypeRequiredDescription
iduuidYesList UUID.

Body parameters

NameTypeRequiredDescription
namestringNoNew name, unique within the workspace.
descriptionstringNoWhat the list is for. Shown in the dashboard only.
typeSTATIC | DYNAMICNoSTATIC: members are added and removed explicitly, and adding one fires the LIST_ADDED sequence trigger. DYNAMIC: a segment whose members are whoever matches rules when it is read; nothing is ever added to it, so LIST_ADDED never fires for it. Switching a dynamic list to static drops its rules and starts it empty; switching a static list to dynamic needs rules in the same request.
rulesobjectNoReplaces the rules of a dynamic list. Who a dynamic list contains, evaluated every time it is read. Required when type is DYNAMIC, cleared when it is STATIC. A group is {"type": "group", "logic": "AND" | "OR", "rules": [...]} whose rules are atomic rules {"type": "rule", "field": ..., "operator": ..., "value": ...} or nested groups, at most three levels deep. A bare array of atomic rules is read as an AND group. field is a contact column (email, firstName, lastName, status, source, createdAt or updatedAt), tags, or properties.<key> for a custom property; any other field is refused (400 lists.invalidRuleField). operator is one of EQUALS, NOT_EQUALS, CONTAINS, NOT_CONTAINS, STARTS_WITH, ENDS_WITH, GREATER_THAN, LESS_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN_OR_EQUAL, IS_SET, IS_NOT_SET, IN or NOT_IN, in that spelling (400 lists.invalidRuleOperator otherwise), and logic is AND or OR (400 lists.invalidRuleLogic). CONTAINS, NOT_CONTAINS, STARTS_WITH and ENDS_WITH match regardless of case; a contact column compares as its own type and a custom property as text. IS_SET and IS_NOT_SET take no value; IN and NOT_IN take a non-empty list, and every other operator one value, not a list (400 lists.invalidRuleValue otherwise). On status and source only EQUALS, NOT_EQUALS, IN, NOT_IN, IS_SET and IS_NOT_SET are accepted (400 lists.invalidRuleOperator), with the values that column holds: SUBSCRIBED, UNSUBSCRIBED, BOUNCED or COMPLAINED for status, and MANUAL, IMPORT, API, FORM or SYNC for source (400 lists.invalidRuleValue). On tags only IN and NOT_IN (tag names) and IS_SET and IS_NOT_SET (any tag at all) are accepted. Example: {"type": "group", "logic": "AND", "rules": [{"type": "rule", "field": "status", "operator": "EQUALS", "value": "SUBSCRIBED"}, {"type": "rule", "field": "tags", "operator": "IN", "value": ["customer"]}, {"type": "rule", "field": "properties.plan", "operator": "EQUALS", "value": "pro"}]}.

Responses

Returns 200 on success.

400
The payload failed validation, or the request is not valid for the current state. message says which kind of refusal it is, and for a payload that failed validation (validationFailed) the description names the field and says what was wrong with it in words, e.g. "domain: domain must be a bare hostname such as acme.com, with no scheme, path, or port". An id in the path that is not a UUID answers invalidUUID on every route.
401
Missing or invalid API key.
403
Valid key, but it does not carry the required scope. message is apiKeys.insufficientScopes and the description names both halves of the problem: "Missing required scope(s): X. This key holds: Y." Neither is a secret, since the required scopes are on this page and the held ones are your own credential, and a bare "Forbidden" costs a debugging pass to work out which of the two it was.
404
No such record in this workspace. An id belonging to a different workspace returns this too, never a 403, because the API will not confirm that a record exists outside the workspace your key was issued in. Read it as "not yours or not there" rather than as "definitely gone".
409
A duplicate, or an idempotency key reused with a different payload.
429
Either rate-limit ceiling was exceeded. message is tooManyRequests, and the Retry-After header says how many seconds until the window rolls.
400
lists.rulesRequiredForDynamic: a switch to dynamic without rules in the same request.
400
lists.invalidRuleField, lists.invalidRuleOperator, lists.invalidRuleValue, lists.invalidRuleLogic, lists.invalidRuleFormat or lists.rulesTooDeeplyNested: a rule the segment query cannot apply, refused rather than stored. lists.invalidRuleOperator, lists.invalidRuleValue and lists.invalidRuleLogic come with a description saying what is accepted.
409
A list with this name already exists in the workspace.

Rate limits

100/min per key, counted against the organization's WRITE ceiling (400/min). Both windows are one minute.