Create a wrapper

post/v1/wrappers

Generates Vojo Passport HTML for a creative. inline returns the HTML in data.html; archive stores it and returns data.url.

The Passport always starts itself. Wrappers created through this API begin reporting as soon as the creative is shown and never wait for a signal from the player, so verification stays independent of the player. There is no option to change this.

Two outcomes — handle both. 201 means the wrapper is ready in the response (e.g. this content was wrapped before). 202 means wrapping continues in the background: the body carries the wrapper id with status: processing; poll GET /v1/wrappers/{wrapper_id} (honour Retry-After) or subscribe to the wrapper.ready / wrapper.failed webhooks. Early implementations may always return 201; do not rely on it. Requesting fingerprint: true additionally needs advertisementFingerprinting. Wrapper delivery is a separate process and not part of this contract.

curl -X POST "https://api.vojo-media.com/v1/wrappers" \
  -H "Authorization: Bearer $VOJO_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "advertisement_id": "cm1adv3z7x0001c5v9b2n6m4tm",
  "screen_id": "cm1scr2w6n0001h8d4k9t3m7ve",
  "fingerprint": true,
  "delivery_mode": "archive",
  "metadata": {
    "line_item": "LI-2291"
  }
}'

const { data, error } = await api.POST("/v1/wrappers", {
  params: { header: { "Idempotency-Key": crypto.randomUUID() } },
  body: {
    advertisement_id: "cm1adv3z7x0001c5v9b2n6m4tm",
    screen_id: "cm1scr2w6n0001h8d4k9t3m7ve",
    fingerprint: true,
    delivery_mode: "archive",
    metadata: {
      line_item: "LI-2291",
    },
    square_ratio: 0.03,
  },
});
if (error) throw new VojoApiError(error);

Response 201

{
  "data": {
    "id": "cm1wrp2e6r0001t9y5u3i8o4wp",
    "status": "ready",
    "failure": null,
    "delivery_mode": "archive",
    "url": "https://cdn.vojo-media.com/wrappers/cm1wrp2e6r0001t9y5u3i8o4wp.html",
    "html": null,
    "fingerprint_id": "cm1fpr6y2u0001o8p4a7s3d9yr",
    "fingerprint": "3-7-1-5-2-8",
    "metadata": {
      "line_item": "LI-2291"
    },
    "created_at": "2026-10-07T09:30:00Z"
  },
  "meta": {}
}

Response 202

{
  "data": {
    "id": "cm1wrp2e6r0001t9y5u3i8o4wp",
    "status": "processing",
    "failure": null,
    "delivery_mode": "archive",
    "url": null,
    "html": null,
    "fingerprint_id": null,
    "fingerprint": null,
    "metadata": {
      "line_item": "LI-2291"
    },
    "created_at": "2026-10-07T09:30:00Z"
  },
  "meta": {}
}

Access

Authentication: Secret key or OAuth access token.
Scope: wrappers:write
User permission: advertisementAddNew
Sending fingerprint: Also needs advertisementFingerprinting
Safe to retry: Send an Idempotency-Key.

Headers

Vojo-Organisationstring
The organisation this request acts on (org id). Required for oauth2 callers — a missing header returns 400 organisation_header_required; an org the user cannot access (a membership or an access grant, and granted to this OAuth client) returns 403 organisation_access_denied. Secret keys are bound to one org: the header may be omitted, and if sent it must match the key's org (else 403). Every query is scoped by the resolved org, never by an id in the body.
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_idstring
advertisement_idstring
screen_size_range_idstring
external_idstring
Partner's own creative reference (e.g. an exchange creative id).
up to 255 characters
sourcestring
Partner / exchange namespace for external_id.
up to 120 characters
content_sourcestring
URL of the creative to wrap.
uri
content_typestring
Creative media type.
One of video, image, html
fingerprintboolean
Burn in a fingerprint. Requires the advertisementFingerprinting permission.
positionstring
Sensor patch position.
One of top_left, top_right, bottom_left, bottom_right, all
sensor_stylestring
Fingerprint sensor patch style.
One of square, quadrant_with_wings
square_rationumber
at most 1, more than 0
Default 0.03
durationnumber
Creative duration in seconds.
more than 0
display_event_idstring
up to 255 characters
delivery_modestring
inline returns the wrapper HTML in the response; archive stores it and returns a URL.
One of inline, archive
Default "inline"
metadataobject or null
Opaque partner passthrough; stored and echoed, never interpreted or scored.

Response 201

Created

dataobjectRequired
A Vojo Passport wrapper. Wrapping can finish inside the create request (status: ready) or continue in the background (status: processing); integrators must handle both.
Show 10 fields
- idstringRequired
  Wrapper id. Opaque string — treat as an identifier, never parse it.
- statusstringRequired
  processing: the wrap is still being built — url, html and the fingerprint fields are null until it is ready. Poll GET /v1/wrappers/{wrapper_id} or subscribe to the wrapper.ready / wrapper.failed webhooks. Clients must tolerate new values.
  One of processing, ready, failed
- failureobject or nullRequired
  Why the wrap failed; null unless status is failed.
  Show 2 fields
  - codestringRequired
    Stable error code from the API error registry (e.g. creative_fetch_failed).
  - detailstringRequired
- delivery_modestringRequired
  inline returns the wrapper HTML in the response; archive stores it and returns a URL.
  One of inline, archive
- urlstring or nullRequired
  Archived wrapper URL (archive mode); null for inline.
  uri
- htmlstring or nullRequired
  Wrapper HTML (inline mode); null for archive.
- fingerprint_idstring or nullRequired
- fingerprintstring or nullRequired
  Fingerprint code burned into the wrapper, when requested.
- metadataobject or nullRequired
- created_atstringRequired
  RFC 3339 / ISO-8601 UTC timestamp.
  date-time
metaobjectRequired
Response metadata for single-resource responses. Reserved; currently empty. Clients must ignore unknown members.

Response headers

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.

Response 202

Accepted — wrapping continues in the background.

dataobjectRequired
A Vojo Passport wrapper. Wrapping can finish inside the create request (status: ready) or continue in the background (status: processing); integrators must handle both.
Show 10 fields
- idstringRequired
  Wrapper id. Opaque string — treat as an identifier, never parse it.
- statusstringRequired
  processing: the wrap is still being built — url, html and the fingerprint fields are null until it is ready. Poll GET /v1/wrappers/{wrapper_id} or subscribe to the wrapper.ready / wrapper.failed webhooks. Clients must tolerate new values.
  One of processing, ready, failed
- failureobject or nullRequired
  Why the wrap failed; null unless status is failed.
  Show 2 fields
  - codestringRequired
    Stable error code from the API error registry (e.g. creative_fetch_failed).
  - detailstringRequired
- delivery_modestringRequired
  inline returns the wrapper HTML in the response; archive stores it and returns a URL.
  One of inline, archive
- urlstring or nullRequired
  Archived wrapper URL (archive mode); null for inline.
  uri
- htmlstring or nullRequired
  Wrapper HTML (inline mode); null for archive.
- fingerprint_idstring or nullRequired
- fingerprintstring or nullRequired
  Fingerprint code burned into the wrapper, when requested.
- metadataobject or nullRequired
- created_atstringRequired
  RFC 3339 / ISO-8601 UTC timestamp.
  date-time
metaobjectRequired
Response metadata for single-resource responses. Reserved; currently empty. Clients must ignore unknown members.

Response headers

Locationstring
URL of the wrapper resource 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.
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.