Run a test play
post/v1/test_helpers/plays
Runs one simulated play now on a simulated screen in this sandbox,
showing advertisement_id, with the evidence scenario describes.
Returns at once with a test_play (status: queued). The play
itself starts about a minute later (so the screen's sensor is heard
before it) and its evidence goes out over the following two minutes;
play_id fills in once the real matcher has opened the play. Poll GET /v1/test_helpers/plays/{test_play_id}
(honour Retry-After), or listen for the play's own webhooks.
Scenarios and the score each settles at (trust-score@4):
| scenario | evidence | settles at |
|---|---|---|
verified |
full Passport lifecycle + glass read | 100 |
partial |
Passport start + glass read | 85 |
glass_only |
glass read only | 75 |
passport_only |
full Passport lifecycle, sensor offline | 70 |
passport_start_only |
Passport start, sensor offline | 45 |
contradicted |
full lifecycle, glass reads another creative | 20 |
screen_off |
full lifecycle, sensor reports the screen off | 20 |
no_evidence |
nothing | no play (play_id stays null) |
contradicted needs a second creative in the sandbox. A play counts
towards the sandbox's daily simulated-play limit.
Access
- Authentication
- Secret key or OAuth access token.
- Scope
test_helpers:write- User permission
developerAccess- Safe to retry
- Send an Idempotency-Key.
Headers
Vojo-VersionstringOptional API version pin (a date). Overrides the version pinned on the secret key / organisation for this request. Echoed in the
Vojo-Versionresponse header. Within/v1only additive changes ship, so most callers can omit it.Idempotency-KeystringClient-generated unique key (UUID v4 recommended) making this create safe to retry. A replay within 24 hours returns the stored response (with
Idempotent-Replayed: true). Reusing a key with a different body returns 409idempotency_key_reused.
Request body
screen_idstringRequiredA simulated screen in this sandbox.
advertisement_idstringRequiredA creative in this sandbox. It is given a fingerprint code first if it has none.
scenariostringWhat evidence a test play sends; see
createTestPlayfor the score each settles at.
Response 202
Accepted — the play's evidence goes out in the background.
dataobjectRequiredShow 11 fields
idstringRequiredPrefixed
tplay_.statusstringRequiredscenariostringRequiredWhat evidence a test play sends; see
createTestPlayfor the score each settles at.expected_scoreinteger or nullRequiredThe score this scenario settles at; null for
no_evidence. The real play's own score is on the play.screen_idstringRequiredadvertisement_idstringRequiredplay_idstring or nullRequiredThe real play, once the matcher has opened it; read it with
GET /v1/plays/{play_id}.failureobject or nullRequiredWhy a
failedtest play failed; null otherwise.Show 2 fields
codestringRequiredmessagestringRequired
created_atstringRequiredsent_atstring or nullRequiredWhen the last of its evidence went out.
livemodebooleanFalse for an object in an integrator sandbox (test key), true otherwise. Always set on each object directly under
data; absent on the same kind of object nested inside another.
metaobjectRequired
Response headers
LocationstringURL of the test play to poll.
Retry-AfterstringSuggested seconds before the first poll.
Vojo-VersionstringThe API version (date) this response was rendered with — the request's
Vojo-Version, else the key/org pin.RateLimitstringIETF RateLimit header: remaining quota in the current window, e.g.
"default";r=97;t=42.RateLimit-PolicystringIETF RateLimit-Policy header, e.g.
"default";q=100;w=60. Portal OAuth clients get a higher tier.Idempotent-Replayedstringtruewhen this response is a stored replay of an earlier request with the sameIdempotency-Key.
Errors
Every error is application/problem+json. Branch on its code.
- 400
Malformed request: invalid JSON, a bad cursor, a missing
Vojo-Organisationfor an OAuth caller, or an unknownVojo-Version. - 401
Missing, invalid, expired or revoked credential.
- 403
The caller is authenticated but not allowed: missing scope (
insufficient_scope), missing Permissions flag (permission_denied), a client/installer persona on an operator endpoint (operator_access_required), or no access to the requested org (organisation_access_denied). - 404
The resource does not exist, or belongs to another organisation. Cross-org ids always 404, never 403.
- 409
The request conflicts with current state (duplicate name, device already paired, idempotency key reuse).
- 422
Well-formed request that failed validation.
errors[]lists each failing field. - 429
Rate limit exceeded for this principal. Back off for
Retry-Afterseconds. - 500
Unexpected server failure.