Tài liệu API

Ứng viên

Ứng viên là thực thể cốt lõi. Mỗi CV được nhập, mỗi người ứng tuyển trên mỗi vị trí, mỗi bản ghi trong talent pool đều là một ứng viên.

Object Candidate

json

{
  "id": "c2a5e7b8-c8aa-4f50-9c3f-2f9a1d9e08aa",
  "code": "CAN-2026-0001",
  "full_name": "Nguyen Minh Tu",
  "email": "tu.nguyen@example.com",
  "phone": "+84912345678",
  "phone_normalized": "+84912345678",
  "current_position": "Senior Backend Engineer",
  "current_company": "Acme Corp",
  "years_of_experience": 6.5,
  "location_display": "Ho Chi Minh City, Vietnam",
  "vn_province_code": "HCM",
  "country_code": "VN",
  "source": "manual",
  "tags": ["backend", "senior"],
  "date_of_birth": "1994-08-21",
  "is_blacklisted": false,
  "duplicate_of_id": null,
  "created_at": "2026-05-12T08:23:11.043Z",
  "updated_at": "2026-05-12T08:23:11.043Z"
}

Trường chính

Trường	Kiểu	Mô tả
`id`	`uuid`	Primary key ổn định, đục.
`code`	`string`	Mã đọc được sinh tự động (ví dụ CAN-2026-0001). Duy nhất theo tenant theo năm.
`phone_normalized`	`string`	Số điện thoại sau khi chuẩn hóa E.164 (ví dụ `0912345678` → `+84912345678`). Tick Up dùng giá trị này để phát hiện trùng lặp.
`duplicate_of_id`	`uuid \| null`	Nếu được set, ứng viên này đã bị đánh dấu là trùng với một ứng viên khác (theo email hoặc số điện thoại đã chuẩn hóa). Dùng endpoint merge để gộp, hoặc bỏ qua đánh dấu.
`is_blacklisted`	`boolean`	Khi là true, ứng viên này không thể được thêm vào vị trí mới hoặc đăng ký drip sequence.
`source`	`string`	Cách ứng viên vào tenant của bạn. Giá trị thường gặp: `manual`, `cv_upload`, `referral`, `linkedin`, `topcv`, `itviec`, cộng thêm bất kỳ source tùy chỉnh nào bạn tạo.

Liệt kê ứng viên

GET /api/v1/candidates trả về danh sách phân trang của ứng viên trong tenant. Hỗ trợ page, page_size, tìm kiếm tự do search, cộng thêm filter cho source, tag (lặp lại để AND), và location (khớp với tên hiển thị, mã tỉnh VN, hoặc mã quốc gia).

curl "https://tickup-api.onrender.com/api/v1/candidates?page=1&page_size=20&source=cv_upload" \
  -H "Authorization: Bearer $TICKUP_TOKEN"

Tạo ứng viên

POST /api/v1/candidates tạo một ứng viên. Tick Up chuẩn hóa số điện thoại, chạy phát hiện trùng lặp theo email + điện thoại đã chuẩn hóa, và gán mã sinh tự động theo pattern CAN-YYYY-XXXX. Trường bắt buộc: full_name và source.

shell

curl -X POST https://tickup-api.onrender.com/api/v1/candidates \
  -H "Authorization: Bearer $TICKUP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Nguyen Minh Tu",
    "email": "tu.nguyen@example.com",
    "phone": "0912345678",
    "source": "manual",
    "current_position": "Senior Backend Engineer",
    "tags": ["backend", "senior"]
  }'

Lấy và cập nhật

GET /api/v1/candidates/{candidate_id} lấy một ứng viên theo UUID. PUT trên cùng đường dẫn cập nhật một phần — chỉ các trường có trong body bị thay đổi. Để đặt giá trị thành null, truyền null tường minh; bỏ trường khỏi body sẽ giữ nguyên giá trị.

Upload CV

Tick Up cung cấp hai đường upload CV. Cả hai đều phân tích file bất đồng bộ và gộp trùng theo email chính tắc (bỏ qua các inbox của job-board như itviec@itviec.com):

POST /api/v1/candidates/batch-upload — upload hàng loạt. Chấp nhận nhiều file trong một request multipart. Trả về batch_id để bạn poll qua GET /api/v1/candidates/batch-upload/{batch_id} xem trạng thái parse từng file.
POST /api/v1/candidates/{candidate_id}/upload-cv — đính kèm CV vào một ứng viên có sẵn (parse lại).