{"openapi":"3.1.0","info":{"title":"Evascrape API","version":"1.0.0","summary":"Start B2B lead extractions from Google Maps, Apollo.io and LinkedIn, and read the results as JSON.","description":"Evascrape turns a search description into a list of business contacts with verified email addresses.\n\nTypical agent flow: ask for a quote, start a job, poll its status, read the results as JSON.\nGoogle Maps is the fastest starting point: give a search term and a place, get businesses with\nphone, website, address and email where published.\n\nBilling is prepaid credits in USD. You are charged when the job starts and refunded automatically\nfor anything we could not deliver, so an over-estimate costs nothing extra.","contact":{"name":"Evascrape","url":"https://evascrape.com/contact"},"termsOfService":"https://evascrape.com/terms-of-service"},"servers":[{"url":"https://app.evascrape.com","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Jobs","description":"Start extractions and read results."},{"name":"Account","description":"Balance and key check."}],"paths":{"/api/v1/jobs":{"post":{"tags":["Jobs"],"operationId":"createJob","summary":"Start an extraction","description":"Charges your balance and starts the run. Returns immediately with a queued job.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"title":"Google Maps","type":"object","required":["source","list_name","total_records","search_terms","location"],"properties":{"source":{"type":"string","const":"google_maps"},"list_name":{"type":"string","maxLength":80,"description":"Used as the export file name.","example":"austin-dentists"},"total_records":{"type":"integer","description":"Maximum records to collect. Multiple of 100.","example":200},"email_verification":{"type":"boolean","default":false,"description":"Adds real-time email verification for $5 per 1,000."},"callback_url":{"type":"string","format":"uri","description":"Optional https endpoint. We POST the job object here when it finishes, signed with X-Evascrape-Signature (HMAC-SHA256 of the raw body).","example":"https://hooks.example.com/evascrape"},"search_terms":{"type":"string","description":"Comma separated business categories.","example":"dentist, orthodontist"},"location":{"type":"string","description":"City, region or country.","example":"Austin, Texas"},"language":{"type":"string","default":"en","example":"en"},"min_rating":{"type":"string","enum":["","3","3.5","4","4.5"],"default":""},"categories":{"type":"string","description":"Optional extra category filter."},"skip_closed":{"type":"boolean","default":false,"description":"Skip permanently closed places."}}},{"title":"Apollo.io","type":"object","required":["source","list_name","total_records","apollo_url"],"properties":{"source":{"type":"string","const":"apollo"},"list_name":{"type":"string","maxLength":80,"description":"Used as the export file name.","example":"austin-dentists"},"total_records":{"type":"integer","description":"Maximum records to collect. Multiple of 100.","example":200},"email_verification":{"type":"boolean","default":false,"description":"Adds real-time email verification for $5 per 1,000."},"callback_url":{"type":"string","format":"uri","description":"Optional https endpoint. We POST the job object here when it finishes, signed with X-Evascrape-Signature (HMAC-SHA256 of the raw body).","example":"https://hooks.example.com/evascrape"},"apollo_url":{"type":"string","format":"uri","description":"A people search URL copied from Apollo.io.","example":"https://app.apollo.io/#/people?personTitles[]=cto&organizationLocations[]=Germany"}}},{"title":"LinkedIn","type":"object","required":["source","list_name","total_records"],"description":"LinkedIn uses filters, not a search URL. Give at least one filter.","properties":{"source":{"type":"string","const":"linkedin"},"list_name":{"type":"string","maxLength":80,"description":"Used as the export file name.","example":"austin-dentists"},"total_records":{"type":"integer","description":"Maximum records to collect. Multiple of 100.","example":200},"email_verification":{"type":"boolean","default":false,"description":"Adds real-time email verification for $5 per 1,000."},"callback_url":{"type":"string","format":"uri","description":"Optional https endpoint. We POST the job object here when it finishes, signed with X-Evascrape-Signature (HMAC-SHA256 of the raw body).","example":"https://hooks.example.com/evascrape"},"contact_job_title":{"type":"string","description":"Comma separated job titles to include.","example":"Head of Marketing, CMO"},"contact_not_job_title":{"type":"string","description":"Job titles to exclude."},"contact_location":{"type":"array","items":{"type":"string"},"description":"Regions or countries from a fixed list, lowercase. US states end in \", us\" (\"california, us\"); other regions in \", <country>\" (\"bavaria, germany\"); or a bare country name (\"germany\"). Unknown values are rejected.","example":["california, us"]},"contact_not_location":{"type":"array","items":{"type":"string"}},"seniority_level":{"type":"array","items":{"type":"string"},"example":["c_suite","director"]},"functional_level":{"type":"array","items":{"type":"string"},"example":["marketing"]},"company_domain":{"type":"string","description":"Comma separated domains, e.g. stripe.com. Domains, not company names."},"company_industry":{"type":"array","items":{"type":"string"}},"company_not_industry":{"type":"array","items":{"type":"string"}},"company_keywords":{"type":"string"},"company_not_keywords":{"type":"string"},"size":{"type":"array","items":{"type":"string"},"example":["51-100","101-200"]},"min_revenue":{"type":"string","example":"1M"},"max_revenue":{"type":"string","example":"50M"},"funding":{"type":"array","items":{"type":"string"},"example":["series_a"]},"include_unverified":{"type":"boolean","default":false,"description":"Include people whose email is not yet verified. Raises volume a lot; most under-delivery comes from leaving this off."}}}]},"examples":{"googleMaps":{"summary":"Dentists in Austin","value":{"source":"google_maps","list_name":"austin-dentists","total_records":200,"search_terms":"dentist","location":"Austin, Texas"}},"apollo":{"summary":"Apollo search URL","value":{"source":"apollo","list_name":"german-ctos","total_records":1000,"apollo_url":"https://app.apollo.io/#/people?personTitles[]=cto"}},"linkedin":{"summary":"LinkedIn filters","value":{"source":"linkedin","list_name":"saas-cmos","total_records":500,"contact_job_title":"CMO","contact_location":["california, us"],"include_unverified":true}}}}}},"responses":{"202":{"description":"Job accepted and charged.","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","properties":{"id":{"type":"integer","example":1421},"status":{"type":"string","enum":["queued","running","succeeded","failed","no_results"],"description":"Poll until this is succeeded, failed or no_results."},"source":{"type":"string","enum":["google_maps","apollo","linkedin"]},"list_name":{"type":"string"},"requested_records":{"type":"integer","description":"What you asked for. This is a maximum."},"delivered_records":{"type":["integer","null"],"description":"What we actually found."},"records_with_email":{"type":["integer","null"],"description":"Rows carrying an email address. Rows without one are billed at a lower rate."},"email_verification":{"type":"boolean"},"verification_status":{"type":"string","enum":["none","pending","completed","failed"]},"credits_charged":{"type":"string","example":"2.40","description":"USD, charged up front."},"credits_refunded":{"type":"string","example":"0.36","description":"USD returned for records we could not deliver."},"error":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"results":{"type":"object","properties":{"available":{"type":"boolean"},"variants":{"type":"array","items":{"type":"string","enum":["all","good","risk","bad"]},"description":"good/risk/bad appear only when email verification was enabled and finished."},"url":{"type":["string","null"]}}}}}}}}}},"400":{"description":"Validation failed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable code.","enum":["missing_credentials","invalid_api_key","invalid_request","insufficient_credits","not_found","not_ready","too_large","file_gone","rate_limited","storage_unavailable","upstream_unavailable","temporarily_unavailable"]},"message":{"type":"string","description":"Human-readable explanation, safe to show to a user."}}}}}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable code.","enum":["missing_credentials","invalid_api_key","invalid_request","insufficient_credits","not_found","not_ready","too_large","file_gone","rate_limited","storage_unavailable","upstream_unavailable","temporarily_unavailable"]},"message":{"type":"string","description":"Human-readable explanation, safe to show to a user."}}}}}}}},"402":{"description":"Not enough credits.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable code.","enum":["missing_credentials","invalid_api_key","invalid_request","insufficient_credits","not_found","not_ready","too_large","file_gone","rate_limited","storage_unavailable","upstream_unavailable","temporarily_unavailable"]},"message":{"type":"string","description":"Human-readable explanation, safe to show to a user."}}}}}}}},"429":{"description":"Rate limited: 20 job starts per minute.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable code.","enum":["missing_credentials","invalid_api_key","invalid_request","insufficient_credits","not_found","not_ready","too_large","file_gone","rate_limited","storage_unavailable","upstream_unavailable","temporarily_unavailable"]},"message":{"type":"string","description":"Human-readable explanation, safe to show to a user."}}}}}}}}}},"get":{"tags":["Jobs"],"operationId":"listJobs","summary":"List recent jobs","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"Your most recent jobs.","content":{"application/json":{"schema":{"type":"object","properties":{"jobs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":1421},"status":{"type":"string","enum":["queued","running","succeeded","failed","no_results"],"description":"Poll until this is succeeded, failed or no_results."},"source":{"type":"string","enum":["google_maps","apollo","linkedin"]},"list_name":{"type":"string"},"requested_records":{"type":"integer","description":"What you asked for. This is a maximum."},"delivered_records":{"type":["integer","null"],"description":"What we actually found."},"records_with_email":{"type":["integer","null"],"description":"Rows carrying an email address. Rows without one are billed at a lower rate."},"email_verification":{"type":"boolean"},"verification_status":{"type":"string","enum":["none","pending","completed","failed"]},"credits_charged":{"type":"string","example":"2.40","description":"USD, charged up front."},"credits_refunded":{"type":"string","example":"0.36","description":"USD returned for records we could not deliver."},"error":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"results":{"type":"object","properties":{"available":{"type":"boolean"},"variants":{"type":"array","items":{"type":"string","enum":["all","good","risk","bad"]},"description":"good/risk/bad appear only when email verification was enabled and finished."},"url":{"type":["string","null"]}}}}}}}}}}}}}},"/api/v1/jobs/{id}":{"get":{"tags":["Jobs"],"operationId":"getJob","summary":"Get job status","description":"Poll this every 20 to 30 seconds. Most jobs finish in a few minutes.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Job state.","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","properties":{"id":{"type":"integer","example":1421},"status":{"type":"string","enum":["queued","running","succeeded","failed","no_results"],"description":"Poll until this is succeeded, failed or no_results."},"source":{"type":"string","enum":["google_maps","apollo","linkedin"]},"list_name":{"type":"string"},"requested_records":{"type":"integer","description":"What you asked for. This is a maximum."},"delivered_records":{"type":["integer","null"],"description":"What we actually found."},"records_with_email":{"type":["integer","null"],"description":"Rows carrying an email address. Rows without one are billed at a lower rate."},"email_verification":{"type":"boolean"},"verification_status":{"type":"string","enum":["none","pending","completed","failed"]},"credits_charged":{"type":"string","example":"2.40","description":"USD, charged up front."},"credits_refunded":{"type":"string","example":"0.36","description":"USD returned for records we could not deliver."},"error":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"results":{"type":"object","properties":{"available":{"type":"boolean"},"variants":{"type":"array","items":{"type":"string","enum":["all","good","risk","bad"]},"description":"good/risk/bad appear only when email verification was enabled and finished."},"url":{"type":["string","null"]}}}}}}}}}},"404":{"description":"No job with that id.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable code.","enum":["missing_credentials","invalid_api_key","invalid_request","insufficient_credits","not_found","not_ready","too_large","file_gone","rate_limited","storage_unavailable","upstream_unavailable","temporarily_unavailable"]},"message":{"type":"string","description":"Human-readable explanation, safe to show to a user."}}}}}}}}}}},"/api/v1/jobs/{id}/results":{"get":{"tags":["Jobs"],"operationId":"getJobResults","summary":"Read results","description":"JSON by default, which is what most agents want. Use format=csv for the raw file.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"],"default":"json"}},{"name":"variant","in":"query","schema":{"type":"string","enum":["all","good","risk","bad"],"default":"all"},"description":"good/risk/bad exist only with email verification."},{"name":"limit","in":"query","schema":{"type":"integer","default":1000,"maximum":10000}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Records.","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"integer"},"variant":{"type":"string"},"total":{"type":"integer"},"offset":{"type":"integer"},"limit":{"type":"integer"},"has_more":{"type":"boolean"},"fields":{"type":"array","items":{"type":"string"}},"records":{"type":"array","items":{"type":"object","additionalProperties":{"type":"string"}}}}}},"text/csv":{"schema":{"type":"string"}}}},"409":{"description":"Job has not finished yet.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable code.","enum":["missing_credentials","invalid_api_key","invalid_request","insufficient_credits","not_found","not_ready","too_large","file_gone","rate_limited","storage_unavailable","upstream_unavailable","temporarily_unavailable"]},"message":{"type":"string","description":"Human-readable explanation, safe to show to a user."}}}}}}}},"413":{"description":"Too large for JSON; use format=csv.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable code.","enum":["missing_credentials","invalid_api_key","invalid_request","insufficient_credits","not_found","not_ready","too_large","file_gone","rate_limited","storage_unavailable","upstream_unavailable","temporarily_unavailable"]},"message":{"type":"string","description":"Human-readable explanation, safe to show to a user."}}}}}}}}}}},"/api/v1/quote":{"post":{"tags":["Jobs"],"operationId":"quote","summary":"Price a job before starting it","description":"Costs nothing and changes nothing. Useful before spending a customer balance.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["source","total_records"],"properties":{"source":{"type":"string","enum":["google_maps","apollo","linkedin"]},"total_records":{"type":"integer","example":200},"email_verification":{"type":"boolean","default":false}}},"example":{"source":"google_maps","total_records":200}}}},"responses":{"200":{"description":"Estimated cost.","content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string"},"total_records":{"type":"integer"},"email_verification":{"type":"boolean"},"cost":{"type":"object","properties":{"base":{"type":"string"},"verification":{"type":"string"},"total":{"type":"string"}}},"currency":{"type":"string"},"note":{"type":"string"}}}}}}}}},"/api/v1/balance":{"get":{"tags":["Account"],"operationId":"getBalance","summary":"Get credit balance","responses":{"200":{"description":"Balance in USD.","content":{"application/json":{"schema":{"type":"object","properties":{"credits":{"type":"string","example":"42.10"},"currency":{"type":"string","example":"USD"}}}}}}}}},"/api/v1/me":{"get":{"tags":["Account"],"operationId":"getMe","summary":"Check the API key","description":"Returns the account the key belongs to. Use it to confirm a key works.","responses":{"200":{"description":"Account and balance.","content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"object","properties":{"id":{"type":"integer"},"email":{"type":"string"},"name":{"type":"string"}}},"balance":{"type":"object","properties":{"credits":{"type":"string"},"currency":{"type":"string"}}}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Create a key at https://app.evascrape.com/account/api-keys and send it as: Authorization: Bearer evs_live_..."}},"schemas":{"Job":{"type":"object","properties":{"id":{"type":"integer","example":1421},"status":{"type":"string","enum":["queued","running","succeeded","failed","no_results"],"description":"Poll until this is succeeded, failed or no_results."},"source":{"type":"string","enum":["google_maps","apollo","linkedin"]},"list_name":{"type":"string"},"requested_records":{"type":"integer","description":"What you asked for. This is a maximum."},"delivered_records":{"type":["integer","null"],"description":"What we actually found."},"records_with_email":{"type":["integer","null"],"description":"Rows carrying an email address. Rows without one are billed at a lower rate."},"email_verification":{"type":"boolean"},"verification_status":{"type":"string","enum":["none","pending","completed","failed"]},"credits_charged":{"type":"string","example":"2.40","description":"USD, charged up front."},"credits_refunded":{"type":"string","example":"0.36","description":"USD returned for records we could not deliver."},"error":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"results":{"type":"object","properties":{"available":{"type":"boolean"},"variants":{"type":"array","items":{"type":"string","enum":["all","good","risk","bad"]},"description":"good/risk/bad appear only when email verification was enabled and finished."},"url":{"type":["string","null"]}}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable code.","enum":["missing_credentials","invalid_api_key","invalid_request","insufficient_credits","not_found","not_ready","too_large","file_gone","rate_limited","storage_unavailable","upstream_unavailable","temporarily_unavailable"]},"message":{"type":"string","description":"Human-readable explanation, safe to show to a user."}}}}}}}}