API
Last updated 4 October 2026
Everything the site does is available over HTTPS: find a business type, count matches, preview rows and export a CSV. Counting and previewing are free and need no key. Exporting uses the same credits as the site, 1 per business, and businesses you already bought are free to export again.
Authentication
Create a key on your account page (up to 5 per account) and send it as a bearer token. The key is shown once, so store it when you create it.
Authorization: Bearer vm_live_...
Base URL: https://verticalmaps.co. Request and response bodies are JSON unless noted.
1. Find the business type
GET /api/categories?q=plumber returns two lists with counts. trades are everyday trade names; use a trade's nodes as the categories of a search. categories are the underlying business types; a parent type covers all of its children.
curl "https://verticalmaps.co/api/categories?q=plumber"
{ "trades": [{ "name": "Plumbers", "nodes": ["plumbing"], "n": 45878 }],
"categories": [] }2. Count, for free
POST /api/count with a search body returns the total and how many have an email, phone and website.
curl -X POST https://verticalmaps.co/api/count \
-H "content-type: application/json" \
-d '{"categories":["plumbing"],"state":"TX","city":"Austin"}'
{ "total": 126, "with_email": 50, "with_phone": 125, "with_website": 117 }The search body
categories: list of business types (from step 1). Leave empty for all business types.state(2 letters) and optionalcity, or a radius:lat,lon,miles(1 to 200).hasEmail,hasPhone,hasWebsite,noWebsite: true or false.excludeChains: true keeps independents only.hasOwner: true keeps businesses with the owner's name on file (from state licence, truck and federal contractor records).confirmedOpen: true keeps businesses that match an active government record. On the site this filter is called "Active government record"; the field keeps its old name so existing code still works. The record is one of: an active Texas sales tax permit, a state licence in force (contractors and trades in nine states), an active registration or licence with the city of Los Angeles, San Francisco, Seattle, Chicago or New York, an active US DOT registration (businesses that run commercial trucks), an active entry in a state business register (Oregon, Colorado, Connecticut, Texas, New York, Pennsylvania, Delaware), a liquor licence in force (New York, Texas) or an active federal contractor registration. The record is matched to the business by name and by address or ZIP code. It shows that the permit, licence or registration was in force in the file we loaded. It is not proof that the location is operating, and a business without a match is not closed. Each state and city publishes different records, so coverage differs by state.sizeBands: any of1-4,5-9,10-19,20-49,50-99,100-249,250+employees. Not every business has a size.
To turn an address into coordinates: GET /api/geocode?address=... returns lat, lon and the matched address.
3. Preview, for free
POST /api/preview with the same body returns 10 sample rows. Emails and phones are partly hidden.
4. Export
POST /api/export with the same body plus max (the most rows you want, up to 250,000). Needs a key. The response is a CSV, sorted by ZIP code and then by street. When max is smaller than the number of matches, businesses with an email are picked first. To download a past export again, exactly as it was and free, send {"exportId": 12} with an id from GET /api/exports. The header x-credits-charged says how many credits were used. A new-business export (its search has "feed": "new") cannot be downloaded by id: send its search to POST /api/new/export again. Businesses you already bought are free.
Send "dryRun": true to learn the cost first: the answer is JSON (businesses, charge, exact, alreadyOwned, credits, enough) and nothing is charged. Send "maxCharge": 764 with the export and it is refused with 409 if it would take more credits than that. Both also work on POST /api/new/export.
curl -X POST https://verticalmaps.co/api/export \
-H "Authorization: Bearer $VERTICALMAPS_API_KEY" \
-H "content-type: application/json" \
-d '{"categories":["plumbing"],"state":"TX","city":"Austin","hasEmail":true,"max":50}' \
-o plumbers-austin.csvColumns: business_name, owner_name (where a public licence record names the owner), category, address, city, state, zip, phone, website, email, email_status, email_source (the business's website, a state licence file or business register, its US DOT registration, or an older business listing), email_type (a generic inbox such as info@, or a named address), email_2 and email_3 (more addresses on the business's own website, where it lists them), chain, employees, status, lat, lon, facebook, instagram, confirmed_open (the active government record matched to the business, where there is one, for example active Texas sales tax permit or state licence in force; the column keeps its old name).
zipis five digits, or empty when we have no ZIP code for the business.phoneis written(512) 555-0142for US numbers.email_status:Previously deliveredmeans the address has already received email without bouncing; where the day is on record it readsPreviously delivered on 2026-08-18.not testedmeans we have not tried it. No address has been through a verification check. Empty when the business has no email.status:listed as open, ornot marked closedwhen the listing gives no status. Businesses listed as closed are left out. Onlyconfirmed_openhas a government record behind it, and it names an active record, not a visit: neither column proves the location is operating today.employees: a band such as5 to 9, where known.
The file is UTF-8 and starts with a byte order mark, so Excel shows accented names correctly. In Python, open it with encoding="utf-8-sig". Excel drops the first zero of a ZIP code such as 02134 when it opens a CSV with a double click. To keep it, load the file with Data, From Text/CSV and set the zip column to text, or give the column the number format 00000.
New businesses and business changes
POST /api/new/search (free) returns counts, the trades in the chosen area, 10 preview rows and map points. POST /api/new/export (needs a key, same credits) returns the CSV, newest first, in the same file format as the main export (byte order mark, five-digit zip, one phone format). updated in the search response is the day we last loaded the feed. It is not the date on any record: each row carries its own. A business you exported before is never charged again, so a repeat export costs only the new rows.
Every row is a new government record: a permit, a licence or a registration. It is not proof that the business has opened or is trading. Some field names are older than this wording (opened, opening_soon, new_owner) and are kept so existing code still works; read them as described here. Coverage differs by state and source: a state shows only what its registers publish.
trades: list of trade names as returned by the search, for exampleRestaurants.state:TX(every new sales tax permit, all trades),CA(new registrations with the cities of Los Angeles and San Francisco, plus contractors with a first state licence),WA(new Seattle business licences, plus contractors first registered with the state),IL(new Chicago business licences),CT(new registrations with the Secretary of the State),ORandMN(contractors with a first state licence), or any other state code. Every state also has businesses that registered commercial trucks with the US DOT in the last 12 months; in the other states these are the only rows. A new DOT registration is not a newly opened business: it can be an existing one putting trucks on the road. Optionalcity, orlat,lon,miles.opened: filters on the date on the record:soon(the date is still ahead),30,90,365(within that many days) orall.storefrontOnly(default true): keeps trades that usually have premises and hides online and home sellers. It is worked out from the trade on the record, not from a visit.newOwnerOnly: true hides new locations of existing businesses. Only Texas, Los Angeles, San Francisco and Chicago tell a new location from a first one; elsewhere it changes nothing.hasContact: true keeps rows with a phone or an email.event: one business change.any, orbranch: a new location of an existing business, reported by the register's own location number in Texas, Los Angeles and Chicago, and inferred from the dates on the register in San Francisco. The other four are inferred by us by matching street addresses, in Texas, Los Angeles and San Francisco only: a new record at an address where a different record closed in the 12 months before or the 4 months after.changed_hands: a possible change of owner (same business name, different legal owner).replaced_same: replaced the same kind of business.replaced: replaced any business.incorporated: the same business under a new registration, where the new owner's name matches the business or the earlier owner (often a sole owner forming a company; the value keeps its old name).
What the response of /api/new/search means:
counts.total: matching records.counts.opening_soon: those whose date is still ahead.counts.last_30: those dated in the last 30 days.events: how many rows carry each business change (branch,changed_hands,replaced_same,replaced,incorporated), under every filter butevent.rows[].opened: the date on the record, androws[].date_labelsays which date it is. Texas permits: the first-sale date the business declared, which can be ahead (issuedis the day the permit was issued). City rows: the location or licence start date on the register. Connecticut: the registration date. Contractors: the day the licence was first issued. Truck operators: the day they registered with the US DOT. A date that is still ahead is declared by the business and not checked; no opening date is inferred.rows[].source,recordandpublisher: the record the row comes from, for exampletx_sales_tax,Texas sales tax permit,Texas Comptroller.rows[].signals: the business changes on the row. The first is the record itself. Each has atype(registration,first_licence,new_location,owner_change,re_registration,replacement,expected_opening), alabel, abasis(reportedby the register or declared by the business, orinferredby us), abasis_labelin words andhow, the evidence.rows[].new_owner: false marks a new location of an existing business. True means only that the register does not show an earlier location; it does not mean the business changed owner.change,prev_nameandprev_closed: the address-matched change, the business whose record was at the address before, and the day the register says that record closed.
Export columns: business_name, trade, address, city, state, zip, opened (the date on the record, as above), permit_issued, status, new_business_or_new_location, owner, phone, website, email, lat, lon, location, at_this_address, previous_business, previous_closed, record, record_publisher, date_is. status is date still ahead (declared) or date passed: it compares the date on the record with today, and nobody has checked that the business is open. new_business_or_new_location is new location, first location on record or new US DOT registration. record and record_publisher name the record the row comes from and who publishes it; date_is says which date opened is on that row. at_this_address, previous_business and previous_closed are inferred by matching street addresses, as described under event.
These are business changes: a reason to get in touch. They do not mean the business is looking for a supplier.
curl -X POST https://verticalmaps.co/api/new/search \
-H "content-type: application/json" \
-d '{"state":"TX","city":"Houston","trades":["Restaurants"],"opened":"soon"}'Your account
GET /api/me: your email and credits left.GET /api/exports: your past exports, each with the search that produced it.
Errors
400: the body is not valid. The response lists what is wrong.401: an export without a valid key.402: not enough credits. The response says how many are needed and how many you have. On a search of more than 1,000 businesses, whenmaxis more than your credits cover, the search stops early.neededis then the most the export could cost, and the real cost can be lower. The response carriesexact: false whenneededis that upper limit.409: the export would take more credits thanmaxCharge; nothing was charged.429: too many requests in a short time. Wait a few minutes and try again. An account can run 10 exports every 10 minutes and 100 a day, and download past exports 20 times every 10 minutes and 200 times a day.
AI agents
Give your agent the skill file at verticalmaps.co/agent-skill.md and an API key. It walks through the same steps and asks before spending credits.