openapi: 3.2.0 info: title: Lusha API Documentation Account Management API version: '' x-logo: url: https://www.lusha.com/logo.png license: name: Proprietary url: https://lusha.com/legal/terms description: "
\n\n⚠️ **This version is soon to be deprecated.** Please [migrate to V3](/apis/openapi).\n\n
\n\n---\n\nLusha provides a RESTful API that allows you to query a comprehensive\ndataset of business profiles and company information.\n\nIt is designed for teams building prospecting, enrichment, automation, and analytics workflows that require accurate, continuously updated business data. The API supports both real-time and bulk use cases and is suitable for production environments.\n\nUse the Lusha API to search for new prospects, enrich existing records, react to real-world changes, and expand coverage using lookalike recommendations.\n\n*All API requests should be made over HTTPS (SSL), and the response bodies are delivered in JSON format.*\n\n---\n \n\n
\n
\n\n \n
\n

\n Person\n

\n \n\n
https://api.lusha.com/v2/person
\n\n
\n \n ▶ Common Use Cases\n \n
    \n
  • • Form enrichment
    • \n
  • • CRM completion
    • \n
  • • Outbound personalization
    • \n
\n
\n
\n\n \n
\n

\n Company\n

\n \n\n
https://api.lusha.com/v2/company
\n\n
\n \n ▶ Common Use Cases\n \n
    \n
  • • Account enrichment
    • \n
  • • Routing, scoring, territory logic
    • \n
  • • Market analysis & segmentation
    • \n
\n
\n
\n\n \n
\n

\n Signals\n

\n \n\n
https://api.lusha.com/v2/signals
\n\n
\n \n ▶ Common Use Cases\n \n
    \n
  • • Job change tracking
    • \n
  • • Company updates signals
    • \n
  • • News event alerts
    • \n
\n
\n
\n\n \n
\n

\n Lookalikes\n

\n \n\n
https://api.lusha.com/v3/lookalike
\n\n
\n \n ▶ Common Use Cases\n \n
    \n
  • • Market expansion
    • \n
  • • Similar account discovery
    • \n
  • • Prospect recommendations
    • \n
\n
\n
\n\n \n
\n

\n Filters\n

\n \n
\n\n \n
\n

\n Account\n

\n \n
\n\n
\n
\n\n \n
\n
\n
\n
\n Webhooks API\n NEW\n
\n

\n Subscribe to real-time notifications when contacts change jobs or companies experience key business events.\n

\n \n View Documentation →\n \n
\n
\n
\n\n\n\n---\n\n**Data Source and Privacy**\n\nPlease note that **Lusha is a search platform**, meaning the data provided\nis not created or directly managed by us. Instead, it is retrieved from\npublicly available sources and through contributions from trusted business\npartners.\n\nFor more information on how we collect, use, and handle business profiles,\nplease refer to our [Privacy Policy](https://lusha.com/legal/privacy-notice/).\n\n----\n\n## Authentication\n\nAPI keys are required for all API and MCP requests and are tied to your Lusha account and plan. To access the Lusha API, you must authenticate your requests using your API\nkey. This key is unique to your account and is used to identify your usage\nof the API.\n\n**How to Authenticate:**\n\nWhen making an API call, include your API key in the `api_key` header of the request.\n\n> You can generate and retrieve your API key [here](https://dashboard.lusha.com/enrich/api).\n\nAPI keys should be stored securely and used only in server-side environments.\n\n---\n\n## Rate Limiting\n\nLusha enforces rate limits on a per-plan basis to ensure fair usage and platform stability. Limits are applied across multiple time windows (per minute, per hour, and per day), and vary depending on your account plan.\n\nRate limits for the **Credit Usage API** differ from standard endpoint limits.\n\n> **Note:** To check your current plan's limits, visit the [Lusha Help Center](https://info.lusha.com/en/articles/163856-all-there-is-to-know-about-lusha-s-api) or contact your account manager.\n\n**Rate Limit Response Headers**\n\nTo monitor your current rate limit status, check the HTTP response headers\nin your API calls:\n\n| Header | Description |\n|--------|-------------|\n| `x-rate-limit-daily` | The total number of requests allowed per day under your current plan |\n| `x-daily-requests-left` | The number of requests remaining in your daily quota |\n| `x-daily-usage` | The number of requests you have made in the current daily period |\n| `x-rate-limit-hourly` | The total number of requests allowed per hour under your current plan |\n| `x-hourly-requests-left` | The number of requests remaining in your hourly quota |\n| `x-hourly-usage` | The number of requests you have made in the current hourly period |\n| `x-rate-limit-minute` | The total number of requests allowed per minute under your current plan |\n| `x-minute-requests-left` | The number of requests remaining in your current minute window |\n| `x-minute-usage` | The number of requests you have made in the current minute window |\n\n---\n\n## Error Codes\n\nLusha API uses standard HTTP response codes to indicate the status of your request.\n\n| Status Code | Name | Description |\n|-------------|------|-------------|\n| **200** | OK | Successful request |\n| **400** | Bad Request | Badly formatted request |\n| **401** | Unauthorized | The API key is invalid |\n| **402** | Payment Required | Your account requires payment |\n| **403** | Forbidden | Your account is not active. Please reach out to support at *support@lusha.com* for assistance |\n| **403** | Forbidden | Your pricing version does not support requesting individual datapoints [revealEmails, revealPhones] |\n| **404** | Not Found | The requested endpoint was not found |\n| **412** | Precondition Failed | The request failed due to invalid syntax that was provided. Please make sure to send a full name field that contains a valid first & last name |\n| **429** | Too Many Requests | You've reached your trial limit, please contact support for upgrade |\n| **429** | Too Many Requests | Daily API quota limit exceeded. Limit X calls per day |\n| **429** | Too Many Requests | Hourly API rate limit exceeded. Limit: X calls per hour. Reset in X seconds |\n| **451** | Unavailable For Legal Reasons | We are unable to process this contact request due to our GDPR regulations |\n| **499** | Client Closed Request | Request failed due to request timeout |\n| **5XX** | Server Error | There's a problem on Lusha's end |\n\n**Error Response Format**\n\nIn case of an error, the response body will contain details about the error:\n\n ```json\n {\n \"error\": {\n \"code\": 400,\n \"message\": \"Invalid request parameters\"\n }\n }\n ```\n\n**Handling errors**\n\n- Always ensure your API key is correct and valid\n- Pay attention to the specific error message and code to troubleshoot issues efficiently\n- Implement proper error handling and retry logic in your application\n- For 5XX errors, implement exponential backoff before retrying\n\n---\n" contact: name: Lusha Support url: https://api.lusha.com email: support@lusha.com termsOfService: https://lusha.com/legal/terms x-privacy-policy: name: Privacy Policy url: https://lusha.com/legal/privacy-notice/ servers: - url: https://api.lusha.com description: Production server security: - ApiKeyAuth: [] tags: - name: Account Management description: 'Manage your account and monitor usage. Use this endpoint to: - Monitor credit usage - Understand consumption patterns - Align API usage with plan limits - Support governance and production operations Account-level insights are especially important for teams running Lusha at scale or across multiple systems. ' paths: /account/usage: get: tags: - Account Management summary: Get Account Usage Statistics description: 'Retrieve your current API credit usage statistics including used, remaining, and total credits. *Endpoint*: **(GET) https://api.lusha.com/account/usage** **Rate Limits**: This endpoint has a specific rate limit of 5 requests per minute. ' operationId: getAccountUsageStats responses: '200': description: Account usage statistics retrieved successfully content: application/json: schema: $ref: '#/components/schemas/AccountUsageStatsResponse' example: usage: bulkCredits: used: 150 total: 1000 remaining: 850 '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' components: responses: InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: statusCode: 500 message: Internal server error. Please try again later. TooManyRequests: description: Too many requests - rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: statusCode: 429 message: Too many requests. Please wait before making another request. headers: RateLimit-Limit: description: The total number of allowed requests per second schema: type: integer RateLimit-Remaining: description: The number of remaining requests in the current window schema: type: integer RateLimit-Reset: description: The time (in seconds) until the rate limit quota is reset schema: type: integer X-RateLimit-Remaining-Daily: description: The number of remaining requests for your daily quota schema: type: integer X-RateLimit-Reset-Daily: description: The time when your daily quota will reset schema: type: integer Unauthorized: description: Unauthorized - invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: statusCode: 401 message: Invalid API key schemas: UsageStats: type: object properties: used: type: number example: 10 total: type: number example: 100 remaining: type: number example: 90 required: - used - total - remaining AccountUsageStatsResponse: type: object properties: usage: type: object additionalProperties: $ref: '#/components/schemas/UsageStats' required: - usage ErrorResponse: type: object required: - statusCode - message properties: statusCode: type: integer description: HTTP status code example: 400 message: type: string description: Error message example: Validation failed errors: type: array items: type: string description: Detailed error messages (optional, only for validation errors) example: - 'entityType must be one of: contact, company' securitySchemes: ApiKeyAuth: type: apiKey in: header name: api_key description: 'Your Lusha API key. You can find this in your Lusha dashboard under API settings. Include this key in the `api_key` header for all requests. '