Skip to main content
Trigger waterfall enrichment (email and/or phone) for a list of contacts. By default the command is asynchronous — it returns a job ID immediately and you poll for results via lonescale result, or pass --wait to have the CLI block until the job finishes.

​
Synopsis

lonescale enrich --type <types> [--contacts <file> | --contacts-inline <json>] [options]

​
Examples

# From a JSON file, polling until done
lonescale enrich --type email,phone --contacts contacts.json --wait

# Inline JSON for a single contact
lonescale enrich --type email --contacts-inline '[
  { "firstname": "John", "lastname": "Doe", "domain": "acme.com" }
]'

# Sync mode (returns results directly, rate-limited to 5 req/min)
lonescale enrich --type email --contacts contacts.json --sync

# Pipe from stdin (any source that produces a JSON array of contacts)
cat contacts.json | lonescale enrich --type email

​
Options

OptionDescription
--type <types>Required. Comma-separated enrichment types: email, phone, or email,phone.
--contacts <file>Path to a JSON file containing the contacts array.
--contacts-inline <json>Inline JSON array (use when piping or scripting).
--custom <json>Custom metadata JSON, echoed back in the result and any webhook payload.
--waitPoll until the job completes. Default timeout is 120 s.
--syncUse the synchronous endpoint. Returns results inline but is rate-limited to 5 requests / minute.
--timeout <seconds>Override the --wait / --sync timeout (default 120).
Plus all global options (--api-key, --output, --debug).

​
Contact schema

[
  {
    "firstname": "John",
    "lastname": "Doe",
    "email": "john@acme.com",
    "job_title": "CTO",
    "linkedin_url": "https://linkedin.com/in/johndoe",
    "domain": "acme.com",
    "company_name": "Acme Inc"
  }
]
firstname and lastname are required. Every other field is optional — but more context means better match accuracy.
Predicted email fallback. For email enrichment, if no provider returns an email, the result falls back to a pattern-based predicted email built from the contact’s name and company domain. It is returned with most_probable_email_status: "predicted" (and an emails[] entry with the same status), alongside predicted_email, email_pattern (e.g. firstname.lastname@domain), and predicted_email_score. Predicted emails are free — they don’t consume enrichment credits. Provide a domain to enable this fallback.

​
Async vs sync at a glance

ModeWhen to useTradeoff
Async (default)Production workloads, batches > 5 contacts, anything you can pollReturns a job ID; you poll lonescale result <id> or pass --wait.
Async + --waitScripts that want a single blocking callCLI does the polling for you. Hits the --timeout if the job takes longer.
Sync (--sync)Single-contact quick checks, exploration5 req/min hard rate limit per account; not for batches.

See the underlying endpoints

POST /trigger/enrich (async) and POST /trigger/enrich/sync (sync).