# 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. Source: https://listingsapi.com/docs/day-pass 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. The day pass is open right now. Live status: https://listingsapi.com/api/day-pass 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 | Feature | Day pass | | --- | --- | | Price | Free. No card and no password. | | Length | 24 hours from the moment the pass starts. | | Locations | Up to 2. | | Endpoints | Locations and listings, over REST and MCP. | | Publishing | 10 listingsAPI demo directories only. | | Not included | Reviews, posts, social, analytics, connected accounts, webhooks, and extra locations. | | Who can use it | One day pass per email address, for people who are not yet listingsAPI customers. | Every signup gives a first name, last name, email and company, and accepts the [Terms of Service](https://www.listingsapi.com/terms) and [Privacy Policy](https://www.listingsapi.com/privacy). 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 1. Open the [day pass signup](https://listingsapi.com/signup?plan=day-pass&campaign=daypass) and enter your name, email and company. 2. We email you a link and a 6-digit code. 3. 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: Start a day pass with your agent: ```text 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: ```bash curl https://listingsapi.com/api/day-pass ``` ### 1. Request the day pass ```bash 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. ```json { "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`: ```bash curl -X POST https://listingsapi.com/api/day-pass/start \ -H "Content-Type: application/json" \ -d '{ "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: ```bash curl -X POST https://listingsapi.com/api/day-pass/status \ -H "Content-Type: application/json" \ -d '{ "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 ```json { "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 | Status | `error` | What to do | | --- | --- | --- | | 400 | `invalid_request` | Fix the fields listed in `issues`. | | 403 | `sandbox_closed` | The day pass is not open right now. | | 409 | `sandbox_already_used` | At start: this email already had its day pass. | | 409 | `email_in_use` | At start: this email already has a listingsAPI plan. Sign in instead. | | 410 | `code_expired` or `poll_token_expired` | The request expired or was already collected. Sign up again. | | 410 | `sandbox_expired` | The pass has ended. Choose a plan to keep building. | | 422 | `email_not_allowed` | Throwaway email services are blocked. | | 422 | `invalid_code` | The code is wrong or expired. Use the code from the latest email. | | 429 | `too_many_attempts` | Five wrong codes. Use the link in the email instead. | | 429 | `rate_limit_exceeded`, `daily_limit_reached` or `domain_limit_reached` | Too many requests. Try again later. | | 503 | `pass_not_started` | The pass could not be started. Retry the same call. | ## Connect MCP The hosted MCP server takes the day pass key in the same header as the REST API. For Claude Code: ```bash claude mcp add --transport http listingsapi https://listingsapi.com/mcp --header "Authorization: API " ``` Configs for Cursor, Windsurf, Codex and other clients are on the [MCP page](https://www.listingsapi.com/mcp). 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. ```bash 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 ```bash curl "https://listingsapi.com/api/v4/locations//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: ```bash curl -X POST https://listingsapi.com/api/v4/locations/update \ -H "Authorization: API $LISTINGSAPI_KEY" \ -H "Content-Type: application/json" \ -d '{ "input": { "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: Create a location: ```text 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. ``` Watch it sync: ```text 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. ``` Change the opening hours: ```text 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.