Tick Up Developers

Data API

Cho coding agent, dashboard hay bảng tính của bạn đọc dữ liệu tuyển dụng của công ty — 7 bảng dữ liệu thô, bộ chỉ số y hệt màn Báo cáo, danh mục để gắn nhãn. Chỉ đọc, 18 tháng gần nhất.

Xác thực

Mọi request gửi khoá trong header Authorization: Bearer tk_live_… tới https://api.tickup.vn/api/v1/data. Khoá do admin công ty tạo trong Cài đặt → API & dữ liệu (xem Khoá API). Data API chỉ nhận khoá API — token đăng nhập của trình duyệt bị từ chối. Đọc khoá từ biến môi trường, không đặt vào URL hay code chạy trên trình duyệt.

curl -s "https://api.tickup.vn/api/v1/data/applications?page_size=100&include_demo=false" \
  -H "Authorization: Bearer $TICKUP_API_KEY"

Phạm vi dữ liệu

18 tháng gần nhất, tính theo trục thời gian riêng của từng bảng. from cũ hơn giới hạn được dời lên và meta.from_clamped = true.
Cùng một luật với màn Báo cáo và file Excel: /applications và các bảng gắn với hồ sơ ứng tuyển đã loại hồ sơ bị gỡ khỏi job, job đã xoá, ứng viên đã xoá và ứng viên đang bị đánh dấu trùng — đếm ra đúng số của màn Báo cáo.
Dòng không bị giấu mà được gắn cờ khi bạn có thể cần: is_demo (dữ liệu mẫu, mặc định có — đặt include_demo=false khi làm báo cáo thật), is_anonymized, duplicate_of_id (trên /candidates).
Có thông tin cá nhân ứng viên (email, số điện thoại). Ứng viên đã ẩn danh trả tên dạng [Đã xóa] và email/SĐT rỗng.
Không có: file CV và nội dung CV, nhận xét phỏng vấn, nhận xét trong phiếu đánh giá, nội dung email offer, ghi chú nội bộ, link họp.

Tham số chung

Các bảng dùng chung bộ tham số sau (job_id không áp dụng cho /candidates):

Trường	Kiểu	Mô tả
`page`	`integer`	Trang, bắt đầu từ 1.
`page_size`	`integer`	Số dòng mỗi trang, tối đa 100 (mặc định 50).
`from`	`date`	Ngày đầu (YYYY-MM-DD, giờ Việt Nam), tính cả ngày đó. Mặc định và sớm nhất: 18 tháng trước.
`to`	`date`	Ngày cuối, tính cả ngày đó. Mặc định: hôm nay.
`updated_since`	`datetime`	Chỉ trả dòng đã thay đổi từ thời điểm này (ISO-8601; không ghi múi giờ = UTC). Dùng để đồng bộ tăng dần.
`include_demo`	`boolean`	Có lấy dữ liệu mẫu hay không. Mặc định true để khớp màn Báo cáo.
`job_id`	`uuid`	Chỉ lấy dữ liệu của một job.

Mọi bảng trả về cùng một phong bì; thứ tự cố định (trục thời gian rồi id) nên lật trang không trùng không sót:

json

{
  "items": [ { "id": "…", "status": "active", "stage_type": "interview", "…": "…" } ],
  "total": 184,
  "page": 1,
  "page_size": 100,
  "total_pages": 2,
  "meta": {
    "from": "2025-03-14",
    "to": "2026-09-14",
    "from_clamped": false,
    "generated_at": "2026-09-14T03:00:00Z"
  }
}

Bảy bảng dữ liệu

Ý nghĩa từng trường nằm trong từ điển dữ liệu của file hướng dẫn; kiểu dữ liệu chính xác xem ở tài liệu đầy đủ.

GET/api/v1/data/candidatesCần xác thực

Hồ sơ ứng viên, theo ngày tạo. Có cả hồ sơ nghi trùng (xem duplicate_of_id) và hồ sơ đã ẩn danh.

GET/api/v1/data/applicationsCần xác thực

Mỗi dòng là một ứng viên ứng tuyển một job, theo ngày vào quy trình. Đúng các dòng màn Báo cáo đếm.

GET/api/v1/data/stage-transitionsCần xác thực

Lịch sử chuyển bước và đổi trạng thái của các hồ sơ trên, theo thời điểm đổi — kèm loại bước (stage_type) để so sánh giữa các job.

GET/api/v1/data/jobsCần xác thực

Tin tuyển dụng kèm các bước trong quy trình, theo ngày tạo.

GET/api/v1/data/interviewsCần xác thực

Lịch phỏng vấn, theo giờ phỏng vấn (hỏi được cả ngày tương lai).

GET/api/v1/data/evaluationsCần xác thực

Phiếu đánh giá (điểm, kết quả), theo lúc nộp phiếu.

GET/api/v1/data/offersCần xác thực

Thư mời nhận việc — mọi phiên bản; phiên bản hiện tại là version lớn nhất của mỗi hồ sơ ứng tuyển.

Chỉ số, danh mục và file hướng dẫn

GET/api/v1/data/metricsCần xác thực

Bộ chỉ số của màn Báo cáo cho một kỳ (from, to, job_id, department), tính bằng đúng hàm của màn hình. Nặng hơn các bảng: 20 lần/phút.

GET/api/v1/data/catalogCần xác thực

Danh mục để gắn nhãn dữ liệu thô: quy trình mẫu và các bước, nguồn riêng của công ty, lý do loại hồ sơ, thành viên (không có email), phòng ban.

GET/api/v1/data/agent-guideCông khai

File hướng dẫn cho coding agent (Markdown, tiếng Việt). Công khai — không chứa dữ liệu.

Giới hạn và lỗi

Mỗi khoá được 120 lần/phút và 5.000 lần/ngày cho các bảng và /catalog; /metrics 20 lần/phút, 500 lần/ngày. Vượt giới hạn trả 429 kèm header Retry-After (số giây) — hãy đợi đúng chừng đó rồi thử lại, và cache kết quả thay vì gọi liên tục. Lỗi trả dạng detail.code + detail.message:

Mã lỗi

Trường	Kiểu	Mô tả
`401 invalid_api_key`	`error`	Thiếu khoá, sai, hết hạn, đã thu hồi, hoặc gửi token đăng nhập thay vì khoá API.
`400 api_key_in_url`	`error`	Khoá nằm trong URL — khoá đã vào log máy chủ. Thu hồi và tạo khoá mới; chỉ gửi khoá trong header.
`422 invalid_range`	`error`	from lớn hơn to, hoặc tham số sai kiểu.
`429 rate_limited`	`error`	Vượt giới hạn — đợi theo Retry-After.

Tự kiểm chéo

Cùng from/to, số dòng /applications bằng số dòng sheet "Đơn ứng tuyển" trong file Excel xuất từ màn Báo cáo, và các con số /metrics bằng màn hình. Nếu lệch, kiểm tra múi giờ khi gom theo ngày và tham số include_demo.