> ## Documentation Index > Fetch the complete documentation index at: https://docs.sendler.ai/llms.txt > Use this file to discover all available pages before exploring further. # Start Lead Database Search > Start a paid background search and retain its job ID for polling. Requires `lead_sourcing:run` and the creator's `ALLOW_LEAD_FINDER` workspace permission. Supply `name`, `filters`, and `limit` (at least 1). The generated filter schema defines supported job, person, company, technology and experience fields. Use [Discover Lead Filters](https://docs.sendler.ai/api-reference/endpoint/get-lead-filters.md) for current schemas and values before creating a search. `industries` is mapped to `experimental_industries` at the provider boundary; exclusions and department aliases are preserved. SIC/NAICS code objects are converted to their code values for the provider. Removed/unknown filters and conflicting aliases fail validation rather than being silently discarded. `job_title_match_mode` accepts `exact`, `contains` or `smart`; `job_title_smart_mode` is used with `smart`. `is_mapped_industries_strict` controls exact versus related industry matching. Date filters accept the documented `dd/mm/yyyy` form and existing ISO date input. Use integers for numeric criteria and at most 100 entries per array filter. Matching controls alone do not restrict a search: include an actual criterion such as job titles, locations or industries. If a previous attempt failed definitively, its idempotency result can still be cached; treat a corrected attempt as a new operation only after checking the original outcome. Never use a new key to bypass an uncertain submission. The search reserves **2 credits per requested lead**; unused credits are returned on completion. REST has no fixed lead-count ceiling in this DTO beyond available credits; the MCP search tool separately limits requests to 1,000 leads. The response's `id` is the search job ID, not a campaign ID. Save it and [poll status](https://docs.sendler.ai/api-reference/endpoint/get-lead-database-search-status.md), then [read results](https://docs.sendler.ai/api-reference/endpoint/get-lead-database-search-results.md). Do not start another paid search merely because the first is still processing. `webhook_url` is an optional public HTTPS completion destination. Use an [Idempotency-Key](https://docs.sendler.ai/api-reference/behavior.md#idempotent-writes) for retryable creation. ## OpenAPI ````yaml POST /v1/lead-database/searches openapi: 3.0.0 info: title: SendPilot External API description: > # SendPilot External API v1 Public API for integrating with SendPilot programmatically. ## Authentication Requests authenticate with a workspace API key in the `X-API-Key` header: ``` X-API-Key: sp_live_your_api_key_here ``` `Authorization: Bearer sp_live_...` (or `sp_test_...`) is also accepted. Prefer one header; `X-API-Key` takes precedence. Clerk OAuth tokens for MCP connection URLs are not public REST API keys. A key only reaches what its scopes and creator's current workspace permissions allow. Each operation lists the scopes it needs in `x-sp-scopes`. Use `GET /v1/me` to inspect the effective permissions and subscription state. ## Rate Limits - **Per API Key**: 300 requests/minute - **Per Workspace**: 50,000 requests/day Responses that reach the rate limiter include these headers; early authentication failures may not: - `X-RateLimit-Limit`: Max requests per minute - `X-RateLimit-Remaining`: Remaining requests in current window - `X-RateLimit-Reset`: Epoch timestamp when limit resets ## LinkedIn Sender Limits When using messaging endpoints, these headers show account limits: - `X-LinkedIn-Messages-Remaining`: Messages left today - `X-LinkedIn-Connections-Remaining`: Connection requests left today - `X-LinkedIn-Quota-Reset-At`: When daily limits reset ## Retries Send an `Idempotency-Key` header on POST and PATCH requests. A retry with the same key within 24 hours returns the first result (with `Idempotent-Replayed: true`) instead of acting twice. The same key with a different request answers 422 `IDEMPOTENCY_KEY_REUSED`; a retry while the first request still runs answers 409 `IDEMPOTENCY_IN_PROGRESS`. Once execution is attempted, its response (including errors) is retained. If a process stops or result storage fails after the attempt, the durable record blocks another execution for the replay window and returns 409 `IDEMPOTENCY_IN_PROGRESS` or `IDEMPOTENCY_REPLAY_UNAVAILABLE`. Check the operation's status before using a new key: an uncertain outcome may already have acted. Requests refused before execution is claimed, such as authentication or rate-limit refusals, can be retried with the same key. ## Webhooks Configure webhooks in the SendPilot app to receive real-time events: - `lead.tag.updated` - `lead.updated` - `message.sent` - `reply.received` - `connection_request.sent` - `connection_request.accepted` - `campaign.started` - `campaign.paused` - `campaign.resumed` - `campaign.finished` ## Error Codes Errors return a JSON body. Use the machine-readable `code` when supplied; validation messages can be arrays, and some legacy errors omit `code`. A typical error is: ```json { "statusCode": 400, "error": "Bad Request", "code": "SPECIFIC_ERROR_CODE", "message": "Human-readable description" } ``` version: '1.0' contact: name: SendPilot Support url: https://sendpilot.ai email: support@sendpilot.ai servers: - url: https://api.sendpilot.ai security: [] tags: [] paths: /v1/lead-database/searches: post: tags: - External API - Lead Database summary: Create a lead database search description: >- Initiates a new lead database search with the specified filters and limit operationId: leadDatabase.startSearch parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateLeadDatabaseSearchDto' responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/CreateLeadDatabaseSearchResponseDto' '401': description: Invalid or missing API key '403': description: Insufficient quota '429': description: Rate limit exceeded '500': description: Internal server error security: - api-key: [] components: schemas: CreateLeadDatabaseSearchDto: type: object properties: name: type: string description: Search name filters: type: object additionalProperties: false minProperties: 1 properties: member_full_name: description: Person name search. type: string minLength: 1 maxLength: 2000 job_titles: description: Current job titles. Use the filter catalog for suggested values. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 excluded_job_titles: description: Job titles to exclude. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 job_title_match_mode: description: >- Job-title matching: exact, contains (provider default), or smart. type: string minLength: 1 maxLength: 2000 enum: - exact - contains - smart job_title_smart_mode: description: Sensitivity when job_title_match_mode is smart. type: string minLength: 1 maxLength: 2000 enum: - loose - normal - strict member_skills: description: Profile skills. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 excluded_member_skills: description: Profile skills to exclude. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 member_linkedin_username: description: LinkedIn usernames or profile URLs. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 excluded_member_linkedin_username: description: LinkedIn usernames or profile URLs to exclude. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 locations: description: Person country, region or city. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 excluded_locations: description: Person locations to exclude. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 member_description: description: Keywords in profile summaries. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 excluded_member_description: description: Profile-summary keywords to exclude. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 seniority_levels: description: >- Seniority level; use exact catalog values, e.g. C-Level or President/Vice President. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 enum: - Specialist - Manager - Owner - Founder - President/Vice President - Director - Senior - Head - C-Level - Partner - Intern excluded_seniority_levels: description: Seniority levels to exclude. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 enum: - Specialist - Manager - Owner - Founder - President/Vice President - Director - Senior - Head - C-Level - Partner - Intern member_department: description: Departments; mapped to the supported provider department filter. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 excluded_member_department: description: Departments to exclude. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 member_certifications: description: Professional certifications. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 excluded_member_certifications: description: Certifications to exclude. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 min_total_experience_duration_months: description: Minimum total experience in months. type: integer minimum: 0 max_total_experience_duration_months: description: Maximum total experience in months. type: integer minimum: 0 min_job_duration_months: description: Minimum time in the current job, in months. type: integer minimum: 0 max_job_duration_months: description: Maximum time in the current job, in months. type: integer minimum: 0 companies: description: Company names. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 excluded_companies: description: Company names to exclude. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 bulk_domains: description: Company domains separated by commas or newlines. type: string minLength: 1 maxLength: 2000 excluded_bulk_domains: description: Company domains to exclude, separated by commas or newlines. type: string minLength: 1 maxLength: 2000 company_linkedin_username: description: Company LinkedIn usernames or URLs. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 excluded_company_linkedin_username: description: Company LinkedIn usernames or URLs to exclude. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 company_type: description: Company types. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 enum: - Privately Held - Public Company - Self-Owned - Partnership - Self-Employed - Nonprofit - Educational - Government Agency excluded_company_type: description: Company types to exclude. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 enum: - Privately Held - Public Company - Self-Owned - Partnership - Self-Employed - Nonprofit - Educational - Government Agency industries: description: >- Company industries. Uses the supported experimental_industries provider field; query the catalog for values. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 excluded_industries: description: Industries to exclude. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 is_mapped_industries_strict: description: >- True requires exact industry matching; false lets the provider match related industries. type: boolean company_sizes: description: Employee-size ranges. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 enum: - '1' - 2-10 - 11-50 - 51-200 - 201-500 - 501-1000 - 1001-5000 - 5001-10000 - 10001+ excluded_company_sizes: description: >- Employee-size codes to exclude, from 1 (one employee) to 9 (10001+). type: array minItems: 1 maxItems: 100 items: type: integer enum: - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 - 9 hq_location: description: Company headquarters locations. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 excluded_hq_location: description: Headquarters locations to exclude. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 sic_codes: description: >- SIC code objects from the catalog. Only each value is sent to the provider. type: array minItems: 1 maxItems: 100 items: type: object properties: label: type: string minLength: 1 maxLength: 2000 value: type: string minLength: 1 maxLength: 2000 required: - label - value additionalProperties: false excluded_sic_codes: description: SIC code strings to exclude. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 naics_codes: description: >- NAICS code objects from the catalog. Only each value is sent to the provider. type: array minItems: 1 maxItems: 100 items: type: object properties: label: type: string minLength: 1 maxLength: 2000 value: type: string minLength: 1 maxLength: 2000 required: - label - value additionalProperties: false excluded_naics_codes: description: NAICS code strings to exclude. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 keywords: description: Keywords in company descriptions or specialties. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 excluded_keywords: description: Company keywords to exclude. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 last_funding_round_name: description: Latest funding-round types. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 enum: - Seed Round - Pre Seed Round - Venture Round - Series A - Grant - Non Equity Assistance - Private Equity Round - Series B - Angel Round - Debt Financing - Post-IPO Equity - Series C - Corporate Round - Equity Crowdfunding - Funding Round - Convertible Note - Post-IPO Debt - Series D - Secondary Market - Post-IPO Secondary - Initial Coin Offering - Product Crowdfunding - Series E - Series F - Series G - Series H ownership_status: description: Company ownership status. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 enum: - Private - Public - Investment Company - NGO/NPO/NFP/Organization/Association - Government - Product/Brand/Service - SPAC min_last_funding_round_amount_raised: description: Minimum latest funding amount. type: integer minimum: 0 max_last_funding_round_amount_raised: description: Maximum latest funding amount. type: integer minimum: 0 ipo_start_date: description: IPO date range start, dd/mm/yyyy. type: string minLength: 1 maxLength: 2000 ipo_end_date: description: IPO date range end, dd/mm/yyyy. type: string minLength: 1 maxLength: 2000 acquired_start_date: description: Acquisition date range start, dd/mm/yyyy. type: string minLength: 1 maxLength: 2000 acquired_end_date: description: Acquisition date range end, dd/mm/yyyy. type: string minLength: 1 maxLength: 2000 min_revenue_annual: description: Minimum annual revenue. type: integer minimum: 0 max_revenue_annual: description: Maximum annual revenue. type: integer minimum: 0 min_total_website_visits_monthly: description: Minimum monthly website visits. type: integer minimum: 0 max_total_website_visits_monthly: description: Maximum monthly website visits. type: integer minimum: 0 min_rank_global: description: Minimum global website rank. type: integer minimum: 0 max_rank_global: description: Maximum global website rank. type: integer minimum: 0 min_rank_country: description: Minimum website rank within its country. type: integer minimum: 0 max_rank_country: description: Maximum website rank within its country. type: integer minimum: 0 min_rank_category: description: Minimum website rank within its category. type: integer minimum: 0 max_rank_category: description: Maximum website rank within its category. type: integer minimum: 0 min_bounce_rate: description: Minimum bounce-rate percentage. type: integer minimum: 0 maximum: 100 max_bounce_rate: description: Maximum bounce-rate percentage. type: integer minimum: 0 maximum: 100 min_pages_per_visit: description: Minimum average pages per visit. type: integer minimum: 0 max_pages_per_visit: description: Maximum average pages per visit. type: integer minimum: 0 min_average_visit_duration_seconds: description: Minimum visit duration in seconds. type: integer minimum: 0 max_average_visit_duration_seconds: description: Maximum visit duration in seconds. type: integer minimum: 0 top_topics: description: Topics covered by the company website. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 excluded_top_topics: description: Website topics to exclude. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 technologies_used: description: Technologies used by the company. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 excluded_technologies_used: description: Company technologies to exclude. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 pricing_available: description: Company publishes pricing. type: boolean demo_available: description: Company offers a demo. type: boolean documentation_exist: description: Company provides documentation. type: boolean free_trial_available: description: Company offers a free trial. type: boolean is_downloadable: description: Company offers downloadable software/resources. type: boolean mobile_apps_exist: description: Company has mobile apps. type: boolean online_reviews_exist: description: Company has online reviews. type: boolean min_company_employee_reviews_aggregate_score: description: Minimum employee-review score. type: integer minimum: 0 max_company_employee_reviews_aggregate_score: description: Maximum employee-review score. type: integer minimum: 0 job_posting_title: description: Job titles the company is recruiting. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 excluded_job_posting_title: description: Recruiting titles to exclude. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 job_posting_location: description: Job posting locations. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 excluded_job_posting_location: description: Job posting locations to exclude. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 excluded_job_posting_functions: description: Job functions to exclude. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 job_posting_start_date: description: Job posting date range start, dd/mm/yyyy. type: string minLength: 1 maxLength: 2000 job_posting_end_date: description: Job posting date range end, dd/mm/yyyy. type: string minLength: 1 maxLength: 2000 job_posting_type: description: Employment types. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 enum: - Full-time - Part-time - Contract - Internship - Volunteer - Temporary - Other job_posting_seniority: description: Recruiting seniority levels. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 enum: - Entry level - Internship - Associate - Mid-Senior level - Director - Executive - Not Applicable experimental_industries: description: >- Compatibility alias for industries; do not supply both with different values. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 deprecated: true excluded_experimental_industries: description: >- Compatibility alias for excluded_industries; do not supply both with different values. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 deprecated: true experimental_member_department: description: >- Compatibility alias for member_department; do not supply both with different values. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 deprecated: true excluded_experimental_department: description: >- Compatibility alias for excluded_member_department; do not supply both with different values. type: array minItems: 1 maxItems: 100 items: type: string minLength: 1 maxLength: 2000 deprecated: true limit: type: number description: Maximum leads to find (no hard limit - capped by available credits) minimum: 1 webhook_url: type: string description: >- HTTPS URL to receive a completion notification. Must be a public host. example: https://my-app.example.com/webhooks/sendpilot required: - name - filters - limit CreateLeadDatabaseSearchResponseDto: type: object properties: id: type: string name: type: string status: type: string created_at: type: string estimated_quota: type: number description: Quota to be consumed required: - id - name - status - created_at - estimated_quota securitySchemes: api-key: type: apiKey in: header name: X-API-Key description: 'API key for authentication (prefix: sp_live_ or sp_test_)' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.