Integration Guide
Build a Custom GPT that searches the ScraperCity Lead Database with natural language. Ask for leads by title, industry, or company and get contact records back instantly in the conversation.
AI Agent? This page shows a Custom GPT using the Lead Database. For access to all 25 scrapers (Apollo, Maps, Email Finder, Mobile Finder, and more) via MCP server, CLI, or skill file:
Full Agent Setup →The ScraperCity Lead Database holds 4.6M+ verified B2B contacts. By wiring it to a Custom GPT as an Action, you turn a conversational AI into a fully functional prospecting tool - no code, no CSV uploads, no switching tabs. Here are the most common workflows teams build with this integration.
Ask for 'CFOs at fintech companies in New York with verified email' and get a formatted table of contacts in seconds. Filter by seniority, department, and company size to build targeted lists on demand.
Look up all contacts at a specific company domain. Ask 'who works at stripe.com in the marketing department?' to map stakeholders before running an ABM campaign.
Search by title and location to surface passive candidates. 'Find senior engineers in Austin at companies with 50-200 employees' returns a sourced list without leaving the chat.
Quickly count and sample leads across industries, geographies, or seniority levels to validate market size assumptions before committing to a full export.
Filter by industry and titles like 'property manager' or 'real estate broker' combined with city filters. For Zillow agents and property owner lookups, use the MCP server for access to all 25 scrapers.
Paste a company domain and ask the GPT to pull all contacts with verified emails. Combine with Email Finder and Mobile Finder via the API for full contact enrichment workflows.
Custom GPT Actions use OpenAPI schemas to describe an external REST API. When a user sends a message, ChatGPT uses function calling internally to decide which action fits the request, builds the correct query parameters from the natural language input, and executes the API call. The response comes back to ChatGPT, which formats it into a readable answer.
For this integration, the flow is: user message -> ChatGPT parses intent -> GET /database/leads with filters -> ScraperCity returns matching contacts -> GPT formats results into a table. The whole round-trip typically takes 2-5 seconds.
The Lead Database endpoint is synchronous and returns results immediately - unlike the Apollo scraper or Google Maps scraper, which are async and require polling. That makes it ideal for a ChatGPT Action where the user expects an instant reply.
Full setup takes about 5 minutes. You need a ChatGPT Plus, Pro, Team, or Enterprise account and a ScraperCity $649/mo plan for Lead Database access.
Click “Explore GPTs” in the sidebar, then “+ Create” in the top-right corner. Switch to the Configure tab.
Give it a name like “Lead Finder” and paste these instructions:
You are a B2B lead search assistant. When a user asks for leads, call the searchLeads action with the appropriate filters. Always set hasEmail to "true" unless the user says otherwise. Present results in a clean table with Name, Email, Title, Company, and LinkedIn URL. Show the total count and how many pages are available.Tip: The more explicit your instructions, the more reliably the GPT will call the Action. If the GPT starts answering from its training data instead of calling the API, add: “Never answer lead questions from memory. Always call searchLeads.”
Scroll down to Actions and click “Create new action.” Paste the OpenAPI schema below into the schema editor:
openapi: "3.1.0"
info:
title: ScraperCity Lead Database
description: Search B2B leads by title, industry, location, and company attributes.
version: "1.0.0"
servers:
- url: https://app.scrapercity.com/api/v1
paths:
/database/leads:
get:
operationId: searchLeads
summary: Search the B2B lead database with filters
parameters:
- name: title
in: query
schema: { type: string }
description: Job title keyword (e.g. CEO, CTO, VP of Sales)
- name: seniority
in: query
schema: { type: string, enum: [c_suite, vp, director, manager, senior, entry] }
- name: department
in: query
schema: { type: string }
- name: industry
in: query
schema: { type: string }
- name: country
in: query
schema: { type: string }
- name: state
in: query
schema: { type: string }
- name: city
in: query
schema: { type: string }
- name: companyName
in: query
schema: { type: string }
- name: companyDomain
in: query
schema: { type: string }
- name: minEmployees
in: query
schema: { type: string }
- name: maxEmployees
in: query
schema: { type: string }
- name: hasEmail
in: query
schema: { type: string, enum: ["true"] }
- name: hasPhone
in: query
schema: { type: string, enum: ["true"] }
- name: page
in: query
schema: { type: string, default: "1" }
- name: limit
in: query
schema: { type: string, default: "50" }
responses:
"200":
description: Lead search resultsAfter pasting, ChatGPT will parse the schema and list the available operations. You should see searchLeads appear under “Available actions.”
Click “Authentication” under the schema editor:
This tells ChatGPT to send Authorization: Bearer YOUR_KEY with every API call. Your key is encrypted at rest by OpenAI and never shown to users of your GPT. Get your API key at app.scrapercity.com/dashboard/api-docs.
Click the “Test” button next to the searchLeads action. The test panel shows the exact request being sent and the raw response - useful for confirming your API key is valid before you save the GPT.
Then go to the Preview panel and try: “Find CTOs in the United States with email addresses.” You should see a table of contacts appear in the reply.
Click “Save” in the top-right corner. Choose who can access the GPT:
Only me - private, for personal prospecting use.
Anyone with a link - share with teammates. They use your API key, so credits come from your account.
GPT Store - public listing. Each user of a published GPT shares the same API key you configured unless you swap to OAuth.
You
Find marketing directors at SaaS companies in California
searchLeads(title=marketing director, industry=computer software, state=California, hasEmail=true)
Lead Finder GPT
Found 1,247 leads across 13 pages. Here are the first 100...
You
Show me VPs at companies with 500+ employees in New York
searchLeads(seniority=vp, state=New York, minEmployees=500, hasEmail=true)
Lead Finder GPT
Found 3,891 leads. Displaying page 1 of 39...
You
Anyone at stripe.com?
searchLeads(companyDomain=stripe.com, hasEmail=true)
Lead Finder GPT
Found 42 contacts at Stripe. Here are the results...
You
Real estate brokers in Texas with phone numbers
searchLeads(title=broker, industry=real estate, state=Texas, hasPhone=true)
Lead Finder GPT
Found 834 contacts. Showing page 1 of 9...
You
C-suite executives at healthcare companies with under 100 employees
searchLeads(seniority=c_suite, industry=hospital & health care, maxEmployees=100, hasEmail=true)
Lead Finder GPT
Found 2,109 leads. Displaying page 1 of 22...
The GPT translates natural language into filter combinations. These patterns consistently produce clean results:
Paginate through results
"Show me page 2 of those results" or "Next 100 leads"
The GPT increments the page parameter. Ask for a specific page number if you want to jump ahead.
Stack multiple filters
"Directors of engineering at Series B startups in Seattle with email"
ChatGPT maps this to title, seniority, city, and hasEmail filters simultaneously.
Count before exporting
"How many CFOs are there in the fintech industry in the UK?"
Ask for a count first to know whether the segment is worth exporting. The total field in the response tells you.
Domain lookup
"Find all contacts at hubspot.com" or "Who works at salesforce.com in sales?"
Use companyDomain for precise company targeting. More reliable than companyName for exact matches.
Format as a table
"Show me the results as a table with Name, Email, Title, and LinkedIn columns only"
Useful when copy-pasting into a spreadsheet. You can also ask for a numbered list.
Custom GPT Actions make one API call per user message. You can ask for "next page" to see page 2, but the GPT cannot loop through 500 pages on its own. For bulk exports, use Claude Code, n8n, or Zapier.
The Lead Database has a 100,000 leads/day limit across all API calls on your account. A typical Custom GPT session pulling 50-100 leads per query is well within this limit. If you hit the limit, it resets at midnight UTC.
The GPT returns data in the conversation window. It cannot export CSVs directly. You can ask it to format results as a table and copy/paste, or use Code Interpreter to write the results to a downloadable file.
Custom GPTs with Actions can be shared with your team or published to the GPT Store. Your API key stays hidden from users.
The Lead Database uses the same API key as all other ScraperCity endpoints. One key, one account - credits for Email Finder, Mobile Finder, and other scrapers all draw from the same wallet.
Most issues with Custom GPT Actions fall into one of four categories: authentication errors, the GPT not calling the Action, schema parsing errors, and response formatting problems. Here is how to fix each one.
401 Unauthorized
Cause: API key is missing, incorrect, or has a leading/trailing space.
Fix: Open the Action editor and click "Authentication." Delete the existing key, re-paste your ScraperCity API key from app.scrapercity.com/dashboard/api-docs, and confirm Auth Type is set to Bearer. Save the GPT again after updating.
GPT answers from memory instead of calling the API
Cause: The system prompt is too vague or doesn't explicitly instruct the GPT to use the Action.
Fix: Add this line to your instructions: "Never answer questions about leads, contacts, or people from your training data. Always call searchLeads." You can also trigger the Action manually by saying "Call searchLeads now with these filters."
Schema parse error: "Could not parse OpenAPI spec"
Cause: YAML indentation error or unsupported OpenAPI version.
Fix: Paste the schema into a YAML validator (e.g. yaml.org/start.html) to check for indentation issues. Ensure the first line reads exactly: openapi: "3.1.0" - ChatGPT supports OpenAPI 3.0 and 3.1.
Empty results or zero leads returned
Cause: Filter combination is too narrow, or a parameter value doesn't match expected formatting.
Fix: Try relaxing one filter at a time. Industry values are case-sensitive and use LinkedIn-style names (e.g. "computer software" not "SaaS"). State values should be full names (e.g. "California" not "CA"). Use the Test button in the Action editor to see the raw request and response.
Action works in Test but not in the chat preview
Cause: The GPT instructions don't clearly map user intent to the Action.
Fix: Try a very explicit prompt like "Call searchLeads with title=CEO and country=United States and hasEmail=true." If that works, the issue is prompt interpretation. Refine the system instructions to be more explicit about when and how to call the Action.
Rate limit or 429 error
Cause: Too many requests sent in a short time window.
Fix: The Lead Database has a duplicate protection window of 30 seconds for identical requests. Wait a moment and retry. If you are sharing your GPT with a large team and hitting limits regularly, contact ScraperCity support to review your usage patterns.
The Custom GPT integration covers the Lead Database - perfect for instant conversational search. But ScraperCity has 25 scrapers in total. If your workflow needs more than the Lead Database, here are the best next steps:
MCP Server Quick Config
{
"mcpServers": {
"scrapercity": {
"command": "npx",
"args": ["-y", "--package", "scrapercity", "scrapercity-mcp"],
"env": { "SCRAPERCITY_API_KEY": "your_api_key_here" }
}
}
}Add this to your Claude Code, Cursor, or Windsurf MCP config. Full guide: /integrations/ai-agents