--- updatedAt: 2026-05-28T21:05:07.000Z agentTools: projectIndex: https://docs.hivestack.com/llms.txt --- # Request a JSON ad schedule for a single screen using a unit UUID Returns a JSON schedule response for Header-Bidder integrations. Use this route when calling from an external SSP partner, not from the player directly. The `ssp_uuid` identifies the Header-Bidder partner (for example, Perion DOOH, Vistar, or Magnite). Contact [support@perion.com](mailto:support@perion.com) to obtain the UUID for your integration. # OpenAPI definition ```json { "openapi": "3.0.0", "x-explorer-enabled": false, "info": { "title": "Ad Server", "version": "2", "description": "\n# Ad Requests\nAd serving routes are what drive digital out-of-home displays. It's how your digital inventory (screens) interact with the Perion DOOH ad server to receive ads to play.\n\n## Choosing an endpoint prefix\n\nAll ad-serving routes are hosted on the Perion DOOH edge. Use the prefix that matches your integration:\n\n* **`/ad`** — call from the **player** (screen-side ad requests, VAST delivery, play confirmation, and creative prefetch).\n* **`/ssp`** — call from a **Header-Bidder integration** (JSON schedule responses for external SSP partners).\n\nLegacy Nirvana-compatible paths under `/nirvana/api/v1/` remain available but are deprecated.\n\nThe fundamentals of a digital display interacting with the Perion DOOH ad server are trivial. You are required to know 4 things:\n1. The unique identifier (UUID) of your organization\n2. The unique identifier (UUID) of your screen, or its external ID\n3. The ad-serving base URL\n4. How to parse a [VAST 2.0 file](https://www.iab.com/guidelines/digital-video-ad-serving-template-vast-2-0)\n\n#### 1) Organization UUID\nTo obtain a unique identifier for your organization, refer to our inventory documentation or contact us at [support@perion.com](mailto:support@perion.com).\n\n#### 2) Screen Identifier\nTo obtain a unique identifier for your digital display, refer to our inventory documentation. If you\ndo not manage your own inventory in our system, you can contact us at [support@perion.com](mailto:support@perion.com)\nto get what you need.\n\n#### 3) Ad-serving Base URL\nTo obtain our ad-server domain, refer to our inventory documentation, or contact us at [support@perion.com](mailto:support@perion.com).\n\nFor this documentation we will be using the following domain:\n`https://privateurl.com/`\n\nAppend the route path to this base URL. For example, a player VAST request looks like:\n`https://privateurl.com/ad/v1/orgs/{org_uuid}/units/uuid/{unit_uuid}/vast`\n\n#### 4) VAST Parsing\nWe conform to the adtech industry standard of using Video Ad Serving Tags (VAST) to deliver creatives from our ad server\nto your digital displays. There are multitudes of vast parsers written in many languages available freely on the internet,\nor you may implement your own if you're feeling up to it!\n\nHere are a few:\n* [Javascript](https://www.npmjs.com/package/iab-vast-parser)\n* [PHP](https://github.com/sokil/php-vast)\n* [Ruby](https://github.com/chrisdinn/vast)\n\n# Creatives\n\n

\n\nIn certain cases, a digital display might be connected to the Internet via what one might consider to be a poor network connection.\nThis can lead to problems or slowdowns downloading creatives in realtime after receiving an ad to play.\n\n

\n\n

\n\nTo give a chance for these displays with poor connection to play content on time, we offer a \"possible creatives\"\nendpoint which provides a list of all creatives that could possibly play for a given display UUID.\nThe list is valid for around 24 hours, so it is recommended that it be refreshed at least once a day screen-side\n

" }, "tags": [ { "name": "Header Bidder", "description": "Header-Bidder integration — request JSON schedule responses using `/ssp` routes" } ], "paths": { "/ssp/v1/{ssp_uuid}/orgs/{org_uuid}/units/uuid/{unit_uuid}/json": { "get": { "tags": [ "Header Bidder" ], "summary": "Request a JSON ad schedule for a single screen using a unit UUID", "description": "Returns a JSON schedule response for Header-Bidder integrations. Use this route when calling from an external SSP partner, not from the player directly.\n\nThe `ssp_uuid` identifies the Header-Bidder partner (for example, Perion DOOH, Vistar, or Magnite). Contact [support@perion.com](mailto:support@perion.com) to obtain the UUID for your integration.", "operationId": "getScheduleJsonByUnitUuid", "parameters": [ { "name": "ssp_uuid", "in": "path", "description": "UUID of the Header-Bidder partner making the request", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "org_uuid", "in": "path", "description": "UUID of the organization that owns the screen", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "unit_uuid", "in": "path", "description": "UUID of the screen requesting an ad", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK - JSON schedule response containing ad details and play confirmation URLs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/jsonresponse" } } } }, "204": { "description": "No ad available" } } } } }, "servers": [ { "url": "https://privateurl.com" } ], "components": { "schemas": { "jsonplay": { "type": "object", "properties": { "impression_url": { "type": "string", "format": "url", "example": "https://privateurl.com/ad/orguuid/yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy/units/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/confirmplay/zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz/adrequestuuid/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa" }, "error_url": { "type": "string", "format": "url", "example": "https://privateurl.com/ad/orguuid/yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy/units/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/expireplay/zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz/adrequestuuid/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa" }, "cpm": { "type": "number", "example": 1.829268292683 }, "purchase_type": { "type": "string", "example": "G" }, "deal_id": { "type": "string", "example": "new deal" }, "dsp": { "type": "integer", "example": 1 }, "dsp_name": { "type": "string", "example": "DSP" }, "advertiser": { "type": "integer", "example": 1 }, "advertiser_domains": { "type": "array", "items": { "type": "string" }, "example": [ "advertiser.com" ] }, "advertiser_name": { "type": "string", "example": "Advertiser" }, "impression_count": { "type": "number", "example": 22.539961812820486 }, "creative_url": { "type": "string", "format": "url", "example": "https://subdomain.cdn.tld/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/creative.jpg" }, "creative_id": { "type": "string", "format": "uuid", "example": "ede5ba5f-7da9-41cb-9a4b-6416d5a71fc4" }, "creative_width": { "type": "integer", "example": 1920 }, "creative_height": { "type": "integer", "example": 1080 }, "creative_properties": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } } }, "example": [ { "key": "a_key", "value": "a value" } ] }, "duration": { "type": "integer", "example": 10 }, "mime_type": { "type": "string", "example": "image/jpeg" }, "content_categories": { "type": "array", "items": { "type": "string" }, "example": [ "AAA11" ] } } }, "jsonresponse": { "type": "array", "items": { "$ref": "#/components/schemas/jsonplay" } } } } } ```