Developers
Glintscout API reference
Everything you do in a project also works over a REST API: create a project, find businesses, find and check their emails, follow each step and download the CSV. Calls cost the same credits as the app and get the same automatic returns.
This page lists the endpoints we support for scripts and integrations. The app calls other paths too; those can change without notice, so build only on the ones below.
- Base URL
https://glintscout.com/api- Authentication
Authorization: Bearer <key>- Format
- JSON in and out (send Accept: application/json); the export is a CSV file.
- Credits
- As in the app: 1 per new company, 6 per email that passes the check.
API keys
A key acts as your account, so keep it secret. Send it in the Authorization header of every call.
- Create a key in Settings, under API keys, once your email address is confirmed. Give it a name; the key is shown once, when you create it.
- A key works until you revoke it in Settings, and a revoked key stops at once. You can hold up to 20 keys.
- A key reaches only your own projects: another account's project or step answers 404.
- A few account actions need you signed in on the site rather than a key: creating or revoking keys, your password and email preferences, plans and payments, and connecting Instantly. A key gets 403 needs_browser_session there.
curl -s https://glintscout.com/api/projects \
-H "Authorization: Bearer $KEY" -H "Accept: application/json"Quick start
From nothing to a CSV of checked emails. Set KEY to your key and API to https://glintscout.com/api; every call below also sends -H "Authorization: Bearer $KEY" -H "Accept: application/json", left out to keep the lines short.
- Look up niches and sources. GET /projects/create-data lists the niches (id and name), the sources with the countries they cover and whether they are paused, the contact modes and the email rules per country.
curl -s "$API/projects/create-data" - Pick the cities. GET /cities/{country} lists a country's built-in cities with their ids (lowercase code; the United Kingdom is uk). For any other place, search it with GET /places/search and add it with POST /cities: the answer is the city with its id.
curl -s "$API/cities/uk" curl -s "$API/places/search?country=uk&q=Leeds" curl -s -X POST "$API/cities" -H "Content-Type: application/json" \ -d '{"geo_place_id": 2643123, "country_code": "uk"}' - Create the project. POST /projects with the country, the niche ids and the city ids. It answers 201 with the project's id.
curl -s -X POST "$API/projects" -H "Content-Type: application/json" -d '{ "name": "Leeds roofers", "country": "United Kingdom", "country_code": "uk", "niche_ids": [12], "city_ids": [345], "contact_mode": "email" }' # {"message":"Project created!","id":42} - Find the companies. POST /projects/{id}/scrape starts the search: one search per city and niche, up to max_results companies each. The answer names the step (process_id) and the credits it holds.
curl -s -X POST "$API/projects/42/scrape" -H "Content-Type: application/json" \ -d '{"max_results": 20}' # {"message":"Company search started ...","process_id":1042,"held":...,"price":{...}} - Follow the step. Ask GET /processes/{id}/status every few seconds until status is completed, failed or cancelled.
curl -s "$API/processes/1042/status" # {"id":1042,"process_type":"scrape","status":"running","total":1,"processed":0,"progress":0,...} - Find and check the emails. POST /projects/{id}/find-emails looks for emails on each company's own website and checks every address it finds. Follow its process_id the same way.
curl -s -X POST "$API/projects/42/find-emails" - Download the CSV. GET /projects/{id}/export gives the valid emails you have not downloaded yet (add all=1 for every valid one). With curl's -f, a 422 "nothing to download" does not end up in the file.
curl -sf "$API/projects/42/export" -o contacts.csv
Endpoints
All paths are relative to https://glintscout.com/api. Each answer is JSON unless it says otherwise.
Projects
GET
/projectsYour projects, newest first, each with its counts: companies_count, contacts_count, verified_count (valid emails), pending_count, to_search_count (companies not searched for emails yet) and phones_count.
Returns: a JSON array (no pages).
GET
/projects/create-dataWhat a new project can use: niches, countries, the sources (strategies, with key, countries and paused), contact_modes, search_price and email_policy (the email rules per country).
POST
/projectsCreate a project.
Send: name (required); country (required, the country's name); country_code (required, 2 or 3 letters, uk for the United Kingdom); niche_ids (required, at least one); city_ids (needed by the google_maps and yellow_pages sources); strategy (the source, default google_maps; yellow_pages covers the US only); contact_mode (email, phone or both, default email); description; city_scopes (optional, per city id: scope city, metro or radius, with radius_km 10, 25 or 50).
Returns: 201 {message, id}.
GET
/projects/{id}One project: project (with its niches and cities), contactStats (valid, catch_all, invalid, unknown, pending, exported), funnel (companies, with_website, emails_found, valid, catch_all, unknown, invalid, pending and more), runningProcesses, recentProcesses and the first 25 contacts.
PUT
/projects/{id}Change a project. The same fields as POST; name, country, country_code and niche_ids are required on every change, and niche_ids and city_ids replace the old lists.
Returns: {message}; 409 step_running if contact_mode changes while a step runs.
DELETE
/projects/{id}Delete a project with its companies and contacts. Refused with 409 while a step runs.
Cities and places
GET
/cities/{country}A country's built-in cities and the ones you added, with their ids, sorted by name.
GET
/places/search?country=uk&q=LeedsPlaces that match a name (each with its geo_id), or the main ones without q. Where place search is not on for a country, available is false.
Limit: 90 a minute.
POST
/citiesThe city to put in city_ids.
Send: {geo_place_id, country_code} for a place from the search, or {name, country_code} for a city by name. A name with extra words ("roofers leeds") answers 422 city_suggestion with the city it holds; send confirm: true to keep your own name.
Returns: the city, with its id.
Steps
Each step runs on our side; you can disconnect and come back. One step at a time per project.
POST
/projects/{id}/scrapeFind companies for the project's cities and niches.
Send: max_results (companies per search, 1 to 100, default 20); source (optional: another source than the project's).
Returns: {message, process_id, held, price}.
Limit: 30 step starts a minute, shared by all steps.
POST
/projects/{id}/find-emailsFind emails on the companies' own websites and check each address found.
Send: max_companies (optional, 1 to 100,000: only the first companies not searched yet).
Returns: {message, process_id, held, ...}.
POST
/projects/{id}/verifyCheck the emails of this project that are still waiting for a check. No body.
Returns: {message, process_id, held, reused}; when every address already has a recent result, process_id is null and valid, catch_all and invalid give the answer at once.
GET
/processes/{id}/statusA step's state and progress (see Following a step).
Limit: 120 a minute.
POST
/processes/{id}/stopStop a running step. What it found so far is kept and charged; the rest of the held credits comes back.
Returns: 200 {message, refunded} when stopped, 202 {message} while it winds down, 409 when it has already ended.
Results
GET
/projects/{id}/companiesThe project's companies, newest first, in pages (see Results).
GET
/projects/{id}/contactsThe project's email contacts, newest first, in pages (see Results).
GET
/projects/{id}/exportThe CSV of valid emails not downloaded yet; all=1 gives every valid one. A project that collects phones only gives its phone list instead.
Returns: a CSV file, or 422 nothing_to_do when there is nothing to download.
Instantly
Connect your Instantly key in Settings first (signed in on the site). Sending needs a Ridge or Summit plan and costs no credits.
GET
/integrations/instantly/campaignsYour Instantly campaigns, to pick a campaign_id.
Limit: 20 a minute.
POST
/projects/{id}/instantly/pushesSend the project's contacts to one of your Instantly campaigns.
Send: campaign_id (required, the campaign's id); verdicts (valid, catch-all or both); only_new (default true: contacts not sent before); skip_existing (none, campaigns or workspace).
Returns: 202 {message, notice, push} with the send's id, status, total, processed, added, skipped and failed.
Limit: 6 a minute.
GET
/projects/{id}/instantly/pushesThe project's sends; /projects/{id}/instantly/pushes/{push} gives one, with its progress.
Steps and credits
A step holds credits when it starts and settles when it ends, exactly as in the app.
- held is the most the step can cost. When it ends you pay for what it found, and the rest of the held credits comes back on its own.
- Finding companies: 1 credit per new company found.
- Finding and checking emails: 6 credits per email that passes the check (valid, or catch-all marked as risky). No email found, invalid and unknown cost nothing.
- Checking emails found earlier: the same 6 credits per email that passes.
- Lists, the export and the status calls are free.
- If your balance is below what a step would hold, it does not start: 422 insufficient_credits, with need and have.
- Where a country's law limits cold email, an email step answers 422 email_use_country; email_policy in GET /projects/create-data gives the rule per country.
Following a step
GET /processes/{id}/status answers with these fields. Asking every 2 to 5 seconds while a step runs is plenty.
status- running, completed, failed or cancelled.
process_type- scrape, find_emails or verify.
total, processed- the step's units: searches for scrape, companies for find_emails, addresses for verify.
success_count, fail_count- units that went through and units that failed.
progress- percent done, one decimal.
started_at, finished_at- when it started and ended (null while it runs).
live- the progress the app shows: phase, done, total, found, percent, eta, elapsed_s, counters and, once it ends, outcome.
Results
Companies and contacts come in pages: per_page from 1 to 500 (default 100) and page; each answer carries data, current_page, last_page, total and next_page_url.
- Companies: id, name, domain, website, phone, address, postal_code, city, country, category, email, verdict, email_state, exported_at, last_checked_at and created_at.
- Company filters: has_phone, has_website and has_valid_email (true or false); email_state (found, none, no_website, not_searched); verdict (valid, catch-all, unknown, pending, invalid, none_found, no_website, not_searched); city, category and search (name, domain or phone); exported (0 or 1).
- Contacts: email, first_name, last_name, position, phone, verified (the check result: valid, catch-all, invalid, unknown or pending), exported, and company (id, name, domain, city, country).
- Contact filters: verified, source, exported, and search (email or name).
- The CSV: Email address, First name, Last name, Company name, Phone (international), Position, Domain, City, Country, Niche. Only valid emails go in it.
Errors
Every refusal is JSON with a message; most carry a code to act on. A refused step start holds no credits.
- 401
- No key, or a revoked one.
- 403
needs_browser_session - An account action that needs you signed in on the site.
- 403
account_review - The account is under review; steps and sends wait until it is cleared.
- 403
glintscout_plan_required - Sending to Instantly needs a Ridge or Summit plan.
- 404
- No such project or step on your account.
- 409
- Another step of this project is running, or the step has already ended.
- 409
step_running - contact_mode cannot change while a step runs.
- 422
- A field is missing or wrong: errors lists them per field.
- 422
insufficient_credits - The step would hold more than your balance; need and have give both figures.
- 422
source_paused - That source is paused for now.
- 422
email_use_country - An email step in a country whose law turns cold email off for this use.
- 422
phone_mode - An email step on a project that collects phone numbers only.
- 422
country_unavailable - A country or place we do not serve.
- 422
city_suggestion - The city name holds a known city plus other words; use the suggestion or send confirm: true.
- 422
nothing_to_do - Nothing for the step or the export to do.
- 429
steps_cap - Your account already runs as many steps as it may at once (limit); start the next one when one ends.
- 429
at_capacity - Glintscout is at full capacity; try again in a few minutes.
- 429
- A rate limit; wait for the seconds in the Retry-After header.
- 503
temporarily_unavailable - A search provider is not available right now; the step did not start. Try again later.
- 503
engine_unavailable - Our search engine is not available right now; the step did not start. Try again later.
Rate limits
- Step starts (scrape, find-emails, verify): 30 a minute per account, shared.
- Step status: 120 a minute per account.
- Place search: 90 a minute; Instantly campaigns: 20 a minute; Instantly sends: 6 a minute.
- Over a limit you get 429 with a Retry-After header: wait that long and try again.
Not in the API
- Admin, onboarding, Chrome extension, directory and internal endpoints: the app uses them, keys cannot rely on them and they change without notice.
- Webhooks: none yet; follow a step with its status call.
- Buying credits or changing a plan: on the site, signed in.
- A test mode: none; every step costs credits as in the app. A small max_results keeps a trial run cheap.
Changes
Changes to the endpoints on this page are listed here, newest first.
- 16 November 2026: This reference first published.
A question, or a field you miss? Write to support@glintscout.com.