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.