Khái niệm cốt lõi

Phân trang

Endpoint dạng list trả về phong bì phân trang. Trang đánh số từ 1; page size mặc định là 20, có giới hạn theo từng endpoint.

Query parameter

Trường	Kiểu	Mô tả
`page`	`integer`	Số trang đánh từ 1. Mặc định: 1.
`page_size`	`integer`	Số bản ghi mỗi trang. Mặc định: 20. Giới hạn thay đổi theo endpoint, thường là 100.
`search`	`string`	Tìm kiếm văn bản tự do (tùy chọn). Mỗi endpoint list tìm trên các trường hữu ích nhất (tên, email, mã).

Shape phản hồi

json

{
  "total": 437,
  "page": 1,
  "page_size": 20,
  "items": [
    {
      "id": "c2a5e7b8-...-3f9a",
      "code": "CAN-2026-0001",
      "full_name": "Nguyen Minh Tu",
      "email": "tu.nguyen@example.com",
      "created_at": "2026-05-12T08:23:11.043Z"
    }
  ]
}

total — tổng số bản ghi qua tất cả các trang, sau khi áp filter và tenancy.
page — trang hiện tại (đánh từ 1).
page_size — có bao nhiêu mục trong mảng items của trang này.
items — bản ghi của trang hiện tại. Shape tùy theo tài nguyên.

Trang cuối có thể ít hơn page_size. Bạn biết đã hết khi page * page_size >= total.

Duyệt toàn bộ collection

Đối với back-fill một lần, pattern an toàn nhất là duyệt từng trang tuần tự:

async function* listAllCandidates(token) {
  let page = 1;
  const page_size = 100;
  while (true) {
    const res = await fetch(
      `https://tickup-api.onrender.com/api/v1/candidates?page=${page}&page_size=${page_size}`,
      { headers: { Authorization: `Bearer ${token}` } },
    );
    if (!res.ok) throw new Error("List failed");
    const { items, total, page_size: ps } = await res.json();
    for (const c of items) yield c;
    if (page * ps >= total) return;
    page += 1;
  }
}

for await (const candidate of listAllCandidates(token)) {
  console.log(candidate.code, candidate.full_name);
}

Sắp xếp ổn định

Endpoint list mặc định sắp theo created_at giảm dần. Nếu có bản ghi mới được tạo trong khi bạn duyệt qua các trang, bạn có thể thấy một bản ghi nhiều lần hoặc bỏ sót một cái. Để có snapshot thực sự, hoặc tạm ngưng write, hoặc dùng bộ lọc cursor rõ ràng:

http

GET /api/v1/candidates?page=1&page_size=100&created_before=2026-05-13T00:00:00Z

Mỗi endpoint mô tả các tham số filter mà nó hỗ trợ trong tài liệu API đầy đủ.

Tìm kiếm & filter

Hầu hết endpoint list chấp nhận query parameter search, cộng với các filter theo tài nguyên như job_id, stage, source, hoặc location. Xem trang của từng tài nguyên để biết shape filter đầy đủ: