Cách 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 thông qua một khóa Firecrawl duy nhất. Bạn khám phá các công cụ miễn phí với v2/search, liệt kê ứng viên bằng Apollo people/search ở mức 0 credit, tiết lộ một người bằng Apollo people/match ở mức 30 credit, hoặc làm giàu một email đã biết bằng People Data Labs person/enrich ở mức 60 credit. Mọi lệnh gọi đều đi qua POST /v2/scrape.

Mỗi bước dưới đây 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 các nhà cung cấp dữ liệu bên thứ ba của Firecrawl, có thể truy cập bằng API key mà bạ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 nó bằng scrape. Khám phá thì miễn phí; thực thi tốn 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 nói rằng 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 tính phí 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 và 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ũng 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 cho 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 làm 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ò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:

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 chỉ với sources được đặt thành ["alexandria"]. Bỏ "web" sẽ giữ 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 gồ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: nó miễn phí và cho bạn thấy ai tồn tại trước khi bạn chi bất cứ thứ gì.

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ờ chỉ trả tiền cho những người đá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 cần chúng. Trang Apollo nói rằng 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ề một 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 nó 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 mang theo một requiresAction.url, và một admin của tổ chức phải mở nó và 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 nó. Tài liệu nói rằng 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 bạn đọ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 trả 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 một script 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 cá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ờ 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á thì 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 mỗi 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 cái nà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í.