Recipes - LoneScale API Doc

Real-world scripting patterns that combine the CLI commands. All examples assume LONESCALE_API_KEY is already exported (see Overview → Authenticate).

Fire and poll

The async pattern, broken into two explicit steps:

JOB_ID=$(lonescale enrich --type email --contacts contacts.json --output minimal)
echo "Started job $JOB_ID"
lonescale result "$JOB_ID" --poll --output json > results.json

Or condensed into a single blocking call:

lonescale enrich --type email --contacts contacts.json --wait --output json > results.json

Batch enrichment across multiple files

mkdir -p results
for file in contacts/*.json; do
  echo "Processing $file..."
  lonescale enrich --type email --contacts "$file" --wait --output json \
    > "results/$(basename "$file")"
done

Pipe sourcing → enrichment

Source contacts at a company, then immediately enrich the LinkedIn URLs:

lonescale source --domain figma.com \
  --personas-inline '[{"name":"Eng","job_titles":["engineering manager"]}]' \
  --locations US --limit 10 --wait --output json \
  | jq '[.contacts[] | { firstname, lastname, linkedin_url }]' \
  | lonescale enrich --type email --wait --output json \
  > figma-eng-emails.json

Filter with `jq`

# Just the names + most probable email
lonescale source --domain acme.com \
  --personas-inline '[{"name":"Sales","job_titles":["VP Sales","Head of Sales"]}]' \
  --wait --output json \
  | jq '.contacts[] | { name: (.firstname + " " + .lastname), email: .most_probable_email }'

Look up a list of companies

# domains.txt — one domain per line
while read domain; do
  lonescale companies search --domain "$domain" --output json
done < domains.txt | jq -s '.'   # combine into a single JSON array

Debug mode

Pass --debug to print every HTTP request and response to stderr. API keys are redacted automatically.

$ lonescale enrich --type email --contacts c.json --debug --wait
[DEBUG] POST https://public-api.lonescale.com/trigger/enrich
[DEBUG] Body: { "enrichment_type": ["email"], "contacts": [...] }
[DEBUG] Response: 200 { "id": "abc-123", "status": "..." }
[INFO]  Job abc-123 started, polling...
[DEBUG] GET https://public-api.lonescale.com/trigger/run/abc-123
[DEBUG] Response: 200 { "status": "processing" }
[DEBUG] GET https://public-api.lonescale.com/trigger/run/abc-123
[DEBUG] Response: 200 { "status": "finished", "contacts": [...] }

Because logs go to stderr and data goes to stdout, you can debug a pipeline without polluting the JSON output:

lonescale enrich --type email --contacts c.json --debug --wait --output json 2> debug.log | jq '.contacts | length'

CI / cron usage

# Example: nightly enrichment in GitHub Actions
- name: Enrich new leads
  env:
    LONESCALE_API_KEY: ${{ secrets.LONESCALE_API_KEY }}
  run: |
    npx -y @lonescale/cli enrich \
      --type email,phone \
      --contacts ./pipeline/new-leads.json \
      --wait --output json > ./pipeline/enriched.json

Need something else?

Tell us your use case at happy@lonescale.com.

​Fire and poll

​Batch enrichment across multiple files

​Pipe sourcing → enrichment

​Filter with jq

​Look up a list of companies

​Debug mode

​CI / cron usage