ค้นหารายชื่อผู้ติดต่อ POST
ดึงรายชื่อผู้ติดต่อ (Person) ของบัญชีคุณแบบแบ่งหน้า ค้นหาจากชื่อ นามสกุล เบอร์โทร หรืออีเมล และกรองตามแท็กได้
Authorization
ใช้ API Key (การยืนยันตัวตน) — ส่ง header Authorization: Bearer <API_KEY> (API Key ขึ้นต้นด้วย smsk_)
HTTP Request
POST https://public-api.smsup-plus.com/Person/requestPersonมีเส้นทางสำรอง POST /Person/SearchPerson ที่ทำงานเหมือนกันทุกอย่าง (รองรับระบบเดิม)
Content Type
application/json — body เป็น optional ถ้าไม่ส่งหรือ JSON ผิดรูปแบบ ระบบจะใช้ค่าเริ่มต้นทั้งหมด
Parameter Description
| Property | Type | Required | Description |
|---|---|---|---|
search | string | Optional | คำค้นแบบบางส่วน ไม่สนตัวพิมพ์เล็ก-ใหญ่ ค้นใน firstName, lastName, phone, email |
tag | string | Optional | คืนเฉพาะรายชื่อที่มีค่านี้อยู่ใน tags (ตรงทุกตัวอักษร) |
page | number | Optional | หน้าที่ต้องการ เริ่มที่ 1 (ค่าเริ่มต้น 1) |
pageSize | number | Optional | จำนวนต่อหน้า 1–100 (ค่าเริ่มต้น 20) — ค่านอกช่วงนี้จะถูกใช้เป็น 20 |
Response Description
| Property | Type | Description |
|---|---|---|
status | number | 200 เมื่อสำเร็จ |
data | array | null | รายการ Person เรียงจากสร้างล่าสุดก่อน — เป็น null เมื่อไม่พบข้อมูล |
total | number | จำนวนรายชื่อทั้งหมดที่ตรงเงื่อนไข |
page | number | หน้าปัจจุบัน |
pageSize | number | จำนวนต่อหน้าที่ระบบใช้จริง |
totalPages | number | จำนวนหน้าทั้งหมด |
Person
| Property | Type | Description |
|---|---|---|
personId | string | รหัสรายชื่อ (UUID) |
accountId | number | รหัสบัญชีของคุณ |
firstName | string | ชื่อ |
lastName | string | นามสกุล |
email | string | อีเมล (ไม่แสดงถ้าว่าง) |
phone | string | เบอร์โทร (ไม่แสดงถ้าว่าง) |
companyName | string | ชื่อบริษัท (ไม่แสดงถ้าว่าง) |
note | string | หมายเหตุ (ไม่แสดงถ้าว่าง) |
tags | string[] | null | รายการแท็กที่เก็บไว้กับรายชื่อ |
isDeleted | boolean | false เสมอในผลลัพธ์นี้ |
createdBy | number | รหัสผู้ใช้ที่สร้าง |
createdAt | string | เวลาสร้าง (ISO 8601) |
updatedAt | string | เวลาแก้ไขล่าสุด (ISO 8601) |
ตัวอย่าง Request
curl -X POST 'https://public-api.smsup-plus.com/Person/requestPerson' \
-H 'Authorization: Bearer <API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
"search": "สมชาย",
"page": 1,
"pageSize": 20
}'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: 'สมชาย', page: 1, pageSize: 20 }),
})
console.log(await res.json())ตัวอย่าง Response
{
"status": 200,
"data": [
{
"personId": "3f8b2c1e-7a4d-4e9b-9c2f-1d5e6a7b8c90",
"accountId": 1024,
"firstName": "สมชาย",
"lastName": "ใจดี",
"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
}Error ที่อาจเจอ
| HTTP | Response | สาเหตุ |
|---|---|---|
| 200 | {"status":500,"description":"Failed to query persons."} | ค้นหาไม่สำเร็จ เช่น search เป็นรูปแบบ regex ที่ไม่ถูกต้อง |
| 401 | {"error":"invalid api key"} | API Key ไม่ถูกต้อง — ดู Error |
WARNING
เมื่อผ่านการยืนยันตัวตนแล้ว endpoint นี้ตอบ HTTP 200 เสมอ ให้ตรวจผลจากฟิลด์ status ใน body
TIP
search ถูกตีความเป็น regular expression — อักขระพิเศษอย่าง + ( ) . * ? มีความหมายพิเศษ ถ้าต้องการค้นตามตัวอักษร ให้ใส่ \ นำหน้า เช่น ค้นเบอร์ +66 ให้ส่ง "\\+66"
INFO
tag กรองจากฟิลด์ tags ที่ส่งตอนเพิ่ม/แก้ไขรายชื่อ เท่านั้น — การผูกแท็กผ่าน /Tag/insertPersonTag ไม่ได้เปลี่ยนค่า tags ของรายชื่อ
