Lusha User Management API Guide

Auth method: API Key (header: api_key)

Setup steps

1. Log in to your Lusha account and navigate to Settings > API.
2. Generate or copy your API key.
3. Include the key in all requests as the header: api_key: .

User object field mapping is not yet verified for this app.

Enrich person by email

• Method: GET
• URL: https://api.lusha.com/person
• Watch out for: Each successful match consumes one credit. No result does not consume a credit but returns a 404.

Request example

GET /person?email=john@example.com HTTP/1.1
Host: api.lusha.com
api_key: YOUR_API_KEY

Response example

{
  "firstName": "John",
  "lastName": "Doe",
  "emails": [{"email": "john@example.com"}],
  "phoneNumbers": [{"number": "+1..."}]
}

Enrich company by domain

• Method: GET
• URL: https://api.lusha.com/company
• Watch out for: Company enrichment is a separate credit pool on some plans; verify plan entitlements before bulk use.

Request example

GET /company?domain=example.com HTTP/1.1
Host: api.lusha.com
api_key: YOUR_API_KEY

Response example

{
  "name": "Example Corp",
  "domain": "example.com",
  "industry": "Software",
  "size": "51-200"
}

• Rate limits: Rate limits are tied to the credit/plan system. Lusha's public API is primarily a data enrichment API; specific rate-limit headers or numeric per-minute limits are not publicly documented.
• Rate-limit headers: No
• Retry-After header: No
• Rate-limit notes: Each successful API call consumes credits. No documented HTTP rate-limit headers or per-second/per-minute throttle values found in official docs.
• Pagination method: none
• Default page size: 0
• Max page size: 0
• Pagination pointer: Not documented

• Webhooks available: No
• Webhook notes: No webhook functionality is documented in Lusha's official API or help center documentation.
• Alternative event strategy: Poll the enrichment API on a scheduled basis for updated contact/company data.

• SCIM available: No
• SCIM version: Not documented
• Plan required: Enterprise
• Endpoint: Not documented

Limitations:

• No SCIM provisioning is documented by Lusha as of the policy date.
• User provisioning/deprovisioning must be performed manually via the Lusha admin dashboard.
• SAML SSO (Okta, Azure AD, custom SAML) is available on Enterprise plans but does not include SCIM.

The primary integration pattern is CRM enrichment: send a GET to /person with a target email, parse the returned phoneNumbers and emails arrays, and write back to the CRM record. Each matched result consumes one credit; a 404 does not. Implement a credit-balance check before any bulk run.

For account-based marketing pipelines, GET /company?domain= returns firmographic fields (industry, size, HQ location). Company enrichment availability varies by plan tier - validate entitlements before batching at scale. Use exponential back-off on non-2xx responses; there are no documented rate-limit headers, so credit exhaustion from retry storms is a real risk.

SSO setup (Okta, Enterprise only) follows a standard SAML 2.0 exchange: copy the ACS URL from Lusha Settings → Security → SSO, configure the IdP app, paste the IdP metadata back into Lusha, and test with a pilot user. SSO does not trigger automatic provisioning - new users must still be invited manually before their first SSO login.

Enrich a CRM contact with phone and email via API

1. Obtain your API key from Lusha Settings > API.
2. Send GET https://api.lusha.com/person?email=target@company.com with header api_key: YOUR_KEY.
3. Parse the returned phoneNumbers and emails arrays and write them back to your CRM record.

Watch out for: Each matched record consumes one credit. Implement a credit-balance check before bulk enrichment runs.

Set up SAML SSO for team access (Okta)

1. Ensure your Lusha plan is Enterprise (SSO is an Enterprise feature).
2. In Lusha admin, navigate to Settings > Security > SSO and copy the SP metadata/ACS URL.
3. In Okta, create a new SAML 2.0 app using Lusha's ACS URL and Entity ID.
4. Paste the Okta IdP metadata XML back into Lusha's SSO configuration and enable SSO.
5. Test with a pilot user before enforcing SSO for all team members.

Watch out for: SSO does not trigger automatic user provisioning (no SCIM). New users must still be invited manually in the Lusha admin dashboard before they can log in via SSO.

Bulk company enrichment for account-based marketing

1. Prepare a list of target domains.
2. For each domain, send GET https://api.lusha.com/company?domain= with your API key.
3. Collect industry, size, and HQ location fields from responses.
4. Implement exponential back-off on non-2xx responses to avoid exhausting credits on transient errors.

Watch out for: Company enrichment availability depends on plan tier. Validate credit balance and plan entitlements before running large batches.

The core trap is assuming Lusha's API can anchor a provisioning workflow. It cannot. The API is read-only enrichment; there is no write surface for user objects, no SCIM endpoint, and no webhook to signal seat changes.

Any identity graph that expects Lusha to emit lifecycle events - user added, user removed, role changed - will receive nothing.

Credit consumption is the second trap. There are no documented HTTP rate-limit headers and no retry-after signals. Bulk enrichment jobs that hit transient errors and retry aggressively will silently drain the credit pool with no programmatic warning.

Monitor credit state via dashboard or parse response metadata manually.

For teams using an MCP server with 60+ deep IT/identity integrations to orchestrate SaaS access reviews, Lusha will require a manual reconciliation step on every cycle. The absence of a user-list endpoint means there is no automated way to confirm who currently holds an active seat.