POST
/listsPOST /lists
Create a list or a segment.
Request
curl -X POST 'https://api.sendheron.com/api/v1/lists' \
-H 'Authorization: Bearer <YOUR_API_KEY>' \
-H 'Content-Type: application/json'Required scopes
The key must carry these:
- contacts:write
Body parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | List name, unique within the workspace. |
| description | string | No | What the list is for. Shown in the dashboard only. |
| type | STATIC | DYNAMIC | Yes | STATIC: 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. |
| rules | object | No | 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 201 on success.
- 400
- The payload failed validation, or the request is not valid for the current state.
messagesays which kind of refusal it is, and for a payload that failed validation (validationFailed) thedescriptionnames 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 answersinvalidUUIDon every route. - 401
- Missing or invalid API key.
- 403
- Valid key, but it does not carry the required scope.
messageisapiKeys.insufficientScopesand thedescriptionnames 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.
messageistooManyRequests, and theRetry-Afterheader says how many seconds until the window rolls. - 400
lists.rulesRequiredForDynamic: a dynamic list withoutrules.- 400
lists.invalidRuleField,lists.invalidRuleOperator,lists.invalidRuleValue,lists.invalidRuleLogic,lists.invalidRuleFormatorlists.rulesTooDeeplyNested: a rule the segment query cannot apply, refused rather than stored.lists.invalidRuleOperator,lists.invalidRuleValueandlists.invalidRuleLogiccome with adescriptionsaying 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.