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-Versionstring

    Optional API version pin (a date). Overrides the version pinned on the secret key / organisation for this request. Echoed in the Vojo-Version response header. Within /v1 only additive changes ship, so most callers can omit it.

    date

  • Idempotency-Keystring

    Client-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 409 idempotency_key_reused.

    8 to 255 characters

Request body

  • screen_idstringRequired

    A simulated screen in this sandbox.

  • advertisement_idstringRequired

    A creative in this sandbox. It is given a fingerprint code first if it has none.

  • scenariostring

    What evidence a test play sends; see createTestPlay for the score each settles at.

    One of verified, partial, glass_only, passport_only, passport_start_only, contradicted, screen_off, no_evidence

    Default "verified"

Response 202

Accepted — the play's evidence goes out in the background.

  • dataobjectRequired
    Show 11 fields
    • idstringRequired

      Prefixed tplay_.

    • statusstringRequired

      One of queued, sending, sent, matched, failed

    • scenariostringRequired

      What evidence a test play sends; see createTestPlay for the score each settles at.

      One of verified, partial, glass_only, passport_only, passport_start_only, contradicted, screen_off, no_evidence

    • expected_scoreinteger or nullRequired

      The score this scenario settles at; null for no_evidence. The real play's own score is on the play.

      0 to 100

    • screen_idstringRequired
    • advertisement_idstringRequired
    • play_idstring or nullRequired

      The real play, once the matcher has opened it; read it with GET /v1/plays/{play_id}.

    • failureobject or nullRequired

      Why a failed test play failed; null otherwise.

      Show 2 fields
      • codestringRequired

        One of simulation_unavailable, evidence_rejected, expired

      • messagestringRequired
    • created_atstringRequired

      date-time

    • sent_atstring or nullRequired

      When the last of its evidence went out.

      date-time

    • livemodeboolean

      False 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

  • Locationstring

    URL of the test play to poll.

  • Retry-Afterstring

    Suggested seconds before the first poll.

  • Vojo-Versionstring

    The API version (date) this response was rendered with — the request's Vojo-Version, else the key/org pin.

  • RateLimitstring

    IETF RateLimit header: remaining quota in the current window, e.g. "default";r=97;t=42.

  • RateLimit-Policystring

    IETF RateLimit-Policy header, e.g. "default";q=100;w=60. Portal OAuth clients get a higher tier.

  • Idempotent-Replayedstring

    true when this response is a stored replay of an earlier request with the same Idempotency-Key.

Errors

Every error is application/problem+json. Branch on its code.

  • 400

    Malformed request: invalid JSON, a bad cursor, a missing Vojo-Organisation for an OAuth caller, or an unknown Vojo-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-After seconds.

  • 500

    Unexpected server failure.