Try listingsAPI free with a day pass
A free 24-hour sandbox day pass for the REST API and MCP server, with demo directories instead of real publishers. Start it in your browser, or let your AI agent start it with the emailed code.
The sandbox day pass is a free, private sandbox for the listingsAPI REST API and the hosted MCP server. You create up to two locations, update them, and watch their listings sync to ten listingsAPI demo directories styled after MapQuest, Apple Maps, Bing, Yelp and others. Nothing is ever sent to real publishers, so you can try the whole create, sync and update loop without touching a real business profile.
Live status: GET /api/day-pass says whether the day pass is open right now.
The day pass is offered for limited periods. While it is closed, signup answers
403 with sandbox_closed, and you can still start on a paid plan with its
14-day free trial.
What you get
Every signup gives a first name, last name, email and company, and accepts the Terms of Service and Privacy Policy. People and AI agents use the same day pass: an agent can start it for its user, and the user proves the email is theirs.
The 24 hours start when the pass starts: when the owner presses Start my day pass from the emailed link, or when the emailed 6-digit code is used. The link and the code work for 24 hours after signup.
The 14-day free trial is different. It runs on a paid plan with a card on file and publishes to real directories. The day pass needs no card, lasts one day, and publishes only to demo directories.
Start it in your browser
- Open the day pass signup and enter your name, email and company.
- We email you a link and a 6-digit code.
- Open the link and press Start my day pass, or type the code on the signup page. Your dashboard opens with your API key.
Let your AI agent start it
Paste this prompt into Claude, ChatGPT, Cursor, or any agent that can make HTTP requests:
Read https://listingsapi.com/docs/day-pass.md and start a listingsAPI sandbox day pass for me. Ask me for my first name, last name, email and company, and confirm that I accept the Terms of Service and Privacy Policy before you sign up. Then ask me for the 6-digit code from the email, or wait while I press Start my day pass in it. With the API key, create one sample location, show me which demo directories it synced to with their links, change its opening hours, and read the listings back. Use only the day pass sandbox, and show me the integration code you used.
The agent makes the calls in the next section. It never needs the dashboard, and the key goes only to the agent that asked for the pass.
Start it from code
The day pass API is on the same origin as the REST API, and none of its calls need a key. Check whether the day pass is open, and read its limits:
curl https://listingsapi.com/api/day-pass1. Request the day pass
curl -X POST https://listingsapi.com/api/day-pass/signup \ -H "Content-Type: application/json" \ -d '{ "first_name": "Ada", "last_name": "Lovelace", "email": "ada@example.com", "company": "Analytical Engines", "accept_terms": true }'Only set accept_terms once the person has agreed to the Terms of Service and
Privacy Policy. The answer is 202, and we email the person a link and a
6-digit code. To protect people's privacy, every allowed request gets the same
answer: if the email already has a listingsAPI account or already used its day
pass, we tell the owner in that email instead, and the request never starts.
{ "status": "verification_sent", "email": "ada@example.com", "expires_in": 86400, "poll_token": "9f2c…64 hexadecimal characters…", "poll_interval_seconds": 5, "next": { "tell_the_user": "We emailed ada@example.com a link and a 6-digit code. …", "with_code": { "method": "POST", "url": "https://listingsapi.com/api/day-pass/start" }, "or_poll": { "method": "POST", "url": "https://listingsapi.com/api/day-pass/status" } }, "docs": "https://listingsapi.com/docs/day-pass"}Keep the poll_token secret. It ties the code and the key to your request, so
whoever holds it can collect the API key once the pass starts.
2. Start it with the emailed code
Ask the person for the 6-digit code from the email, then send it with the
poll_token:
curl -X POST https://listingsapi.com/api/day-pass/start \ -H "Content-Type: application/json" \ -d '{ "poll_token": "<poll_token>", "code": "482913" }'The code only works together with the poll_token of the request it was
emailed for, so it can't be typed into the website instead.
Or wait for the owner to press Start
If the person would rather press Start my day pass in the email, poll with
the poll_token every 5 seconds:
curl -X POST https://listingsapi.com/api/day-pass/status \ -H "Content-Type: application/json" \ -d '{ "poll_token": "<poll_token>" }'Until they press it, the answer is {"status": "pending"} with a Retry-After
header. After that, it is the same credentials the start call returns.
The credentials
{ "status": "active", "api_key": "dp.…", "authorization_header": "API dp.…", "api_base_url": "https://listingsapi.com", "mcp_url": "https://listingsapi.com/mcp", "expires_at": "2026-09-26T10:04:11Z", "limits": { "locations": 2, "requests_per_minute": 30, "requests_per_day": 1500 }, "includes": ["locations", "listings"], "demo_directories": [ { "name": "MapQuest", "sync": "instant" }, { "name": "N49", "sync": "delayed" } ], "dashboard_url": "https://listingsapi.com/dashboard", "docs": "https://listingsapi.com/docs/day-pass", "next_steps": ["Create a location: POST https://listingsapi.com/api/v4/locations …"]}Day pass keys start with dp., and the API and MCP server accept them only for
the locations and listings endpoints. limits carries the pass's live values,
and demo_directories lists all ten directories. If a response is lost, retrying the start call or polling again
returns the same key for 10 minutes; after that the request is closed. Only
wrong codes count toward the five tries a code allows. The owner can sign in to
the dashboard at any time with Email me a sign-in link.
Errors
Connect MCP
The hosted MCP server takes the day pass key in the same header as the REST API. For Claude Code:
claude mcp add --transport http listingsapi https://listingsapi.com/mcp --header "Authorization: API <api_key>"Configs for Cursor, Windsurf, Codex and other clients are on the
MCP page. Clients that sign in with OAuth,
such as a Claude custom connector, open the listingsAPI sign-in page instead:
choose Email me a sign-in link with the day pass email. On a day pass the
server offers the locations, listings, docs and account tools, including
locations_create, locations_update and listings_premium.
Create a location
The address must be real and geocodable, the phone a 10-digit number, and the description at least 200 characters. A sample is fine, because it only reaches the demo directories.
curl -X POST https://listingsapi.com/api/v4/locations \ -H "Authorization: API $LISTINGSAPI_KEY" \ -H "Content-Type: application/json" \ -d '{ "input": { "name": "Acme Kitchen", "description": "Acme Kitchen is a family-owned neighborhood restaurant in downtown New York serving wood-fired pizza, hand-rolled pasta, and a short seasonal menu built around produce from nearby growers. Our dining room seats forty, takeout and delivery run until close.", "street": "350 5th Ave", "city": "New York", "stateIso": "NY", "postalCode": "10118", "countryIso": "US", "phone": "6443859313", "bizUrl": "https://acmekitchen.example.com", "subCategoryId": 1432 } }'The response carries the new location under data.createLocation.location.
Keep its base64 id for the calls below.
Watch it sync
curl "https://listingsapi.com/api/v4/locations/<location-id>/listings/premium" \ -H "Authorization: API $LISTINGSAPI_KEY"Each record under data.listingsForLocation names a demo directory with its
syncStatus. Seven directories show SYNCED within seconds, with a
listingUrl that opens the demo page. N49, Chamber of Commerce and Hotfrog
show IN_PROGRESS for 30 to 90 seconds first, so you can watch the status
change. The demo pages are labelled as sandboxes and hidden from search engines
and AI crawlers.
Change a field and check again
Send only the fields you change. For opening hours, send the full week:
curl -X POST https://listingsapi.com/api/v4/locations/update \ -H "Authorization: API $LISTINGSAPI_KEY" \ -H "Content-Type: application/json" \ -d '{ "input": { "id": "<location-id>", "businessHours": [ { "day": "MONDAY", "type": "OPEN", "slots": [{ "start": "08:00am", "end": "06:00pm" }] }, { "day": "TUESDAY", "type": "OPEN", "slots": [{ "start": "08:00am", "end": "06:00pm" }] }, { "day": "WEDNESDAY", "type": "OPEN", "slots": [{ "start": "08:00am", "end": "06:00pm" }] }, { "day": "THURSDAY", "type": "OPEN", "slots": [{ "start": "08:00am", "end": "06:00pm" }] }, { "day": "FRIDAY", "type": "OPEN", "slots": [{ "start": "08:00am", "end": "06:00pm" }] }, { "day": "SATURDAY", "type": "CLOSED", "slots": [] }, { "day": "SUNDAY", "type": "CLOSED", "slots": [] } ] } }'The update answers HTTP 200 even when validation fails, so check success in
the body, then read the premium listings again.
Prompts to try
With the MCP server connected, paste one of these into your agent:
Use the listingsAPI tools to create a sample location for a coffee shop at a real street address in Austin, TX, with a 10-digit phone number, a website and a description of at least 200 characters. Then show its premium listings as a table of directory, syncStatus and listingUrl.
Show the premium listings for my listingsAPI location again. Tell me which demo directories are synced and which are still in progress, and give me the link to each demo listing page.
Update my listingsAPI location's opening hours to 8am to 6pm on weekdays and closed on weekends, sending the full seven-day week. Then check its premium listings again and tell me what changed.
After 24 hours
The API key stops working and the dashboard asks you to upgrade. You then have 48 hours to sign up for Launch or Growth with the same email; we email you a link to set a password, and the sandbox account is deleted as soon as the new account is created. If you don't upgrade within those 48 hours, the sandbox account and its data are deleted. Sandbox locations never carry over to a paid plan.