Tìm và làm giàu dữ liệu khách hàng tiềm năng từ Claude Code

API people của Firecrawl Alexandria cho phép agent lập trình của bạn tìm và làm giàu thông tin về người chỉ với một khóa Firecrawl duy nhất. Bạn khám phá công cụ miễn phí bằng v2/search, liệt kê ứng viên bằng Apollo people/search với chi phí 0 credit, tiết lộ một người bằng Apollo people/match với 30 credit, hoặc làm giàu một email đã biết bằng People Data Labs person/enrich với 60 credit. Tất cả các lệnh gọi đều đi qua POST /v2/scrape.

Dùng thử Apidog ngay hôm nay

Mỗi bước dưới đây đều xuất hiện hai lần: một prompt cho Claude Code (hoặc Codex) và lệnh curl thô, để bạn có thể viết script mà không cần agent.

Firecrawl Alexandria people API là gì

Alexandria là thư viện nhà cung cấp dữ liệu bên thứ ba của Firecrawl, truy cập được bằng chính API key bạn vẫn dùng để scrape. Theo tài liệu Alexandria, bạn khám phá một công cụ, xem đầu vào và giá của nó, rồi chạy bằng scrape. Khám phá miễn phí; thực thi tốn đúng số credit được ghi trên công cụ.

Danh mục People có 12 nhà cung cấp. Hai trong số đó bao phủ phần lớn công việc tìm kiếm khách hàng tiềm năng:

Giá là mức hiển thị bên cạnh nút Run trên trang Apollo và trang People Data Labs vào ngày 4 tháng 11 năm 2026. Trang Apollo cũng ghi rõ một lần people/match không khớp "không trả về người nào và không bị tính phí."

Một lần tra cứu người tốn bao nhiêu đô

Giá trị của một credit phụ thuộc vào gói của bạn. Theo trang giá Firecrawl, Hobby là 19 USD một tháng cho 5.000 credit và Standard là 99 USD một tháng cho 100.000 credit, cả hai đều thanh toán theo tháng.

Phép tính: $19 / 5.000 = $0.0038 mỗi credit, và $99 / 100.000 = $0.00099. Tìm kiếm 100 bản xem trước rồi tiết lộ 20 người tốt nhất tốn 600 credit — nằm gọn trong 1.000 credit mỗi tháng của gói Free. People Data Labs còn giới hạn bạn ở 50.000 lệnh gọi API mỗi năm cho mỗi tổ chức, dùng chung cho cả endpoint person và company, kể cả các lần thử lại.

Bước 1: Kết nối Claude Code với Firecrawl

Cách nhanh nhất là trình cài đặt agent của Firecrawl. Nó thêm các skill Firecrawl vào mọi agent lập trình mà nó phát hiện và đăng nhập giúp bạn qua trình duyệt:

npx -y firecrawl-cli@latest init --all --browser

Khởi động lại agent của bạn sau đó. Nếu cài thủ công, đó là npm install -g firecrawl-cli và firecrawl login. Hướng dẫn Firecrawl CLI của chúng tôi đề cập cả hai cách, còn bài hướng dẫn Firecrawl MCP đề cập MCP server — thứ cung cấp cùng vòng lặp đó dưới dạng firecrawl_search, firecrawl_find_tools và firecrawl_scrape.

Với các ví dụ curl bên dưới, hãy export khóa của bạn một lần duy nhất:

export FIRECRAWL_API_KEY="fc-..."   # never commit this

Bước 2: Khám phá các công cụ people miễn phí

Hãy hỏi agent của bạn trước, vì khám phá không tốn gì:

Use Firecrawl Alexandria to find tools that search people by job title and
company, and tools that enrich a person from an email. Inspect Apollo and
People Data Labs with find-tools and show me each capability's inputs and
credit price before you run anything.

Về bản chất, đó là một tìm kiếm với sources đặt thành ["alexandria"]. Bỏ "web" sẽ giữ cho nó miễn phí, vì kết quả web bị tính phí:

curl https://api.firecrawl.dev/v2/search \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "find people by job title and company", "sources": ["alexandria"], "limit": 5}'

Phản hồi liệt kê các tools đã được xếp hạng, mỗi cái kèm nhà cung cấp, khả năng và mô tả. Để đọc đầu vào và giá, agent chạy find-tools:

firecrawl find-tools --options '{"providers":["apollo","people-data-labs"],"level":"tools","expand":["options","response"]}' --include-costs

Bước 3: Tìm ứng viên trên Apollo với 0 credit

Trang Apollo khuyên agent luôn bắt đầu từ đây: miễn phí, và cho bạn thấy ai tồn tại trước khi tiêu bất kỳ credit nào.

Run Apollo people/search through Firecrawl Alexandria for "VP of Sales" and
"Head of Revenue" at stripe.com and linear.app, 25 per page. Show name,
title, company and has_email. Don't reveal anyone yet.

Lệnh gọi thô:

curl https://api.firecrawl.dev/v2/scrape \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "alexandria": {
      "provider": "apollo",
      "capability": "people/search",
      "options": {
        "person_titles": ["VP of Sales", "Head of Revenue"],
        "q_organization_domains_list": ["stripe.com", "linear.app"],
        "page": 1,
        "per_page": 25
      }
    }
  }'

Mỗi bản xem trước mang một họ bị che và một id Apollo — đầu vào đáng tin cậy nhất cho bước tiếp theo.

Bước 4: Tiết lộ một người bằng people/match

Giờ hãy chỉ trả tiền cho những người thực sự đáng liên hệ, với 30 credit mỗi lần match:

For the 3 previews with has_email true, run Apollo people/match with their
id. Don't set reveal_personal_emails or reveal_phone_number.

curl https://api.firecrawl.dev/v2/scrape \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alexandria": {"provider": "apollo", "capability": "people/match", "options": {"id": "<apollo_id>"}}}'

Hãy để hai cờ reveal ở trạng thái tắt trừ khi bạn thực sự cần. Trang Apollo nói rõ email cá nhân "bị tính thêm phí" và số điện thoại thì "đắt hơn đáng kể so với mức match cơ bản."

Bước 5: Làm giàu một email đã biết bằng People Data Labs

Khi bạn đã có sẵn một email — chẳng hạn từ một lượt đăng ký inbound — person/enrich trả về hồ sơ đầy đủ hơn: email công việc, chức danh, công ty, URL LinkedIn, kinh nghiệm và kỹ năng.

Enrich jane@example.com with People Data Labs person/enrich through
Firecrawl Alexandria. Set min_likelihood to 6 so a weak match comes back
as a 404 instead of a wrong record.

curl https://api.firecrawl.dev/v2/scrape \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alexandria": {"provider": "people-data-labs", "capability": "person/enrich", "options": {"email": "jane@example.com", "min_likelihood": 6}}}'

min_likelihood chạy từ 1 đến 10 với mặc định là 2. Trang nhà cung cấp nói rõ sự đánh đổi: một lỗi 404 "ở đây là miễn phí, còn một bản ghi sai thì không." Hãy nâng giá trị này lên trước khi bạn lặp qua một danh sách.

Xử lý THIRD_PARTY_DATA_TERMS_REQUIRED

Lệnh gọi trả phí đầu tiên của bạn tới một nhà cung cấp có thể thất bại với THIRD_PARTY_DATA_TERMS_REQUIRED. Theo tài liệu, lỗi này kèm theo một requiresAction.url, và một admin của tổ chức phải mở liên kết đó, chấp nhận điều khoản của nhà cung cấp trước khi bất kỳ lệnh gọi nào được thực hiện.

Đừng để agent tự bấm qua. Tài liệu nêu rõ agent cần sự cho phép rõ ràng từ người dùng trước khi chấp nhận điều khoản — vốn quy định cách bạn được phép sử dụng dữ liệu cá nhân. Thêm một dòng vào CLAUDE.md của bạn: "Nếu một lệnh gọi trả về THIRD_PARTY_DATA_TERMS_REQUIRED, hãy dừng lại và hiển thị cho tôi requiresAction.url."

Đọc payload alexandria[].data

Kết quả trả về trong một mảng alexandria, mỗi lệnh gọi công cụ một phần tử, với payload của nhà cung cấp nằm dưới data. HTTP thô bọc toàn bộ kết quả SDK trong một data ở cấp cao nhất, nên trong phản hồi curl, kết quả match của Apollo nằm tại data.alexandria[0].data.person:

curl -s https://api.firecrawl.dev/v2/scrape ... | jq '.data.alexandria[0].data.person | {name, title, email, linkedin_url}'

Hai bước kiểm tra giúp giữ các dòng lỗi ra khỏi CRM của bạn:

1. Kiểm tra lỗi ở từng kết quả trước khi đọc data. Tài liệu nói rõ điều này: một lệnh gọi đơn lẻ có thể thất bại trong khi yêu cầu HTTP vẫn thành công.
2. Coi các email giữ chỗ như là thiếu. Apollo lưu ý rằng một email chưa được tiết lộ có thể trả về đúng nguyên văn email_not_unlocked@domain.com, ngay cả khi email_status báo là đã xác minh.

Với People Data Labs, thông tin về người nằm dưới data bên trong kết quả, cạnh status và likelihood của envelope.

Gửi phản hồi và nhận lại một credit

Alexandria hoàn tiền cho bạn khi gửi phản hồi. Mỗi lần gửi hoàn lại 1 credit cho bất kỳ mức đánh giá nào, giới hạn mỗi ngày UTC là 10 credit cho mỗi website và 100 cho mỗi team. Bạn có 20 phút kể từ lệnh gọi Alexandria gần nhất của team mình; sau đó bạn sẽ nhận FEEDBACK_WINDOW_EXPIRED.

Từ CLI, chạy firecrawl alexandria feedback (xem --help để biết các tùy chọn). Qua MCP, agent gọi firecrawl_feedback với endpoint: "alexandria". Một dòng prompt cũng hiệu quả: "Nếu một kết quả trông sai hoặc trống, hãy gửi phản hồi Alexandria mô tả điều đó."

Để Claude Code giám sát các lệnh gọi này bằng Apidog CLI

Khi script của bạn phụ thuộc vào việc people/search trả về một id mà people/match chấp nhận, một trường bị đổi tên sẽ phá hỏng nó một cách âm thầm. Agent của bạn có thể biến các lệnh gọi trong hướng dẫn này thành một kịch bản regression trong Apidog CLI và chạy nó theo lịch — bạn chỉ cần viết một prompt.

Thiết lập CLI và skill agent của nó một lần:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_APIDOG_TOKEN>
npx -y skills add https://apidog.com   # pick Claude Code or Codex when prompted

Sau đó đưa cho Claude Code prompt này:

Write an OpenAPI 3 file for three Firecrawl calls from this guide:
POST /v2/search with sources ["alexandria"], POST /v2/scrape for apollo
people/search (per_page 1), and POST /v2/scrape for apollo people/match.
All send Authorization: Bearer {{FIRECRAWL_API_KEY}}. Import it into Apidog
project <projectId> and create a "Firecrawl" environment for
https://api.firecrawl.dev. Build a test scenario that runs the three in
order, saves data.alexandria[0].data.people[0].id as personId and passes it
to people/match, and asserts status 200, no result error, and a person
object on the match. Run it and summarize failures.

Agent đọc schema payload của từng lệnh gọi, xác thực nó, rồi chạy các lệnh như sau:

apidog import --project <projectId> --format openapi --file ./firecrawl-people.json
apidog environment create Firecrawl --project <projectId> --base-url https://api.firecrawl.dev
apidog test-scenario create --project <projectId> --name "Alexandria people" --folder-id <folderId> --priority <priority>
apidog cli-schema get test-scenario-update
apidog cli-schema validate test-scenario-update --file ./people-scenario.json
apidog test-scenario update <scenarioId> --project <projectId> --file ./people-scenario.json
apidog run -t <scenarioId> --project <projectId> -e <envId> \
  --env-var "FIRECRAWL_API_KEY=$FIRECRAWL_API_KEY" -r cli,junit

Mỗi lần chạy đầy đủ tốn 30 credit cho phần match, nên hãy lên lịch chạy hằng ngày thay vì mỗi lần commit. Tài liệu tham chiếu apidog run liệt kê các c flags báo cáo và lặp, còn Apidog CLI trong Claude Code trình bày phần thiết lập kỹ hơn. Gói Free của Apidog hỗ trợ tối đa 4 người dùng.

Câu hỏi thường gặp

Firecrawl Alexandria people API có miễn phí không? Khám phá miễn phí, và Apollo people/search hiển thị 0 credit vào ngày 4 tháng 11 năm 2026. Tiết lộ một người thì tốn credit: 30 cho Apollo people/match và 60 cho People Data Labs person/enrich. Gói Free bao gồm 1.000 credit mỗi tháng mà không cần thẻ.

Tôi có cần tài khoản Apollo hay People Data Labs riêng không? Không. Alexandria chạy cả hai qua API key Firecrawl của bạn và tính phí bằng credit Firecrawl. Tuy nhiên, một admin của tổ chức cần chấp nhận điều khoản của từng nhà cung cấp một lần — đó chính là điều THIRD_PARTY_DATA_TERMS_REQUIRED yêu cầu.

Tại sao phản hồi people/match của tôi lại hiển thị email_not_unlocked@domain.com? Đó là email giữ chỗ của Apollo cho một email chưa được tiết lộ. Hãy coi nó là không có sẵn, ngay cả khi email_status báo đã xác minh.

Codex hay Cursor có thể chạy thay cho Claude Code không? Có. npx -y firecrawl-cli@latest init --all thiết lập mọi agent được phát hiện, và các công cụ MCP hoạt động trong bất kỳ client MCP nào. Các lệnh gọi curl thì chạy được mà không cần agent nào cả.

Làm sao để tránh trả tiền cho những lần match sai? Tìm kiếm trước khi match, match bằng id Apollo thay vì bằng tên, và đặt min_likelihood từ 6 trở lên với People Data Labs. Apollo không tính phí một lần không khớp, và lỗi 404 của PDL thì miễn phí.