Quickstart

Vojo verifies digital out-of-home advertising. You register your screens, play creatives wrapped in a Vojo Passport, and get back a verification for each play.

The API is in early access. The reference documents the whole /v1 contract, and marks any endpoint that Vojo doesn't serve yet. Those endpoints return 404 for now.

Make your first request

You need a secret key. Vojo issues keys during early access, so ask for one if you don't have one yet.

Save your key in an environment variable, then ask which organisation it belongs to. This call needs no scope, so it's a quick way to check that a key works.

export VOJO_KEY="vojo_live_..."

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

import { createVojoClient, VojoApiError } from "@vojo/api-client";

const api = createVojoClient({
  baseUrl: "https://api.vojo-media.com",
  getToken: () => process.env.VOJO_KEY,
});

const { data, error } = await api.GET("/v1/organisation");
if (error) throw new VojoApiError(error);
console.log(data.data.name);

Every JSON response has the same shape: the result in data, and anything about the response in meta.

Base URLs

Every path starts with /v1.

Build the integration

A complete integration has five steps. Each guide has the requests you need.

1. Register your screens: create a site for each venue and a screen for each display.
2. Wrap each creative by URL, once per screen.
3. Play the wrapped creative exactly as Vojo returned it.
4. Receive webhooks as plays complete and their scores become final.
5. Read plays and their evidence when you need detail or want to reconcile.

Not sure what a Passport or a Harvester is? Read the core concepts first.

What early access doesn't do yet

• Only vojo_live_ keys work, so there's no test mode. For a sandbox, use the mock server or ask for a separate development organisation.
• Wrapping is synchronous, so you always get 201 today. Build for 202 anyway.
• Inline wrapper HTML is returned only when the wrapper is created.
• square_ratio is accepted up to 1, as the contract says, but the value used is limited to 0.01 to 0.2. Anything outside that range is adjusted without an error. If you also send screen_size_range_id, that range sets the ratio and square_ratio is ignored.