--- updatedAt: 2026-05-28T20:16:27.000Z agentTools: projectIndex: https://docs.hivestack.com/llms.txt --- # Submit a creative This endpoint allows buyers from external DSPs to submit creatives for approval. The creative submission process is designed to minimize response times and occurs in the background. Buyers can specify the creative's files using either the `media_files` field or the `adm` field, which accepts VAST or raw HTML content. Upon submission, a message is returned to indicate that the creative and its files are being processed. The query string parameters `publisher_id` and `deal_id` are mutually exclusive, with `publisher_id` taking precedence over `deal_id`. If `publisher_id` is provided, the creative will be sent to the specific publisher for approval. If `deal_id` is provided, the creative will be sent to the owner of the deal for approval. If the `deal_id` corresponds to a curated deal, the creative will be sent to all publishers associated with the curated deal. # OpenAPI definition ```json { "openapi": "3.0.0", "x-explorer-enabled": false, "info": { "title": "External DSPs API (V2)", "version": "2", "description": "\n# Creative Submission\nThe Creative Submission API enables external buyers to submit their creatives for approval to publishers. This process allows buyers to bid on their creatives only after they have been approved.\nThe API provides endpoints for submitting creatives and checking their approval status.\n\nIn Perion DOOH, creative approval is handled at the file level. This means each file within a creative must be individually approved.\nFor instance, if a creative is initially submitted with a single image file, that image will be approved by the publisher. However,\nif additional files are added later through a bid response, those new files will require separate approval.\nApproved files will remain available for playback, even if other files are pending approval. Additionally, creatives can support multiple\nformats, with each file needing individual approval.\n\nTo view available publishers, please refer to our [sellers.json](https://www.hivestack.com/sellers.json).\n\n# Deals API\n\nThe Deals API provides access to information about deals available to your DSP. It allows you to fetch details about specific deals and view all deals that are available for buyers.\n\n# Authenticate\n\nPerion DOOH uses API key authentication for securing access to our endpoints. Each request must include an API key, which can be provided in one of two ways:\n- Request Header: Include the API key in the `hs-auth` header.\n- Query Parameter: Alternatively, include the API key as the `apikey` query parameter.\n\nTo obtain your API key, please contact your Perion DOOH representative." }, "security": [ { "APIKeyHeader": [] }, { "APIKeyQuery": [] } ], "tags": [ { "name": "Creative Submission", "description": "Endpoints for submitting and retrieving creatives for approval." } ], "paths": { "/creatives": { "post": { "tags": [ "Creative Submission" ], "summary": "Submit a creative", "description": "This endpoint allows buyers from external DSPs to submit creatives for approval.\n\nThe creative submission process is designed to minimize response times and occurs in the background.\nBuyers can specify the creative's files using either the `media_files` field or the `adm` field, which accepts VAST or raw HTML content.\nUpon submission, a message is returned to indicate that the creative and its files are being processed.\n\nThe query string parameters `publisher_id` and `deal_id` are mutually exclusive, with `publisher_id` taking precedence over `deal_id`.\nIf `publisher_id` is provided, the creative will be sent to the specific publisher for approval.\nIf `deal_id` is provided, the creative will be sent to the owner of the deal for approval.\nIf the `deal_id` corresponds to a curated deal, the creative will be sent to all publishers associated with the curated deal.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreativePost" } } }, "description": "A JSON payload containing the fields required to submit a creative." }, "responses": { "202": { "description": "Confirmation that the creative has been successfully queued for processing. The creative is still being processed and has not yet been fully created." }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } }, "servers": [ { "url": "https://apps.hivestack.com/api/dsp" } ], "components": { "responses": { "Unauthorized": { "description": "Authorization information is missing.", "content": { "*/*": { "schema": { "type": "object", "properties": { "error_code": { "type": "string", "example": "20af6774-5952-475b-8734-c0fd0ed75b23" }, "error": { "type": "string", "example": "Missing authorization info" } }, "example": { "error_code": "20af6774-5952-475b-8734-c0fd0ed75b23", "error": "Missing authorization info" } } } } } }, "securitySchemes": { "APIKeyHeader": { "name": "hs-auth", "type": "apiKey", "in": "header" }, "APIKeyQuery": { "name": "apikey", "type": "apiKey", "in": "query" } }, "schemas": { "CreativePost": { "type": "object", "required": [ "creative_id", "name", "advertiser_domain" ], "properties": { "creative_id": { "type": "string", "example": "abc123", "description": "The unique identifier for the creative per publisher. This ID corresponds to the `crid` field sent in a bid response." }, "name": { "type": "string", "example": "Test" }, "publisher_id": { "$ref": "#/components/schemas/PublisherId" }, "deal_id": { "type": "string", "description": "The ID of the deal that will be used as submission source of the creative.\nIgnored if `publisher_id` is included in the request.\n\nIf `deal_id` is a publisher deal, the creative's media files will be sent to the owner of the deal for approval.\nIf `deal_id` is a curated deal, the creative's media files will be sent to all publishers owning a deal as a member of the given curated deal.\n" }, "advertiser_domain": { "type": "string", "example": "example.com", "format": "domain", "description": "The domain used by the adverstiser of the creative, this is *not* a full url.\n" }, "media_files": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "example": "https://example.com/logo.jpg", "format": "url" }, "format": { "type": "string", "example": "image/jpg" }, "width": { "type": "integer", "example": 1920 }, "height": { "type": "integer", "example": 1080 } } } }, "adm": { "type": "string", "format": "xml", "example": "\n\n \n \n \n \n \n \n \n \n \n \n \n 00:00:10\n \n \n \n \n \n \n \n \n \n \n \n\n", "description": "Contains the ad markup in VAST (Video Ad Serving Template) or HTML format. This example shows a VAST XML structure, which includes details such as impression and error URLs, creative information, and media file links.\n\n**Supported Formats**: Currently, we support VAST and HTML formats.\n" }, "languages": { "type": "array", "items": { "type": "string", "example": "en-US" }, "description": "A list of language codes associated with the creative.\n\nFor a complete list of available language codes, you can query our endpoint for languages. Refer to the Inventory > Languages section for more details.\n" }, "iab_categories": { "type": "array", "items": { "type": "string", "example": "IAB1-3" }, "description": "A list of IAB categories associated with the creative, based on the IAB Content Taxonomy v1.0. For a complete list of available IAB categories, you can refer to this IAB [official list](https://github.com/InteractiveAdvertisingBureau/Taxonomies/blob/main/Content%20Taxonomies/Content%20Taxonomy%201.0.tsv).\n" } } }, "PublisherId": { "type": "string", "example": "HS-NA-1", "description": "The ID of the publisher that will review the creative. The IDs of our different publishers can be found in our [sellers.json](https://www.hivestack.com/sellers.json) file.\n" } } } } ```