lonescale enrich - LoneScale API Doc

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

Option	Description
`--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.
`--wait`	Poll until the job completes. Default timeout is 120 s.
`--sync`	Use 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"
  }
]

Each contact needs at least one identifier: linkedin_url, or firstname + lastname + (domain or company_name), or email alone. Every other field is optional — but more context means better match accuracy.

Email as a standalone identifier. An email sent on its own resolves the person behind it — name, LinkedIn URL, job title, company — as long as enrichment_type includes profile. Add email / phone to the same request to also get their contact details.

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

Mode	When to use	Tradeoff
Async (default)	Production workloads, batches > 5 contacts, anything you can poll	Returns a job ID; you poll `lonescale result <id>` or pass `--wait`.
Async + `--wait`	Scripts that want a single blocking call	CLI does the polling for you. Hits the `--timeout` if the job takes longer.
Sync (`--sync`)	Single-contact quick checks, exploration	5 req/min hard rate limit per account; not for batches.

See the underlying endpoints

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

​Synopsis

​Examples

​Options

​Contact schema

​Async vs sync at a glance

See the underlying endpoints

Synopsis

Examples

Options

Contact schema

Async vs sync at a glance