# Sandbox > Build and test your integration against the MarketCheck API sandbox with a free test key. Same endpoints and response formats as production, sample data only, never billed. The MarketCheck API sandbox is a free, self-service copy of the API for building and testing integrations. It runs on its own infrastructure with its own sample data, accepts only sandbox API keys, and never produces billable usage. Use it to develop and test your application before you subscribe to a production plan. ## Base URL | Environment | Host | Base Path | Key prefix | |-------------|-------------|-------------|-------------| | Sandbox | `api.sandbox.marketcheck.com` | `/v2/` | `mc_test_` | Endpoints, parameters and response formats are the same as production. Moving to production is a change of host and key only. > **WARNING**: > The sandbox uses a small, fixed set of sample data that is refreshed occasionally. It does not represent live inventory or real market prices, mileage, counts, or dates. Use it for integration testing, not for evaluating data coverage, freshness, or accuracy. To access real market data, subscribe through the [MarketCheck Developer Portal](https://developers.marketcheck.com/) or use the Free plan, which includes 500 production API calls per month. ## Get a Sandbox Key A sandbox key is offered during onboarding when you sign up on the [Marketcheck Developers Portal](https://developers.marketcheck.com/sign-up). You can also create one at any time from your account: 1. Log in to your [Marketcheck Developers Portal](https://developers.marketcheck.com/) account 2. Navigate to the [API Keys](https://developers.marketcheck.com/api-keys) section 3. Choose **Create sandbox key** No subscription is required. Sandbox keys start with `mc_test_` so they are easy to tell apart from production keys. One sandbox key is issued per account; you can rotate or delete it from the same page. Authenticate exactly as in production by passing the key in the `api_key` query parameter. See [Authentication](/docs/get-started/api/authentication). ## Environment Separation The sandbox and production are fully separate environments. Every API key belongs to exactly one of them and is accepted only by that environment's host. | Environment | Host | Accepted keys | |---------------|---------------|---------------| | Sandbox | `api.sandbox.marketcheck.com` | `mc_test_...` | | Production | `api.marketcheck.com` | `mc_live_...` | ### Key Details - A sandbox key sent to the production host is rejected with `403 Forbidden`, so it can never read production data - A production key sent to the sandbox host is rejected with `403 Forbidden`, so it can never be billed for sandbox calls - The response body states which host or key to use; see [Errors](#errors) > **TIP**: > Keep the host and the key together in your configuration and switch both when you change environment. A mismatch fails immediately with a clear message instead of silently reading or billing the wrong environment. ## Try It ### United States Search active car inventory in the sandbox: ```bash curl --request GET \ --url https://api.sandbox.marketcheck.com/v2/search/car/active ``` ### United Kingdom Search active UK car inventory in the sandbox: ```bash curl --request GET \ --url https://api.sandbox.marketcheck.com/v2/search/car/uk/active ``` ## VIN-Based Endpoints The VIN endpoints work in the sandbox for every VIN in the sample dataset: | Endpoint | Path | What it returns | |-----------------|-----------------|-----------------| | [Basic VIN Decoder](/docs/api/cars/vehicle-specs/basic) | `/v2/decode/car/{vin}/specs` | Year, make, model, trim and standard specifications | | [NeoVIN Decoder](/docs/api/cars/vehicle-specs/neovin) | `/v2/decode/car/neovin/{vin}/specs` | Trim, options packages, installed equipment, features and MSRP | | [History by VIN](/docs/api/cars/vehicle-history/history-by-vin) | `/v2/history/car/{vin}` | Past listings with price, miles, seller and first and last seen dates | > **NOTE**: > Any `vin` returned by a sandbox inventory search is available on all three endpoints. The sample is built so that each vehicle has its decode, NeoVIN and listing history data. Fetch VINs from a search at the start of a test run instead of hard-coding them, because the sample is replaced when it is refreshed. ## Sandbox Data The sandbox contains sample vehicles for every vertical the API serves, in the same response format as production: - Cars (US, Canada and UK): active and recent listings, listing details, VIN history, VIN decode, dealers, taxonomy and market statistics - Recreational vehicles (US and UK), motorcycles and heavy equipment > **NOTE**: > The sample is deliberately small today and will grow to several thousand vehicles per vertical. Every filter value that returns results in production returns results in the sandbox, so you can exercise every parameter. Treat all values as test data: `num_found`, prices, mileage, days on market and listing dates do not describe today's market. ## Endpoints Not Available in the Sandbox The following endpoints are not included in sandbox plans. Calling them with a sandbox key returns `403 Forbidden`. | Service | Endpoints | |-----------|-----------| | [AutoRecalls](/docs/api/cars/third-party/autorecalls) | `/v2/car/autorecalls/{vin}` | | [VINData AAMVA reports](/docs/api/cars/third-party/vindata) | `/v2/vindata/generate-report/aamva/{vin}`, `/v2/vindata/access-report/aamva/{vin}` | | [CarsXE plate decoder](/docs/api/cars/third-party/carsxe) | `/v2/carsxe/plate-decoder/{plate}` | | [Enhanced VIN decoder (EPI)](/docs/api/cars/third-party/epi) | `/v2/decode/car/epi/{vin}/specs` | | MarketCheck Price | `/v2/predict/car/us/marketcheck_price`, `/v2/predict/car/ca/marketcheck_price` and their `/comparables` variants | | MarketMatch | `/v2/marketmatch/dealers/rank`, `/v2/marketmatch/vins/rank` | | [Batch APIs](/docs/get-started/api/batch-api) | `/v2/batch/...` | ## Limits | Plan | Rate Limit (RPS) | Monthly Quota | |------------------|------------------|------------------| | Sandbox | 5 RPS | 25,000 API calls | Limits are enforced per key by the gateway with the same `429` responses and `RateLimit-*` / `Quota-*` headers as production, which makes the sandbox a good place to test your retry logic. See [Quota and Rate Limits](/docs/get-started/api/quota-and-rate-limits). ## Errors | Status Code | Description | Common Causes | |---------------|---------------|---------------| | 401 | Unauthorized | Missing or invalid `api_key` | | 403 | Forbidden | Sandbox key used on `api.marketcheck.com` | | 403 | Forbidden | Production key used on `api.sandbox.marketcheck.com` | | 403 | Forbidden | Endpoint is not included in sandbox plans (see the list above) | | 429 | Too Many Requests | More than 5 requests per second, or the 25,000 monthly calls used up | **Error Response Format** ```json { "code": , "message": "" } ``` #### Example: Sandbox key on the production host ```json { "code": 403, "message": "This sandbox API key can only be used with the sandbox host. Please switch to the sandbox host or use a production API key." } ``` #### Example: Production key on the sandbox host ```json { "code": 403, "message": "The sandbox host only accepts sandbox API keys. Please use a sandbox API key or switch to the production host." } ``` ## Moving to Production 1. Subscribe to a production plan on the [Marketcheck Developers Portal](https://developers.marketcheck.com/) 2. Create a production API key (`mc_live_`) 3. Change the host to `api.marketcheck.com` and swap the key No other code changes are needed. ## Good to Know - Sandbox usage is shown on the [Sandbox dashboard](https://developers.marketcheck.com/sandbox) of the Developer Portal and never appears on an invoice - The sandbox is best effort and has no SLA - The sample dataset is replaced when it is refreshed, so listing ids, VINs and dealer ids you saved from earlier responses may stop resolving; do not hard-code them in your tests - Sandbox responses are sample data. Never show sandbox prices, mileage or counts to your own users or base a business decision on them