{"openapi":"3.1.0","info":{"title":"FindLeadEmails API","version":"1.1.0","description":"Find and verify B2B work emails. A verified mailbox costs 1 credit. Catch-alls, misses, and repeat lookups are free. Contact hi@findleademails.com.","contact":{"email":"hi@findleademails.com","url":"https://www.findleademails.com/contact"},"termsOfService":"https://www.findleademails.com/legal/terms"},"servers":[{"url":"https://www.findleademails.com"}],"security":[{"apiKey":[]},{"bearer":[]}],"paths":{"/api/v1/email/find":{"post":{"operationId":"findEmail","summary":"Find one work email","description":"Find and verify one person's work email. Costs 1 credit only when the mailbox is verified.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Person"}}}},"responses":{"200":{"description":"Lookup result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinderResult"}}}},"400":{"description":"The name or company domain was rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or rejected credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The wallet cannot cover this call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-workspace rate limit or too many queued jobs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/verify":{"post":{"operationId":"verifyEmail","summary":"Verify one email address","description":"Check an address you already have. Costs 1 credit only when the mailbox is confirmed valid.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"email":{"type":"string","examples":["jane.doe@company.com"]}},"required":["email"]}}}},"responses":{"200":{"description":"Verification verdict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyResult"}}}},"400":{"description":"The address was rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or rejected credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The wallet cannot cover this call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-workspace rate limit or too many queued jobs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/bulk/find":{"post":{"operationId":"findEmailsBulk","summary":"Find emails in one synchronous batch","description":"Find and verify a batch in one request. The zod schema accepts up to 10,000 records. The route rejects a larger synchronous batch with 413 batch_too_large (the cap is lower when mailbox verification is enabled). Use POST /api/v1/jobs for a larger list.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"records":{"type":"array","minItems":1,"maxItems":10000,"items":{"$ref":"#/components/schemas/Person"}}},"required":["records"]}}}},"responses":{"200":{"description":"Per-row results and a summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkResult"}}}},"400":{"description":"The records were rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or rejected credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The wallet cannot cover this call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The batch is over the synchronous cap.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-workspace rate limit or too many queued jobs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/jobs":{"post":{"operationId":"createJob","summary":"Queue an async bulk job","description":"Reserves one credit per row up front and returns 202 with the job. Unused credits are refunded as rows resolve.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Optional key so a retry does not create a second job."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"records":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/Person"}},"name":{"type":"string","maxLength":200},"callback_url":{"type":"string","format":"uri","description":"Optional HTTPS URL notified when the job finishes."}},"required":["records"]}}}},"responses":{"202":{"description":"Job accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"The payload was rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or rejected credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The wallet cannot cover this call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The job has more rows than the workspace cap.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-workspace rate limit or too many queued jobs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Async jobs are not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listJobs","summary":"List recent jobs","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Recent jobs, newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"jobs":{"type":"array","items":{"$ref":"#/components/schemas/Job"}}},"required":["jobs"]}}}},"401":{"description":"Missing or rejected credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Async jobs are not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/jobs/{id}":{"get":{"operationId":"getJob","summary":"Read one job","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"401":{"description":"Missing or rejected credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No job with that id in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Async jobs are not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"renameJob","summary":"Rename a job","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200}},"required":["name"]}}}},"responses":{"200":{"description":"Updated job.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"401":{"description":"Missing or rejected credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No job with that id in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"cancelJob","summary":"Cancel a queued or running job","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Canceled job.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"401":{"description":"Missing or rejected credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No cancelable job with that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/jobs/{id}/results":{"get":{"operationId":"getJobResults","summary":"Page through a job's row results","description":"Readable while the job is still running. Pass next_cursor back as cursor until it is null.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}},{"name":"cursor","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"One page of results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResults"}}}},"401":{"description":"Missing or rejected credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No job with that id in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Async jobs are not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"FindLeadEmails API key from the Developers page."},"bearer":{"type":"http","scheme":"bearer","description":"The same API key as a bearer token."}},"schemas":{"Person":{"type":"object","additionalProperties":false,"properties":{"first_name":{"type":"string","minLength":1,"maxLength":120,"description":"Given name."},"last_name":{"type":"string","minLength":1,"maxLength":160,"description":"Family name."},"company_domain":{"type":"string","maxLength":300,"description":"Company website domain, such as company.com. Optional when company_linkedin_url is set."},"company_name":{"type":"string","maxLength":200,"description":"Company display name. Optional."},"linkedin_url":{"type":"string","maxLength":500,"description":"The person's LinkedIn profile URL. Stored for reference. Not used to find the address."},"company_linkedin_url":{"type":"string","maxLength":500,"description":"The company's LinkedIn page. Resolved to a domain only when company_domain is empty."}},"required":["first_name","last_name"]},"FinderResult":{"type":"object","properties":{"email":{"type":["string","null"],"examples":["jane.doe@company.com"]},"status":{"type":"string","enum":["verified","catch_all","predicted","not_found","insufficient_evidence","invalid_input","error"]},"verification_status":{"type":["string","null"],"enum":["valid","invalid","catch_all","unknown",null]},"confidence":{"type":"number"},"confidence_label":{"type":"string","enum":["LOW","MEDIUM","HIGH","VERY_HIGH"]},"needs_verification":{"type":"boolean"},"credits_used":{"type":"number"},"credits_remaining":{"type":"number"},"first_name":{"type":"string"},"last_name":{"type":"string"},"company_domain":{"type":"string"},"company_name":{"type":["string","null"]}},"required":["status"]},"VerifyResult":{"type":"object","properties":{"email":{"type":"string","examples":["jane.doe@company.com"]},"status":{"type":"string","enum":["valid","invalid","catch_all","unknown"]},"label":{"type":"string"},"explanation":{"type":"string"},"next_step":{"type":"string"},"repeat":{"type":"boolean"},"credits_used":{"type":"number"},"credits_remaining":{"type":["number","null"]}},"required":["email","status","credits_used"]},"BulkResult":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/FinderResult"}},"summary":{"type":"object","properties":{"total":{"type":"integer"},"found":{"type":"integer"},"verified":{"type":"integer"},"catch_all":{"type":"integer"},"verification_enabled":{"type":"boolean"},"credits_used":{"type":"number"},"credits_remaining":{"type":"number"}}}},"required":["results","summary"]},"Job":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"status":{"type":"string","enum":["queued","processing","completed","partial","failed","canceled"]},"job_type":{"type":"string"},"total_items":{"type":"integer"},"processed_items":{"type":"integer"},"successful_items":{"type":"integer"},"failed_items":{"type":"integer"},"verified_items":{"type":"integer"},"catch_all_items":{"type":"integer"},"predicted_items":{"type":"integer"},"not_found_items":{"type":"integer"},"credits_reserved":{"type":"number"},"credits_spent":{"type":"number"},"callback_url":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":["string","null"],"format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"error_message":{"type":["string","null"]}},"required":["id","status"]},"JobResults":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/Job"},"results":{"type":"array","items":{"type":"object","properties":{"position":{"type":"integer"},"status":{"type":"string"},"result":{"oneOf":[{"$ref":"#/components/schemas/FinderResult"},{"type":"null"}]},"error":{"type":["string","null"]}},"required":["position","status"]}},"next_cursor":{"type":["integer","null"]}},"required":["job","results","next_cursor"]},"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"required":{"type":"number"},"available":{"type":"number"},"retry_after_seconds":{"type":"integer"},"max_rows":{"type":"integer"},"limit":{"type":"integer"}},"required":["error"]}}}}