Lusha Account Management API

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: "<blockquote class=\"callout-warning\">\n\n⚠️ **This version is soon to be deprecated.** Please [migrate to V3](/apis/openapi).\n\n</blockquote>\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    <style>\n    body {\n        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;\n        margin: 0;\n        padding: 0;\n        background: #ffffff;\n    }\n\n    .endpoint-link {\n        color: #0969da;\n        text-decoration: none;\n        transition: all 0.2s ease;\n    }\n\n    .endpoint-link:hover {\n        color: #0550ae;\n        text-decoration: underline;\n    }\n\n    .endpoint-url {\n        font-family: 'SF Mono', Monaco, 'Cascadia Code', monospace;\n        font-size: 9px;\n        color: #6b7280;\n        background: #f3f4f6;\n        padding: 3px 6px;\n        border-radius: 4px;\n        margin-top: 8px;\n        margin-bottom: 10px;\n        display: inline-block;\n    }\n\n    details summary:hover {\n        color: #4b5563;\n    }\n</style>\n\n<div style=\"max-width: 900px; margin: 0 auto; padding: 15px;\">\n    <div style=\"display: grid; grid-template-columns: repeat(2, 1fr); gap: 12px;\">\n\n        <!-- Person Card -->\n        <div style=\"background: #fafbfc; border: 1px solid #d1d5db; border-radius: 6px; padding: 14px; min-height: 160px;\">\n            <h3 style=\"margin: 0 0 8px 0; color: #1f2937; font-size: 14px; font-weight: 600; padding-bottom: 6px; border-bottom: 1px solid #e5e7eb;\">\n                Person\n            </h3>\n            <ul style=\"font-size: 12px; line-height: 1.4; margin: 0; padding-left: 0; list-style: none;\">\n                <li style=\"padding: 2px 0;\">• <a href=\"#operation/searchSingleContact\" class=\"endpoint-link\">Person Enrichment</a></li>\n                <li style=\"padding: 2px 0;\">• <a href=\"#operation/searchProspectingContacts\" class=\"endpoint-link\">Contact Search &amp; Enrich</a></li>\n            </ul>\n\n            <div class=\"endpoint-url\">https://api.lusha.com/v2/person</div>\n\n            <details style=\"margin-top: 10px; padding-top: 8px; border-top: 1px solid #e5e7eb;\">\n                <summary style=\"cursor: pointer; font-size: 10px; font-weight: 600; color: #6b7280; text-transform: uppercase; letter-spacing: 0.5px; margin: 0 0 6px 0; list-style: none;\">\n                    ▶ Common Use Cases\n                </summary>\n                <ul style=\"font-size: 11px; line-height: 1.4; margin: 0; padding-left: 14px; list-style: none; color: #4b5563;\">\n                    <li style=\"padding: 1px 0;\">• Form enrichment</li>\n                    <li style=\"padding: 1px 0;\">• CRM completion</li>\n                    <li style=\"padding: 1px 0;\">• Outbound personalization</li>\n                </ul>\n            </details>\n        </div>\n\n        <!-- Company Card -->\n        <div style=\"background: #fafbfc; border: 1px solid #d1d5db; border-radius: 6px; padding: 14px; min-height: 160px;\">\n            <h3 style=\"margin: 0 0 8px 0; color: #1f2937; font-size: 14px; font-weight: 600; padding-bottom: 6px; border-bottom: 1px solid #e5e7eb;\">\n                Company\n            </h3>\n            <ul style=\"font-size: 12px; line-height: 1.4; margin: 0; padding-left: 0; list-style: none;\">\n                <li style=\"padding: 2px 0;\">• <a href=\"#operation/searchSingleCompanyV2\" class=\"endpoint-link\">Company Enrichment</a></li>\n                <li style=\"padding: 2px 0;\">• <a href=\"#operation/searchProspectingCompanies\" class=\"endpoint-link\">Company Search &amp; Enrich</a></li>\n            </ul>\n\n            <div class=\"endpoint-url\">https://api.lusha.com/v2/company</div>\n\n            <details style=\"margin-top: 10px; padding-top: 8px; border-top: 1px solid #e5e7eb;\">\n                <summary style=\"cursor: pointer; font-size: 10px; font-weight: 600; color: #6b7280; text-transform: uppercase; letter-spacing: 0.5px; margin: 0 0 6px 0; list-style: none;\">\n                    ▶ Common Use Cases\n                </summary>\n                <ul style=\"font-size: 11px; line-height: 1.4; margin: 0; padding-left: 14px; list-style: none; color: #4b5563;\">\n                    <li style=\"padding: 1px 0;\">• Account enrichment</li>\n                    <li style=\"padding: 1px 0;\">• Routing, scoring, territory logic</li>\n                    <li style=\"padding: 1px 0;\">• Market analysis &amp; segmentation</li>\n                </ul>\n            </details>\n        </div>\n\n        <!-- Signals Card -->\n        <div style=\"background: #fafbfc; border: 1px solid #d1d5db; border-radius: 6px; padding: 14px; min-height: 160px;\">\n            <h3 style=\"margin: 0 0 8px 0; color: #1f2937; font-size: 14px; font-weight: 600; padding-bottom: 6px; border-bottom: 1px solid #e5e7eb;\">\n                Signals\n            </h3>\n            <ul style=\"font-size: 12px; line-height: 1.4; margin: 0; padding-left: 0; list-style: none;\">\n                <li style=\"padding: 2px 0;\">• <a href=\"#operation/getContactSignalsById\" class=\"endpoint-link\">Contact Signals</a></li>\n                <li style=\"padding: 2px 0;\">• <a href=\"#operation/getCompanySignalsById\" class=\"endpoint-link\">Company Signals</a></li>\n            </ul>\n\n            <div class=\"endpoint-url\">https://api.lusha.com/v2/signals</div>\n\n            <details style=\"margin-top: 10px; padding-top: 8px; border-top: 1px solid #e5e7eb;\">\n                <summary style=\"cursor: pointer; font-size: 10px; font-weight: 600; color: #6b7280; text-transform: uppercase; letter-spacing: 0.5px; margin: 0 0 6px 0; list-style: none;\">\n                    ▶ Common Use Cases\n                </summary>\n                <ul style=\"font-size: 11px; line-height: 1.4; margin: 0; padding-left: 14px; list-style: none; color: #4b5563;\">\n                    <li style=\"padding: 1px 0;\">• Job change tracking</li>\n                    <li style=\"padding: 1px 0;\">• Company updates signals</li>\n                    <li style=\"padding: 1px 0;\">• News event alerts</li>\n                </ul>\n            </details>\n        </div>\n\n        <!-- Lookalikes Card -->\n        <div style=\"background: #fafbfc; border: 1px solid #d1d5db; border-radius: 6px; padding: 14px; min-height: 160px;\">\n            <h3 style=\"margin: 0 0 8px 0; color: #1f2937; font-size: 14px; font-weight: 600; padding-bottom: 6px; border-bottom: 1px solid #e5e7eb;\">\n                Lookalikes\n            </h3>\n            <ul style=\"font-size: 12px; line-height: 1.4; margin: 0; padding-left: 0; list-style: none;\">\n                <li style=\"padding: 2px 0;\">• <a href=\"#operation/getContactLookalikes\" class=\"endpoint-link\">Similar Contacts</a></li>\n                <li style=\"padding: 2px 0;\">• <a href=\"#operation/getCompanyLookalikes\" class=\"endpoint-link\">Similar Companies</a></li>\n            </ul>\n\n            <div class=\"endpoint-url\">https://api.lusha.com/v3/lookalike</div>\n\n            <details style=\"margin-top: 10px; padding-top: 8px; border-top: 1px solid #e5e7eb;\">\n                <summary style=\"cursor: pointer; font-size: 10px; font-weight: 600; color: #6b7280; text-spacing: 0.5px; margin: 0 0 6px 0; list-style: none;\">\n                    ▶ Common Use Cases\n                </summary>\n                <ul style=\"font-size: 11px; line-height: 1.4; margin: 0; padding-left: 14px; list-style: none; color: #4b5563;\">\n                    <li style=\"padding: 1px 0;\">• Market expansion</li>\n                    <li style=\"padding: 1px 0;\">• Similar account discovery</li>\n                    <li style=\"padding: 1px 0;\">• Prospect recommendations</li>\n                </ul>\n            </details>\n        </div>\n\n        <!-- Filters Card -->\n        <div style=\"background: #fafbfc; border: 1px solid #d1d5db; border-radius: 6px; padding: 14px; min-height: 160px;\">\n            <h3 style=\"margin: 0 0 8px 0; color: #1f2937; font-size: 14px; font-weight: 600; padding-bottom: 6px; border-bottom: 1px solid #e5e7eb;\">\n                Filters\n            </h3>\n            <ul style=\"font-size: 12px; line-height: 1.4; margin: 0; padding-left: 0; list-style: none;\">\n                <li style=\"padding: 2px 0;\">• <a href=\"#operation/getSignalOptions\" class=\"endpoint-link\">Signal Options</a></li>\n                <li style=\"padding: 2px 0;\">• <a href=\"#tag/Contact-Filters\" class=\"endpoint-link\">Contact Filters</a></li>\n                <li style=\"padding: 2px 0;\">• <a href=\"#tag/Company-Filters\" class=\"endpoint-link\">Company Filters</a></li>\n            </ul>\n        </div>\n\n        <!-- Account Card -->\n        <div style=\"background: #fafbfc; border: 1px solid #d1d5db; border-radius: 6px; padding: 14px; min-height: 160px;\">\n            <h3 style=\"margin: 0 0 8px 0; color: #1f2937; font-size: 14px; font-weight: 600; padding-bottom: 6px; border-bottom: 1px solid #e5e7eb;\">\n                Account\n            </h3>\n            <ul style=\"font-size: 12px; line-height: 1.4; margin: 0; padding-left: 0; list-style: none;\">\n                <li style=\"padding: 2px 0;\">• <a href=\"/guides\" class=\"endpoint-link\">Getting started</a></li>\n                <li style=\"padding: 2px 0;\">• <a href=\"#operation/getAccountUsageStats\" class=\"endpoint-link\">Credit Usage</a></li>\n                <li style=\"padding: 2px 0;\">• <a href=\"#tag/Account-Management\" class=\"endpoint-link\">Rate Limits</a></li>\n            </ul>\n        </div>\n\n    </div>\n</div>\n\n  <!-- WEBHOOKS FEATURED BANNER -->\n  <div style=\"background: #f8f9fa; border: 1px solid #e5e7eb; padding: 18px 20px; border-radius: 8px; margin-top: 20px; box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);\">\n      <div style=\"display: flex; align-items: center; gap: 14px;\">\n          <div style=\"flex: 1;\">\n              <div style=\"display: flex; align-items: center; gap: 8px; margin-bottom: 6px;\">\n                  <strong style=\"font-size: 16px; color: #1f2937;\">Webhooks API</strong>\n                  <span style=\"background-color: #dbeafe; color: #1e40af; padding: 2px 8px; border-radius: 4px; font-size: 10px; font-weight: 600;\">NEW</span>\n              </div>\n              <p style=\"font-size: 13px; margin: 0 0 12px 0; color: #6b7280; line-height: 1.5;\">\n                  Subscribe to real-time notifications when contacts change jobs or companies experience key business events.\n              </p>\n              <a href=\"#tag/Webhooks\" style=\"background: #2563eb; color: white; padding: 8px 16px; border-radius: 6px; text-decoration: none; font-size: 12px; font-weight: 600; display: inline-block; transition: all 0.2s;\">\n                  View Documentation →\n              </a>\n          </div>\n      </div>\n  </div>\n\n<script>\n    document.addEventListener('DOMContentLoaded', function() {\n        const details = document.querySelectorAll('details');\n        details.forEach(detail => {\n            detail.addEventListener('toggle', function() {\n                const summary = this.querySelector('summary');\n                if (summary) {\n                    if (this.open) {\n                        summary.innerHTML = '▼ Common Use Cases';\n                    } else {\n                        summary.innerHTML = '▶ Common Use Cases';\n                    }\n                }\n            });\n        });\n    });\n</script>\n\n---\n\n**<strong style=\"font-size: 1.2em; display: block; margin: 20px 0 10px 0;\">Data Source and Privacy</strong>**\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.

        '