{ "openapi": "3.0.1", "info": { "title": "Martindale-Hubbell Attorney Scraper — AV Preeminent Ratings", "description": "Attorney records from Martindale-Hubbell: name, firm, job title, practice areas, office address, phone and website where published, year of first admission, bar admissions, law school, ISLN — and the AV Preeminent peer review rating with its five sub-scores. Filter by state, city or rating.", "version": "0.1", "x-build-id": "ci3BeNwVWA5YxOR5L" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/scrapersdelight~martindale-lawyer-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-scrapersdelight-martindale-lawyer-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/scrapersdelight~martindale-lawyer-scraper/runs": { "post": { "operationId": "runs-sync-scrapersdelight-martindale-lawyer-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/scrapersdelight~martindale-lawyer-scraper/run-sync": { "post": { "operationId": "run-sync-scrapersdelight-martindale-lawyer-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "country": { "title": "Country", "enum": [ "usa", "canada", "territories" ], "type": "string", "description": "Which Martindale directory to walk. Measured on the live sitemap index 2026-08-12: United States publishes 76 sitemap chunks across 52 regions, Canada 13, US territories 5. The states/provinces list below must belong to the country you pick here — mixing them stops the run with an error listing the valid slugs rather than returning nothing.", "default": "usa" }, "states": { "title": "States / provinces", "type": "array", "description": "Pick one or more. Leave empty to walk the whole country in alphabetical order. Sizes differ by orders of magnitude: Texas alone publishes 142,408 attorney URLs across 3 sitemap chunks, while Yukon publishes 107. Only pick options belonging to the country selected above.", "items": { "type": "string", "enum": [ "alabama", "alaska", "arizona", "arkansas", "california", "colorado", "connecticut", "delaware", "district-of-columbia", "florida", "georgia", "hawaii", "idaho", "illinois", "indiana", "iowa", "kansas", "kentucky", "louisiana", "maine", "maryland", "massachusetts", "michigan", "minnesota", "mississippi", "missouri", "montana", "nebraska", "nevada", "new-hampshire", "new-jersey", "new-mexico", "new-york", "north-carolina", "north-dakota", "ohio", "oklahoma", "oregon", "pennsylvania", "rhode-island", "south-carolina", "south-dakota", "tennessee", "texas", "utah", "vermont", "virginia", "washington", "west-virginia", "wisconsin", "wyoming", "san-luis-potosi", "alberta", "british-columbia", "manitoba", "new-brunswick", "newfoundland-and-labrador", "northwest-territories", "nova-scotia", "nunavut", "ontario", "prince-edward-island", "quebec", "saskatchewan", "yukon-territory", "guam", "northern-mariana-islands", "puerto-rico", "us-pacific-territories", "us-virgin-islands" ], "enumTitles": [ "Alabama", "Alaska", "Arizona", "Arkansas", "California", "Colorado", "Connecticut", "Delaware", "District of Columbia", "Florida", "Georgia", "Hawaii", "Idaho", "Illinois", "Indiana", "Iowa", "Kansas", "Kentucky", "Louisiana", "Maine", "Maryland", "Massachusetts", "Michigan", "Minnesota", "Mississippi", "Missouri", "Montana", "Nebraska", "Nevada", "New Hampshire", "New Jersey", "New Mexico", "New York", "North Carolina", "North Dakota", "Ohio", "Oklahoma", "Oregon", "Pennsylvania", "Rhode Island", "South Carolina", "South Dakota", "Tennessee", "Texas", "Utah", "Vermont", "Virginia", "Washington", "West Virginia", "Wisconsin", "Wyoming", "San Luis Potosí — Martindale files it under US", "Alberta — Canada", "British Columbia — Canada", "Manitoba — Canada", "New Brunswick — Canada", "Newfoundland and Labrador — Canada", "Northwest Territories — Canada", "Nova Scotia — Canada", "Nunavut — Canada", "Ontario — Canada", "Prince Edward Island — Canada", "Quebec — Canada", "Saskatchewan — Canada", "Yukon — Canada", "Guam — US territory", "Northern Mariana Islands — US territory", "Puerto Rico — US territory", "US Pacific territories", "US Virgin Islands — US territory" ] } }, "profileUrls": { "title": "Specific attorney profile URLs", "type": "array", "description": "One attorney profile URL per line, e.g. https://www.martindale.com/attorney/mr-william-mather-mckellar-1808340/ — the trailing numeric id is what identifies the attorney. Martindale's DIRECTORY pages (/all-lawyers/…, /by-location/…, practice-area listings) are behind a Cloudflare challenge and returned HTTP 403 on every attempt through a working residential session, so they are not accepted here; only /attorney/ profile URLs are. Law-firm /organization/ URLs are a different record and are rejected with an error rather than producing a half-empty attorney row.", "items": { "type": "string" } }, "cities": { "title": "Cities", "type": "array", "description": "Optional. Keep only attorneys whose office city matches, e.g. Austin, Houston, San Antonio. Exact and case-insensitive against the city Martindale prints in the address. A big city inside its own state costs a few fetches per row; a small town can cost hundreds. The run logs the running match rate every 200 fetches so you are never guessing.", "items": { "type": "string" } }, "practiceAreas": { "title": "Practice areas", "type": "array", "description": "Optional. Keep only attorneys who list one of these areas. Matching is case-insensitive SUBSTRING against Martindale's own area names, so picking Criminal also keeps \"Criminal Defense\" and \"Criminal Law\", and picking Litigation keeps \"Commercial Litigation\", \"Civil Litigation\" and \"Toxic Tort Litigation\". Measured fill: 79.2% of attorneys list at least one area, 4.7 areas each on average — but Martindale's taxonomy is long-tail (50 Wyoming attorneys produced 202 distinct area names), so this list covers the roots. For anything not here, use the free-text box below.", "items": { "type": "string", "enum": [ "Personal Injury", "Wrongful Death", "Medical Malpractice", "Products Liability", "Toxic Tort", "Asbestos", "Auto Accident", "Nursing Home", "Workers", "Class Action", "Litigation", "Appellate", "Arbitration", "Mediation", "Criminal", "DUI", "White Collar", "Juvenile", "Family", "Divorce", "Child Custody", "Adoption", "Estate Planning", "Probate", "Trusts", "Wills", "Elder", "Real Estate", "Land Use", "Zoning", "Construction", "Business", "Corporate", "Mergers", "Securities", "Tax", "Bankruptcy", "Banking", "Insurance", "Franchise", "Antitrust", "Employment", "Labor", "Immigration", "Intellectual Property", "Patent", "Trademark", "Copyright", "Entertainment", "Environmental", "Oil and Gas", "Energy", "Health Care", "Civil Rights", "Municipal", "Education", "Social Security", "Military", "Aviation", "Maritime", "General Practice" ], "enumTitles": [ "Personal injury", "Wrongful death", "Medical malpractice", "Products liability", "Toxic tort", "Asbestos / mesothelioma", "Auto accidents", "Nursing home & elder abuse", "Workers' compensation", "Class actions", "Litigation (any kind)", "Appellate practice", "Arbitration", "Mediation", "Criminal law & defense", "DUI / DWI", "White-collar crime", "Juvenile law", "Family law", "Divorce", "Child custody", "Adoption", "Estate planning", "Probate", "Trusts & estates", "Wills", "Elder law", "Real estate", "Land use", "Zoning", "Construction law", "Business law", "Corporate law", "Mergers & acquisitions", "Securities", "Tax law", "Bankruptcy", "Banking & finance", "Insurance", "Franchise law", "Antitrust", "Employment law", "Labor law", "Immigration", "Intellectual property", "Patent", "Trademark", "Copyright", "Entertainment & media", "Environmental law", "Oil & gas", "Energy", "Health care", "Civil rights", "Municipal & government law", "Education law", "Social Security disability", "Military & veterans", "Aviation", "Maritime & admiralty", "General practice" ] } }, "practiceAreaKeywords": { "title": "Practice-area keywords (free text)", "type": "array", "description": "Optional escape hatch for the long tail the dropdown above cannot list. Same case-insensitive substring rule, one phrase per line, e.g. \"Insurance Coverage\", \"Oil and Gas\", \"Complex and Multi-District\". Combined with the dropdown as OR — an attorney is kept if they match ANY selected area or ANY keyword. Leave empty if the dropdown covers you.", "items": { "type": "string" } }, "avPreeminentOnly": { "title": "Only AV Preeminent attorneys", "type": "boolean", "description": "Keep only attorneys carrying the AV Preeminent Peer Review Rating — Martindale's top peer tier, voted by other lawyers and judges, and the field no other attorney directory publishes. Measured on 490 unique Texas attorneys: 77 qualify (15.7%), so expect roughly 6 fetches per row on a plain state walk and far more if you combine it with a city.", "default": false }, "ratedOnly": { "title": "Only attorneys with a rating", "type": "boolean", "description": "Looser than the AV filter: keeps any attorney with a peer rating (AV Preeminent, Distinguished or Notable) or a client rating. Measured 25.5% carry a peer rating on 490 Texas attorneys, so roughly 4 fetches per row.", "default": false }, "withPhoneOnly": { "title": "Only attorneys with a phone number", "type": "boolean", "description": "Keep only attorneys who publish a phone number. Off by default, and read this first: Martindale publishes a phone only on CLAIMED, subscribing profiles — measured at 1.8% of 490 Texas attorneys, roughly 1 profile in 50 — so this filter costs about 50 fetches per row returned. Martindale publishes NO email address for any attorney, so there is no email filter and no email field.", "default": false }, "withWebsiteOnly": { "title": "Only attorneys with a website", "type": "boolean", "description": "Keep only attorneys who link a firm website. Measured 5.1% on 490 Texas attorneys — same claimed-profile subset as the phone, so budget roughly 20 fetches per row.", "default": false }, "minYearsSinceAdmission": { "title": "Minimum years since first admission", "minimum": 0, "maximum": 80, "type": "integer", "description": "Keep only attorneys admitted to a bar at least this many years ago, computed from the profile's own 'Year of First Admission'. Set 25+ for succession, retirement and practice-acquisition outreach; leave at 0 for everyone. Measured 98.2% fill, so this is the one cheap filter on the page.", "default": 0 }, "includePeerBreakdown": { "title": "Include the peer-review sub-scores", "type": "boolean", "description": "Include the five Martindale peer sub-scores — Legal Knowledge, Analytical Capability, Judgment, Communication and Legal Experience — as an object on each row. Measured present on 9.0% of 490 Texas attorneys, because Martindale only renders them where visible peer reviews exist (reviews submitted before 2008 are not displayed).", "default": true }, "includeOffices": { "title": "Include every office location", "type": "boolean", "description": "Include the full array of office locations Martindale lists for the attorney, each with its own street, city, state, ZIP, phone and fax. The primary office is always flattened into the top-level address fields either way, so turning this off loses nothing for a single-office attorney.", "default": true }, "maxItems": { "title": "Max results", "minimum": 1, "type": "integer", "description": "Cap on attorneys returned. You are charged $0.003 per attorney returned, so this is also your budget control: 50 rows = $0.15, 1,000 = $3.00, 5,000 = $15.00. Rows that your Step 2 filters remove are never charged.", "default": 50 }, "skipFirst": { "title": "Skip the first N attorneys", "minimum": 0, "type": "integer", "description": "Resume where a previous run stopped. Martindale's sitemaps are stable and served in a fixed order, so run 1 with maxItems 1000 and run 2 with skipFirst 1000 walks the next slice of the same state without repeating anyone — measured: two contiguous 120-attorney slices joined this way shared 0 rows out of 240. Every run logs the number to use and writes it to the key-value store as NEXT_SKIP_FIRST.", "default": 0 }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 8, "type": "integer", "description": "How many profile pages may be in flight at once (1-8). The run is paced to roughly 1.7 requests a second no matter what you set, because Martindale rate-limits the proxy exit IP and not the worker — at 4 requests a second the run measured 88.8% clean and spent the difference on retries, at 1.7 it measured 96-100% and finished FASTER (79 s vs 86 s for 120 attorneys). Raising this above 6 mostly changes how many workers wait on the pacer.", "default": 4 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify Proxy with the RESIDENTIAL group. Leave it alone unless you are supplying your own residential proxies. Measured through Apify against martindale.com: a datacenter exit that changes on every request cleared 0 of 5 requests, a pinned datacenter session 76.9%, a pinned residential session at 600 ms pacing 122/122 = 100% and then 96.1% over a 250-attorney run with 0 attorneys lost. Datacenter will eventually get there on retries; it just pays for the same rows several times over.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } }