Test in a sandbox

Build against simulated screens and plays, then run any scenario on demand.

A sandbox is a separate copy of Vojo for building and testing your integration. It has its own sites, screens, creatives and plays, and its own keys and webhook endpoints. Its screens are simulated, but everything they report goes through the same pipeline as live, so the plays, scores and webhooks you get back look exactly like live ones.

Nothing in a sandbox is billed, and nothing in it touches your live data.

Create a sandbox

An organisation owner creates sandboxes in the Vojo portal, under Developers → Sandboxes. You can have up to five, each with its own name, from one of three starting points:

Starting point What's in it
Sample network Four sites, each with a simulated screen, plus sample campaigns and creatives
Empty Nothing. Build your own sites and screens through the API
Copy of your setup Your live sites, screens, campaigns and creatives, with every screen simulated

To see a sandbox in the Vojo portal, pick it in the switch at the top of any page. An orange banner shows while you're looking at one. Every page, from screens to plays, then shows that sandbox's data, until you switch back to live.

Get a test key

A test key starts with vojo_test_ and reaches only its own sandbox. Create one on the sandbox's row under Developers → Sandboxes, or on Developers → API keys while you're viewing the sandbox.

Use a test key exactly as you use a live one, with the same base URL and the same endpoints:

export VOJO_TEST_KEY="vojo_test_..."

curl https://api.vojo-media.com/v1/screens \
  -H "Authorization: Bearer $VOJO_TEST_KEY"

Every object a test key reads or writes, and every webhook event a sandbox endpoint receives, has "livemode": false. Live objects and events have "livemode": true. Check it before acting on anything in production.

A test key can't see live data, and a live key can't see a sandbox: an id from the other one returns 404, as for any other organisation.

Run a play

POST /v1/test_helpers/plays plays one creative on one simulated screen, with the evidence a scenario describes. Your key needs the test_helpers:write scope.

curl -X POST https://api.vojo-media.com/v1/test_helpers/plays \
  -H "Authorization: Bearer $VOJO_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "screen_id": "cmw...",
    "advertisement_id": "cmw...",
    "scenario": "verified"
  }'

It returns 202 at once with a test play:

{
  "data": {
    "id": "tplay_...",
    "status": "queued",
    "scenario": "verified",
    "expected_score": 100,
    "screen_id": "cmw...",
    "advertisement_id": "cmw...",
    "play_id": null,
    "failure": null,
    "created_at": "2026-11-10T09:30:00Z",
    "sent_at": null,
    "livemode": false
  }
}

The play starts about a minute later, and its evidence goes out over the next two minutes. Poll GET /v1/test_helpers/plays/{test_play_id}, waiting as long as Retry-After says, or wait for the play's own webhooks.

Status Meaning
queued Waiting to start
sending The simulated screen is playing it and sending its evidence
sent All of its evidence has been sent
matched Vojo has opened the play: play_id is set, and GET /v1/plays/{play_id} returns it
failed It didn't run. failure.code says why: simulation_unavailable, evidence_rejected or expired

Once a play is matched, it's an ordinary play. Its score settles, it sends verification.ping, verification.score.preliminary and verification.score.final to the sandbox's endpoints, and it appears in GET /v1/plays.

Scenarios

Each scenario sends a fixed set of evidence, so it always settles at the same score:

scenario Evidence sent Settles at
verified The full Passport lifecycle and a glass read of the creative 100
partial The Passport's start and a glass read 85
glass_only A glass read only 75
passport_only The full Passport lifecycle, with the screen's sensor offline 70
passport_start_only The Passport's start, with the sensor offline 45
contradicted The full lifecycle, but the glass reads a different creative 20
screen_off The full lifecycle, but the sensor reports the screen off 20
no_evidence Nothing No play: play_id stays null

contradicted needs a second creative in the sandbox. Use the scenarios to check that your integration handles every outcome, not only the good one.

When a play is refused

Response Why
409 screen_busy A test play is already running on that screen. Try again once it's sent.
422 validation_failed The screen isn't simulated, or contradicted has no second creative to read
429 rate_limited The sandbox has used its 2,000 simulated plays for the day. Retry-After says when the count restarts, at midnight UK time
403 test_mode_only You called a test helper with a live key

Background plays

To have the simulated screens play on their own, switch ambient plays on with PATCH /v1/test_helpers/simulation:

curl -X PATCH https://api.vojo-media.com/v1/test_helpers/simulation \
  -H "Authorization: Bearer $VOJO_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ambient": true, "plays_per_hour": 12 }'

Each simulated screen then plays its running campaigns while its site is open, at up to plays_per_hour (1 to 60). Each screen's profile decides how its plays score. Ambient plays switch themselves off after 24 hours, so a forgotten sandbox goes quiet. They're off when a sandbox is created.

Make a screen do something

POST /v1/test_helpers/screens/{screen_id}/events has a simulated screen's Harvester report something, as a real one would:

type What follows
calibration screen.calibrated
quality_good screen.quality, every channel GOOD
quality_bad screen.quality, channels BAD
screen_off Later plays on the screen read as screen off, and settle at 20
screen_on Plays on the screen are scored normally again
curl -X POST https://api.vojo-media.com/v1/test_helpers/screens/$SCREEN_ID/events \
  -H "Authorization: Bearer $VOJO_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "quality_bad" }'

As on a real screen, screen.quality fires at most once per screen every 10 minutes.

Start again

POST /v1/test_helpers/sandbox/reset puts the sandbox back to its starting point. Its sites, screens, creatives, plays and test plays are replaced. Its test keys and webhook endpoints are kept, so your configuration still works. Owners can also reset a sandbox from the Vojo portal.

Without code

Everything above can also be done in the Vojo portal. View the sandbox, then open Developers → Simulation to:

  • run a play of any scenario on any simulated screen;
  • switch background plays on or off, and set their rate;
  • have a screen report an event;
  • reset the sandbox.

Each test play shows its status as it runs, and links to its play once it's matched. It's a quick way to see each score before you write any code.

Limits

Per sandbox
Screens 25
Sites 10
Webhook endpoints 5
Simulated plays a day 2,000
Creative storage 500 MB

Reports and exports from a sandbox are marked as test data on every page. A sandbox's screens can't be paired with real hardware, so it can't stand in for live verification.