Skip to content

List Tags POST ​

Returns your account's tags (contact groups), paginated, with optional search by tag name.

Authorization ​

API Key (Authentication) — send the header Authorization: Bearer <API_KEY> (API keys start with smsk_)

HTTP Request ​

http
POST https://public-api.smsup-plus.com/Tag/requestTag

Content Type ​

application/json — the body is optional; if it is missing or not valid JSON, all defaults apply

Parameter Description ​

PropertyTypeRequiredDescription
searchstringOptionalCase-insensitive partial match on the tag name
pagenumberOptionalPage number, starting at 1 (default 1)
pageSizenumberOptionalItems per page, 1–100 (default 50) — 101–200 is treated as 20; any other out-of-range value as 50

Response Description ​

PropertyTypeDescription
statusnumber200 on success
dataarray | nullList of Tag, newest first — null when nothing matches
totalnumberTotal number of matching tags
pagenumberCurrent page
pageSizenumberPage size actually applied
totalPagesnumberTotal number of pages

Tag ​

PropertyTypeDescription
tagIdstringTag ID (UUID)
accountIdnumberYour account ID
namestringTag name
isDeletedbooleanAlways false in this result
createdBynumberID of the user who created it
createdAtstringCreation time (ISO 8601)
updatedAtstringLast update time (ISO 8601)

Request Example ​

bash
curl -X POST 'https://public-api.smsup-plus.com/Tag/requestTag' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "search": "vip",
    "page": 1,
    "pageSize": 50
  }'
js
const res = await fetch('https://public-api.smsup-plus.com/Tag/requestTag', {
  method: 'POST',
  headers: { Authorization: 'Bearer <API_KEY>', 'Content-Type': 'application/json' },
  body: JSON.stringify({ search: 'vip', page: 1, pageSize: 50 }),
})
console.log(await res.json())

Response Example ​

json
{
  "status": 200,
  "data": [
    {
      "tagId": "a1c2e3f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
      "accountId": 1024,
      "name": "VIP",
      "isDeleted": false,
      "createdBy": 2048,
      "createdAt": "2026-11-16T03:10:00.000Z",
      "updatedAt": "2026-11-16T03:10:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 50,
  "totalPages": 1
}

Possible Errors ​

HTTPResponseCause
200{"status":500,"description":"Failed to query tags."}Query failed, e.g. search is an invalid regular expression
401{"error":"invalid api key"}Invalid API key — see Errors

WARNING

Once authenticated, this endpoint always answers HTTP 200. Check the status field in the body.

TIP

search is interpreted as a regular expression — escape special characters such as + ( ) . * ? with \ to match them literally.