← All recipesrecipe 04

Build a verified lead list in one call

What you'll build: a verified list of people at companies matching your filters, using the server-side lead-list workflow — quoted first, then run, then exported as CSV.

Section	Server-side workflows
Actions used	`POST /v1/data/workflows/lead-list:estimatePOST /v1/data/workflows/lead-list`
Credits	7 per person found (worst case)
Test-key safe	No — needs a live key
Time to complete	~15 min
Prerequisites	A qk_live_ key with a credit balance. This recipe touches paid sources, so a test key returns fixtures rather than live results.

What the workflow chains

Three steps run on our side per person: find candidates matching your filters, find the email address, then verify that address. You send one request instead of orchestrating three, and each step bills only when it produces something.

list-workflows.sh

# Discover what is available to your key rather than
# trusting a list copied from a page.
curl https://api.qannasapi.com/v1/data/workflows \
  -H "Authorization: Bearer $QANNAS_API_KEY"

Quote it with dry_run

Send the workflow body with dry_run: true and you get the per-step credit breakdown without running anything. This is the number to budget against — it assumes every step succeeds for every person.

quote.sh

curl -X POST https://api.qannasapi.com/v1/data/workflows/lead-list \
  -H "Authorization: Bearer $QANNAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "inputs": {"industry": "logistics", "country": "AE"},
        "limit": 25,
        "dry_run": true
      }'

# < X-Credits-Charged: 0   # the quote is free

Run it

Drop dry_run and send the same body. Set format to csv if you want a file rather than JSON; markdown is available too. The response carries the same credit headers as any other call, so you can reconcile the run against the quote immediately.

run.sh

# Same body, without dry_run. format: json | csv | markdown
curl -X POST https://api.qannasapi.com/v1/data/workflows/lead-list \
  -H "Authorization: Bearer $QANNAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "inputs": {"industry": "logistics", "country": "AE"},
        "limit": 25,
        "format": "csv"
      }'

# < X-Credits-Charged: 138  # reconcile this against the quote

Refresh on a delta

Set track_delta on the first run and pass the returned cursor as since_cursor on the next one to receive only what changed. Note that delta is a filter on what you receive, not a discount on what you pay.

delta.sh

# Run one: ask for a cursor.
curl -X POST https://api.qannasapi.com/v1/data/search/people \
  -H "Authorization: Bearer $QANNAS_API_KEY" \
  -d '{"query": "logistics AE", "track_delta": true}'

# Run two: receive only what changed.
# NOTE: delta filters what you RECEIVE. It is not a discount.
curl -X POST https://api.qannasapi.com/v1/data/search/people \
  -H "Authorization: Bearer $QANNAS_API_KEY" \
  -d '{"query": "logistics AE", "since_cursor": "cur_..."}'

Summary

Pattern	How
Quote	POST /v1/data/workflows/lead-list with dry_run: true
Run	Same body, without dry_run
Chained steps	search → find email → verify email, billed per step
Output format	format: json \| csv \| markdown
Incremental refresh	track_delta on run one, since_cursor after
Cost shape	Per person found, not per person requested

Production checklist

Quote with dry_run before every scheduled run, not just the first.
Budget against the ceiling; reconcile against X-Credits-Charged.
Store the delta cursor with the list, not in application memory.
Re-verify addresses on a schedule — deliverability decays.

Next steps

recipe 05

Clean an email list

Batch-verify a list and get a decay report back, without hand-rolling a queue.

recipe 01

Estimate before you call

Quote the exact credit cost of any action before you run it, for free.

Run the estimate first. It costs nothing and it is the same arithmetic the meter will apply.

Get your API key Read the API reference