Skip to content

Search Contacts POST ​

Returns your account's contacts (Persons), paginated. Search by first name, last name, phone or email, and filter by tag.

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/Person/requestPerson

POST /Person/SearchPerson is an alias that behaves identically (kept for legacy integrations).

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 firstName, lastName, phone, email
tagstringOptionalReturn only contacts whose tags contains this exact value
pagenumberOptionalPage number, starting at 1 (default 1)
pageSizenumberOptionalItems per page, 1–100 (default 20) — any value outside this range is treated as 20

Response Description ​

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

Person ​

PropertyTypeDescription
personIdstringContact ID (UUID)
accountIdnumberYour account ID
firstNamestringFirst name
lastNamestringLast name
emailstringEmail (omitted when empty)
phonestringPhone number (omitted when empty)
companyNamestringCompany name (omitted when empty)
notestringNote (omitted when empty)
tagsstring[] | nullTags stored on the contact
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/Person/requestPerson' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "search": "somchai",
    "page": 1,
    "pageSize": 20
  }'
js
const res = await fetch('https://public-api.smsup-plus.com/Person/requestPerson', {
  method: 'POST',
  headers: { Authorization: 'Bearer <API_KEY>', 'Content-Type': 'application/json' },
  body: JSON.stringify({ search: 'somchai', page: 1, pageSize: 20 }),
})
console.log(await res.json())

Response Example ​

json
{
  "status": 200,
  "data": [
    {
      "personId": "3f8b2c1e-7a4d-4e9b-9c2f-1d5e6a7b8c90",
      "accountId": 1024,
      "firstName": "Somchai",
      "lastName": "Jaidee",
      "email": "somchai@example.com",
      "phone": "0812345678",
      "companyName": "Example Co., Ltd.",
      "tags": ["VIP"],
      "isDeleted": false,
      "createdBy": 2048,
      "createdAt": "2026-11-16T03:15:42.123Z",
      "updatedAt": "2026-11-16T03:15:42.123Z"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20,
  "totalPages": 1
}

Possible Errors ​

HTTPResponseCause
200{"status":500,"description":"Failed to query persons."}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 — characters such as + ( ) . * ? are special. Escape them with \ to match literally, e.g. send "\\+66" to search for +66.

INFO

tag filters on the tags field set by Add Contact / Update Contact only. Assigning a tag with /Tag/insertPersonTag does not change a contact's tags.