## Overview

This page is the technical entry point to the Lusha API.
It introduces the core data types exposed by the API, the main access patterns, and the fundamentals required to authenticate and make a first request.
Use this section to understand how the API is structured and confirm access before moving into specific capabilities.

## How the Lusha API is organized

The Lusha API exposes GTM data through a small set of core data types and access patterns.

### Core data types

* **People** — contact profiles and identifiers
* **Companies** — firmographic and company-level attributes
* **Signals** — change-based events across contacts and companies
* **Lookalikes** — similarity-based recommendations for expansion


### Access patterns

* **Enrichment** — add missing or updated data to existing records
* **Search & prospecting** — find contacts and companies using filters
* **Automation** — use enrichment and signals inside workflows


## Endpoints at a Glance

| Resource | Endpoint | Purpose |
|  --- | --- | --- |
| Person | `GET /v2/person` | Lookup contact details |
|  | `POST /v2/person` | Bulk person enrichment |
| Company | `GET /v2/company` | Lookup company info |
|  | `POST /v2/company` | Bulk company enrichment |
| Prospect | `POST /prospecting/contact/search` | Search for contacts |
|  | `POST /prospecting/contact/enrich` | Enrich contact data |
|  | `POST /prospecting/company/search` | Search for companies |
|  | `POST /prospecting/company/enrich` | Enrich company data |
| Account | `GET /account/usage` | Check credit usage |
| Signals | `POST /signals/contacts` | Retrieve contact signals by IDs |
|  | `POST /signals/companies` | Retrieve company signals by IDs |
|  | `POST /signals/contacts/search` | Retrieve contact signals by identifiers |
|  | `POST /signals/companies/search` | Retrieve company signals by identifiers |
| Recommendations | `POST /recommendations/contacts` | Get contact recommendations |
|  | `POST /recommendations/companies` | Get company recommendations |


## 1. Authentication

### API key setup

* Generate and manage API keys in the [Lusha API Dashboard](https://dashboard.lusha.com/api)
* Store keys securely (for example, using environment variables)
* Never expose API keys in client-side code


### Authenticating requests

When making an API call, include your API key in the api_key header of the request.

* **Header:** `api_key`
* **Format:** `Bearer YOUR_API_KEY`


## 2. Data model basics

* All responses are returned as structured JSON
* Common fields include `email`, `phone`, `job title`, `company`, and `location`
* Some fields may be missing depending on availability, permissions, or compliance rules


## 3. First request

### Example: enrich a person


```bash
GET https://api.lusha.com/v2/person
```

* Send identifying fields such as `firstName`, `lastName`, `company`
* Parse the JSON response
* Locate returned fields such as `email` or `phone` when available


## 4. Error handling basics

* Check HTTP status codes for every response
* Handle 4xx and 5xx errors explicitly
* Implement retry logic for rate limit responses (HTTP 429)


Detailed error formats and retry guidance are covered in [**Errors & handling**](/apis/openapi)

## 5. Rate limits and pagination

* Default rate limit: 25 requests per second
* Some endpoints return paginated results
* Use pagination tokens to retrieve additional pages


> See [**Rate limits**](/apis/openapi) for full details.


## 6. Next steps

Once you've validated access, you can:

* Use **Enrichment** to add missing data to contacts and companies
* Explore **Search & prospecting** to build dynamic contact and company lists
* Add **Signals** to trigger workflows based on real-world changes
* Apply **Lookalikes** to expand target accounts and audiences
* Explore **MCP** for AI- and agent-based workflows
* Review rate limits and best practices before moving to production


## 7. Integration Guides

Quick implementations for common platforms:

- **Salesforce**
  - Apex trigger on `Lead` creation → call Lusha API → update fields.
  - Flows for easy webhook API implementation.
- **HubSpot**
  - Workflow → custom webhook
  - Map response to HubSpot properties (YAML/JSON examples).
- **Webhooks**
  - Subscribe to events (e.g., data updates).
  - Verify signatures; Node.js/Express listener example.
- **Bulk Enrichment**
  - Python scripts to process CSV files
  - Submit bulk requests, poll for results, and write output to a database or file
- **SDK Examples (Node.js, Python, Java)**
  - Community wrappers: install, initialize, fetch data.
  - Raw HTTP equivalents for each example.


## 8. Advanced Topics

Deeper guidance for teams running Lusha at scale.

- **Performance & Cost**
  - Batch requests, caching (Redis/in-memory), cost-aware enrichment patterns.
- **Complex Queries**
  - Combine parameters for higher accuracy, client-side matching and deduplication.
- **Security Best Practices**
  - Encrypt API keys, enforce least privilege, audit logging.
- **Orchestration Workflows**
  - Terraform/CloudFormation snippets for AWS Lambda and API Gateway.
- **Data Quality & Fallbacks**
  - Handle missing fields: fallback to alternative data sources, merge multiple enrichers.
- **Schema & Data Modeling**
  - DB table structures (Postgres, MongoDB), indexing (email hash, domain), migration strategies.
- **Compliance & Privacy**
  - GDPR/CCPA guidelines: retention policies, anonymization, privacy disclaimers.
- **Custom Connectors**
  - Build for Workato, Zapier, Make: HTTP module config, auth, mapping, error patterns.


## Need help?

- [**Full API Doc**](/apis/openapi): Complete endpoint docs with examples (cURL, Node.js, Python, Java).
- [**Common API questions**](/qa): FAQs and clarifications.
- [**Changelog & Release Notes**](/changelog): Track new endpoints, parameter changes, deprecations.
- [**Help Center**](/tutorials): Links to community-driven wrappers; installation and usage.


> **Explore the Postman Public Environment**: Test out the API endpoints and see how the data is structured. You can access our public Postman workspace to experiment with live examples and understand the response formats - [Access Lusha's Postman Workspace!](https://www.postman.com/lushateam/workspace/lusha-s-api/collection/28683568-fc849873-9ae1-47dd-8159-0d4deda04750)