Lusha

What your agents can doCopy Anchor Link

Helios agents call Lusha's v3 API with your API key. Available operations depend on your key's permissions and Lusha plan.

• Find a person's work email or phone number from their name and company, email, or LinkedIn profile
• Enrich a company by domain with its size, industry, revenue, and technologies
• Find contacts at a target account with prospecting filters, or find the account's buying group
• Read and score signals for contacts and companies, such as job changes and hiring surges
• Add contacts and companies to Lusha tables
• Search recorded Lusha Conversations calls and read their transcripts

Most calls use credits from your Lusha plan, the same as in Lusha. Helios checks the connection with Lusha's usage endpoint, which is free.

The agent's API tool only reaches api.lusha.com.

AuthenticationCopy Anchor Link

See Integration authentication for how credentials are stored and injected.

Lusha API KeyCopy Anchor Link

Use an API key from your Lusha account. The account's permissions, plan, and credit limits apply to calls made through Helios. Triggers also require access to Lusha's webhook API.

To connect:

1. In Lusha, open API Hub and select the Manage API Keys tab.
2. Copy your key, or generate a new one.
3. In Helios, choose Lusha API Key and paste the key into Lusha API Key.
4. Optional: fill in Contacts to watch and Companies to watch for triggers.
5. Save.

If you delete or replace the key in Lusha, enter the new one through Manage.

TriggersCopy Anchor Link

When you save the connection, Helios sets up subscriptions through Lusha's webhook API. Subscription setup depends on your account's webhook access and existing subscriptions. Before setting up triggers, create the account's webhook secret in Lusha if it has none.

Lusha sends signals for one contact or company at a time, so you choose what to watch on the connection:

• Contacts to watch: Lusha contact IDs, separated by commas. Helios subscribes each contact to the supported contact signals: promotions and company changes.
• Companies to watch: Lusha company IDs, separated by commas. Helios subscribes each company to the supported company signals: hiring surges, headcount changes, website traffic, IT spend, and news.

Lusha IDs are the id field in Lusha search and enrichment results. An agent can look them up for you from names, emails, or domains.

When you save the connection, Helios creates the subscriptions in Lusha, named Helios. When you change the lists, it adds subscriptions for new IDs before it removes the ones for IDs you took out. Deleting the connection removes them. Lusha allows one subscription per contact or company in an account. When another subscription already watches an ID, Lusha rejects it with DUPLICATE_SUBSCRIPTION and Helios skips it.

Helios also creates the account's opt-out subscription, named Helios, which needs no watch list. It sends contact.opted_out when any contact that your account revealed opts out of Lusha. Lusha allows one opt-out subscription per account. If the account already has one, Lusha refuses the Helios one and contact.opted_out shows as unavailable.

To see what was created and what was skipped, open API Hub → Webhooks in Lusha. The Webhook Subscriptions table lists the account's subscriptions. An ID that isn't in a Helios subscription was skipped, and the subscription that already watches it is listed under another name. You can also ask an agent to list the Lusha subscriptions, since agents can call Lusha's webhook API.

All filters are optional, and case doesn't matter in any of them.

• New job title matches the contact's title after the change, such as VP*. A / counts as a space, so *CEO* matches Founder/CEO.
• Company domain matches the watched company's domain on company events, and the domain of the contact's current company on contact events. For example, acme.com or *.acme.com.
• News event type matches the type of the news story, such as partnership or *funding*. An agent can list Lusha's news event types with Lusha's company signal filters endpoint.

The trigger picker shows an event as unavailable, with the reason, when it can't arrive on this connection:

• Every contact event, when Contacts to watch is empty or Lusha rejected every contact in it, for example because the plan doesn't include webhooks. The same goes for company events and Companies to watch.
• contact.opted_out, when Lusha refused the opt-out subscription.

Lusha checks most signals weekly, and headcount, website traffic, and IT spend monthly. An event can arrive weeks after the change.

Lusha signs every delivery with one webhook secret for the whole account. Helios reads it when you save the connection. If the account has no secret, setup stops and asks you to create one in Lusha, then save the connection again. Helios never regenerates the secret during setup. If you regenerate the secret in Lusha, save the connection in Helios again. Until you do, or until the daily refresh picks up the new secret, deliveries fail verification. Deliveries are verified with the HMAC-SHA256 X-Lusha-Signature header over the timestamp and body, and deliveries more than five minutes old are rejected.

Lusha retries a failed delivery 3 times, then disables the subscription. Helios checks its subscriptions once a day and turns disabled ones back on. If the setup itself fails, for example because Lusha rejects the key, the daily refresh stops. Fix the cause and save the connection again.

Check that it worksCopy Anchor Link

• The connection: after you save, the connection's status shows Connected. Error means the connection test failed.

• The subscriptions: in Lusha, open API Hub → Webhooks and find the subscriptions named Helios, including the opt-out subscription.

• A trigger: Lusha signals arrive weekly or monthly, so you can't cause one on demand.

  1. Add company.hiring_surged or a news event to a workflow with no filters.
  2. Watch a few companies that are likely to have news or hiring activity.
  3. When a run starts, open the connection in Helios and click Webhook events to see the event.

  Lusha can also send a test delivery for one subscription, with mock data and no credits. Ask an agent to call Lusha's test endpoint for a Helios subscription.

Common errorsCopy Anchor Link

LimitsCopy Anchor Link

Lusha's rate limits, credits, and webhook subscription limits apply. Helios creates and deletes subscriptions in groups of up to 25. See Lusha's API overview and webhooks overview for plan limits.