lists

Embed

<a href="https://hermeticor.com/docs/ref-lists"><img src="https://hermeticor.com/docs/_api/public/orgs/5fcd8b3c-a27c-4688-972f-de710125592f/spaces/caf5dc05-15f7-4e0c-bdb8-ab29ede6211e/pages/dea5db4d-524b-41d3-8271-fa7e50897c07/social-card.svg?v=3e7ae33eec8b" alt="lists" width="600" height="315"></a>

POSThttps://hermeticor.com/l/c/{*}

Confirm list double opt-in; idempotent

Parameters

*stringpathrequired

Code samples

cURL

curl -X POST "https://hermeticor.com/l/c/{*}"

TypeScript

Python

PHP

Ruby

Java

Responses

200 Default Response

"string"

4XX Default Response

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

detailsobject

5XX Default Response

Same as 4XX · POST /l/c/{*}

GEThttps://hermeticor.com/v1/list-folders

Parameters

limitintegerquery

Page size; omitted returns the whole list

cursorstringquery

Opaque: the nextCursor of the previous page

Code samples

cURL

curl -X GET "https://hermeticor.com/v1/list-folders" \
  -H "Authorization: Bearer $HERMETICOR_API_KEY"

TypeScript

Python

PHP

Ruby

Java

Responses

200 Default Response

Example

{
  "items": [
    {
      "id": "string",
      "name": "string",
      "parentId": "string",
      "listCount": 0,
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "nextCursor": "string"
}

Schema

itemsItemsItem159[]required

Show child parameters

idstringrequired

namestringrequired

parentIdstringrequired

listCountinteger

createdAtstringrequired

nextCursorstringrequired

4XX Default Response

Same as 4XX · POST /l/c/{*}

5XX Default Response

Same as 4XX · POST /l/c/{*}

POSThttps://hermeticor.com/v1/list-folders

Request body

application/json

namestringrequired

parentIdstring

{
  "name": "string",
  "parentId": "string"
}

Code samples

cURL

curl -X POST "https://hermeticor.com/v1/list-folders" \
  -H "Authorization: Bearer $HERMETICOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","parentId":"string"}'

TypeScript

Python

PHP

Ruby

Java

Responses

201 Default Response

Example

{
  "id": "string",
  "name": "string",
  "parentId": "string",
  "listCount": 0,
  "createdAt": "2024-01-01T00:00:00Z"
}

Schema

idstringrequired

namestringrequired

parentIdstringrequired

listCountinteger

createdAtstringrequired

4XX Default Response

Same as 4XX · POST /l/c/{*}

5XX Default Response

Same as 4XX · POST /l/c/{*}

GEThttps://hermeticor.com/v1/list-folders/{id}

Parameters

idstringpathrequired

Code samples

cURL

curl -X GET "https://hermeticor.com/v1/list-folders/{id}" \
  -H "Authorization: Bearer $HERMETICOR_API_KEY"

TypeScript

Python

PHP

Ruby

Java

Responses

200 Default Response

Same as 201 · POST /v1/list-folders

4XX Default Response

Same as 4XX · POST /l/c/{*}

5XX Default Response

Same as 4XX · POST /l/c/{*}

DELETEhttps://hermeticor.com/v1/list-folders/{id}

Delete a folder; its lists become unfiled

Parameters

idstringpathrequired

Code samples

cURL

curl -X DELETE "https://hermeticor.com/v1/list-folders/{id}" \
  -H "Authorization: Bearer $HERMETICOR_API_KEY"

TypeScript

Python

PHP

Ruby

Java

Responses

200 Default Response

Example

{
  "ok": true
}

Schema

okbooleanrequired

true

4XX Default Response

Same as 4XX · POST /l/c/{*}

5XX Default Response

Same as 4XX · POST /l/c/{*}

PATCHhttps://hermeticor.com/v1/list-folders/{id}

Parameters

idstringpathrequired

Request body

application/json

namestring

parentIdstring

{
  "name": "string",
  "parentId": "string"
}

Code samples

cURL

curl -X PATCH "https://hermeticor.com/v1/list-folders/{id}" \
  -H "Authorization: Bearer $HERMETICOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","parentId":"string"}'

TypeScript

Python

PHP

Ruby

Java

Responses

200 Default Response

Same as 201 · POST /v1/list-folders

4XX Default Response

Same as 4XX · POST /l/c/{*}

5XX Default Response

Same as 4XX · POST /l/c/{*}

POSThttps://hermeticor.com/v1/lists/{id}/members/batch

Upsert up to 500 members at once with status, tags and topic subscriptions; per-member errors are reported, the rest still apply

Parameters

idstringpathrequired

Request body

application/json

membersobject[]required

Show child parameters

emailstring

phonestring

externalIdstring

anonymousIdstring

standardobject

Show child parameters

firstNamestring

lastNamestring

timezonestring

localestring

countrystring

citystring

regionstring

lifecycleStagestring

ownerUserIdstring

attributesobject

statusstring

subscribed | unsubscribed | pending = subscribed

tagsstring[]

topicsobject[]

Show child parameters

idstringrequired

statusstringrequired

subscribed | unsubscribed

consentAssertionobject

Show child parameters

channelstringrequired

email | sms | whatsapp | push | postcard

purposestringrequired

marketing | prospecting | transactional | operational

sourceTextstringrequired

attestedBystringrequired

updateExistingboolean

= true

{
  "members": [
    {
      "email": "string",
      "phone": "string",
      "externalId": "string",
      "anonymousId": "string",
      "standard": {
        "firstName": "string",
        "lastName": "string",
        "timezone": "string",
        "locale": "string",
        "country": "string",
        "city": "string",
        "region": "string",
        "lifecycleStage": "string",
        "ownerUserId": "string"
      },
      "attributes": {},
      "status": "subscribed",
      "tags": [
        "string"
      ],
      "topics": [
        {
          "id": "string",
          "status": "subscribed"
        }
      ]
    }
  ],
  "consentAssertion": {
    "channel": "email",
    "purpose": "marketing",
    "sourceText": "string",
    "attestedBy": "string"
  },
  "updateExisting": true
}

Code samples

cURL

curl -X POST "https://hermeticor.com/v1/lists/{id}/members/batch" \
  -H "Authorization: Bearer $HERMETICOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"members":[{"email":"string","phone":"string","externalId":"string","anonymousId":"string","standard":{"firstName":"string","lastName":"string","timezone":"string","locale":"string","country":"string","city":"string","region":"string","lifecycleStage":"string","ownerUserId":"string"},"attributes":{},"status":"subscribed","tags":["string"],"topics":[{"id":"string","status":"subscribed"}]}],"consentAssertion":{"channel":"email","purpose":"marketing","sourceText":"string","attestedBy":"string"},"updateExisting":true}'

TypeScript

Python

PHP

Ruby

Java

Responses

200 Default Response

Example

{
  "created": 0,
  "updated": 0,
  "skipped": 0,
  "errors": [
    {
      "index": 0,
      "message": "string"
    }
  ]
}

Schema

createdintegerrequired

updatedintegerrequired

skippedintegerrequired

errorsErrorsItem3[]required

Show child parameters

indexintegerrequired

messagestringrequired

4XX Default Response

Same as 4XX · POST /l/c/{*}

5XX Default Response

Same as 4XX · POST /l/c/{*}

POSThttps://hermeticor.com/v1/lists/{id}/members/remove

Remove many members from the list in one call

Parameters

idstringpathrequired

Request body

application/json

profileIdsstring[]required

reasonstring

unsubscribed | cleaned | deleted | removed = removed

{
  "profileIds": [
    "string"
  ],
  "reason": "removed"
}

Code samples

cURL

curl -X POST "https://hermeticor.com/v1/lists/{id}/members/remove" \
  -H "Authorization: Bearer $HERMETICOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profileIds":["string"],"reason":"removed"}'

TypeScript

Python

PHP

Ruby

Java

Responses

200 Default Response

Example

{
  "changed": [
    "string"
  ]
}

Schema

changedstring[]required

4XX Default Response

Same as 4XX · POST /l/c/{*}

5XX Default Response

Same as 4XX · POST /l/c/{*}

POSThttps://hermeticor.com/v1/lists/{id}/members/clear

Remove every member (the list stays)

Parameters

idstringpathrequired

Code samples

cURL

curl -X POST "https://hermeticor.com/v1/lists/{id}/members/clear" \
  -H "Authorization: Bearer $HERMETICOR_API_KEY"

TypeScript

Python

PHP

Ruby

Java

Responses

200 Default Response

Same as 200 · POST /v1/lists/{id}/members/remove

4XX Default Response

Same as 4XX · POST /l/c/{*}

5XX Default Response

Same as 4XX · POST /l/c/{*}

POSThttps://hermeticor.com/v1/lists/{id}/members/move

Move people (everyone, or the given ones) from this list to another

Parameters

idstringpathrequired

Request body

application/json

toListIdstringrequired

profileIdsstring[]

{
  "toListId": "string",
  "profileIds": [
    "string"
  ]
}

Code samples

cURL

curl -X POST "https://hermeticor.com/v1/lists/{id}/members/move" \
  -H "Authorization: Bearer $HERMETICOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"toListId":"string","profileIds":["string"]}'

TypeScript

Python

PHP

Ruby

Java

Responses

200 Default Response

Same as 200 · POST /v1/lists/{id}/members/remove

4XX Default Response

Same as 4XX · POST /l/c/{*}

5XX Default Response

Same as 4XX · POST /l/c/{*}

Next part

Updated Nov 8, 2026

Was this page helpful?