{ "openapi": "3.0.0", "info": { "title": "Vistar Media Marketplace DSP API", "description": "The DSP (Demand Side Platform) API lets you view, create, and update insertion orders, campaigns, and related data.", "version": null }, "servers": [ { "url": "https://platform-api.vistarmedia.com/api/dsp/v1" } ], "security": [ { "SessionCookie": [] } ], "tags": [ { "name": "Insertion Orders", "description": "Insertion orders represent a contractual agreement between the buyer and the media owner. Each insertion order is associated with a single advertiser and contains one or more campaigns (line items). These campaigns divide the insertion order budget and define targeting and other business rules. Using this API, you can list, view, create, and update insertion orders." }, { "name": "Campaigns", "description": "Campaigns are the individual line items that belong to an insertion order. You can apply targeting and associate creatives with campaigns. Each creative is associated with a single creative category. Using this API, you can list, view, create, modify, and activate campaigns." }, { "name": "Targeting", "description": "In Vistar’s DSP, you can add targeting to run your campaigns on different formats and locations of DOOH (digital out-of-home) inventory. You can layer multiple targeting options on your campaigns to reach specific inventory.\n\nTargeting using the DSP API currently supports only venue, venue type, publisher, and deal targeting. Other targeting options will follow.\n\nYou can see a campaign’s current targeting using the [Get Campaign Targetings API](/apis/dsp/targeting/dsp_getcampaigntargetings) and set targetings on a campaign using the [Set Campaign Targetings API](/apis/dsp/targeting/dsp_setcampaigntargetings)." }, { "name": "Advertisers", "description": "An advertiser identifies the brand or organization associated with an insertion order or creative. Using this API, you can list and create advertisers.\n\nAdvertisers in the Vistar DSP are global and shared across all seats and users." }, { "name": "Creatives", "description": "Creatives are the images, videos, audio, and dynamic assets that make up your campaign. Using the DSP API, you can view creatives, update creative metadata, and associate existing creatives with campaigns and insertion orders.\n\nCreatives are specific to each DSP seat. Each creative can be associated with multiple campaigns across multiple insertion orders. When a creative is associated with a campaign, it must also be associated with the campaign’s parent insertion order. The API automatically creates this association if needed.\n\nEach creative is associated with an advertiser and assigned a creative category. Use the [Advertiser](/apis/dsp/advertisers) and [Creative Category](/apis/dsp/creatives/dsp_listcreativecategories) APIs to find the applicable advertiser and creative category IDs. The creative’s advertiser ID must match the campaign and insertion order during association." } ], "paths": { "/advertisers": { "get": { "summary": "List Advertisers", "description": "Returns the global list of advertisers available to all seats in the DSP.", "operationId": "DSP_ListAdvertisers", "responses": { "200": { "description": "Operation completed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.ListAdvertisersResponse" } } } }, "400": { "description": "Bad request. The request contains invalid syntax or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid JSON" } } } } } }, "401": { "description": "Not authorized. Authentication is required to access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authorized" } } } } } }, "403": { "description": "Not authenticated. Re-authenticate to access the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authenticated" } } } } } }, "404": { "description": "Not found. The requested resource doesn't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Found" } } } } } }, "422": { "description": "Invalid request. One or more request parameters are invalid. See the response for more details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid Request", "data": [ { "field": "page", "messages": [ "Is not less than or equal to 100" ] } ] } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Too Many Requests" } } } } } } }, "parameters": [ { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 100, "default": 25 }, "description": "The maximum number of results to return per page." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0, "default": 0 }, "description": "The zero-based page offset (page number ) to return. For example, 0 returns the first page, 1 returns the second page, and so on." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The field to sort the results by." }, { "name": "asc", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Specifies the sort direction. Set to `true` for ascending order or `false` for descending order." }, { "name": "filter", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "description": "The field to filter by. You can specify multiple filter parameters.\n\nWhen you apply filters to different fields, the results include only records that match all specified field values (AND logic). When you apply multiple filters to the same field, the results include records that match any of the specified values in that field (OR logic).\n\nSupported Fields: `id`.", "example": "id:000lYW0SSFSPuV32udyVpA" }, { "name": "search", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Perform a substring search on the specified field. Searches are case-insensitive.\n\nSupported Fields: `name`.", "example": "name:duff" } ], "tags": [ "Advertisers" ] }, "post": { "summary": "Create Advertiser", "description": "Create a new Advertiser", "operationId": "DSP_CreateAdvertiser", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.Advertiser" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid JSON" } } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authorized" } } } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authenticated" } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Found" } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid Request", "data": [ { "field": "page", "messages": [ "Is not less than or equal to 100" ] } ] } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Too Many Requests" } } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.CreateAdvertiserRequest" } } }, "required": true }, "tags": [ "Advertisers" ] } }, "/advertisers/{id}": { "get": { "summary": "Get Advertiser by ID", "description": "Returns an individual advertiser.", "operationId": "DSP_GetAdvertiser", "responses": { "200": { "description": "Operation completed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.Advertiser" } } } }, "400": { "description": "Bad request. The request contains invalid syntax or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid JSON" } } } } } }, "401": { "description": "Not authorized. Authentication is required to access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authorized" } } } } } }, "403": { "description": "Not authenticated. Re-authenticate to access the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authenticated" } } } } } }, "404": { "description": "Not found. The requested resource doesn't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Found" } } } } } }, "422": { "description": "Invalid request. One or more request parameters are invalid. See the response for more details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid Request", "data": [ { "field": "page", "messages": [ "Is not less than or equal to 100" ] } ] } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Too Many Requests" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "tags": [ "Advertisers" ] } }, "/campaigns": { "get": { "summary": "List Campaigns", "description": "Returns a list of the seat's campaigns, optionally with progress information.", "operationId": "DSP_ListCampaigns", "responses": { "200": { "description": "Operation completed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.ListCampaignsResponse" } } } }, "400": { "description": "Bad request. The request contains invalid syntax or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid JSON" } } } } } }, "401": { "description": "Not authorized. Authentication is required to access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authorized" } } } } } }, "403": { "description": "Not authenticated. Re-authenticate to access the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authenticated" } } } } } }, "404": { "description": "Not found. The requested resource doesn't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Found" } } } } } }, "422": { "description": "Invalid request. One or more request parameters are invalid. See the response for more details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid Request", "data": [ { "field": "page", "messages": [ "Is not less than or equal to 100" ] } ] } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Too Many Requests" } } } } } } }, "parameters": [ { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "The maximum number of results to return per page." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "The zero-based page offset (page number ) to return. For example, 0 returns the first page, 1 returns the second page, and so on." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The field to sort the results by." }, { "name": "asc", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Specifies the sort direction. Set to `true` for ascending order or `false` for descending order." }, { "name": "filter", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "description": "The field to filter by. You can specify multiple filter parameters.\n\nWhen you apply filters to different fields, the results include only records that match all specified field values (AND logic). When you apply multiple filters to the same field, the results include records that match any of the specified values in that field (OR logic).\n\nSupported Fields: `id`, `archived`, `insertion_order_id`, `region_code`, `active`, `pacing`, `buy_type`\n\nSpecial Filters: `in_flight`: When `true`, limits results to campaigns where the current time falls between `start_time` and `end_time`.", "example": "in_flight:true" }, { "name": "search", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Performs a substring search on a specified field. The search is case-insensitive.\n\nSupported Fields: `name`", "example": "name:quarter" }, { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "BASIC", "PROGRESS" ], "default": "BASIC" }, "description": "Specifies which fields are returned in the response.\n\nAvailable Views:\n\n- `BASIC`: Returns campaign metadata only.\n- `PROGRESS`: Returns campaign metadata and current campaign progress information." } ], "tags": [ "Campaigns" ] }, "post": { "summary": "Create Campaigns", "description": "Create up to 100 new campaigns in a single request. Campaigns must be associated with insertion orders, so create the insertion orders first.\n\nThis endpoint is transactional. If the request succeeds, all campaigns are created. If the request fails, no campaigns are created.", "operationId": "DSP_CreateCampaigns", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.CreateCampaignsResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid JSON" } } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authorized" } } } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authenticated" } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Found" } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid Request", "data": [ { "field": "page", "messages": [ "Is not less than or equal to 100" ] } ] } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Too Many Requests" } } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.CreateCampaignsRequest" } } }, "required": true }, "tags": [ "Campaigns" ] }, "patch": { "summary": "Update Campaigns", "description": "Update up to 100 campaigns in a single request. Specify only the properties you want to update. Properties you omit remain unchanged.\n\nThis endpoint is transactional. If the request succeeds, all campaigns are updated. If the request fails, no campaigns are updated.", "operationId": "DSP_UpdateCampaigns", "responses": { "200": { "description": "Operation completed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.UpdateCampaignsResponse" } } } }, "400": { "description": "Bad request. The request contains invalid syntax or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid JSON" } } } } } }, "401": { "description": "Not authorized. Authentication is required to access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authorized" } } } } } }, "403": { "description": "Not authenticated. Re-authenticate to access the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authenticated" } } } } } }, "404": { "description": "Not found. The requested resource doesn't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Found" } } } } } }, "422": { "description": "Invalid request. One or more request parameters are invalid. See the response for more details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid Request", "data": [ { "field": "page", "messages": [ "Is not less than or equal to 100" ] } ] } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Too Many Requests" } } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.UpdateCampaignsRequest" } } }, "required": true }, "tags": [ "Campaigns" ] } }, "/campaigns/{campaign_id}/targetings": { "get": { "summary": "Get Campaign Targetings", "description": "Returns a list of a campaign's active targetings. For targetings that the DSP API supports, the response includes full details in the appropriate options field. For unsupported targetings, the response includes only a targeting\\_type, with no details.\n\nTo view these details, log in to the Vistar DSP at [trafficking.vistarmedia.com](https://trafficking.vistarmedia.com/).", "operationId": "DSP_GetCampaignTargetings", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.CampaignTargetings" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid JSON" } } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authorized" } } } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authenticated" } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Found" } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid Request", "data": [ { "field": "page", "messages": [ "Is not less than or equal to 100" ] } ] } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Too Many Requests" } } } } } } }, "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "tags": [ "Targeting" ] }, "put": { "summary": "Set Campaign Targetings", "description": "Set targetings on a campaign.\n\nTo set targetings, provide a list of targeting option objects in the targetings field. Each object represents a single targeting type. When you set a campaign's targetings using this API, the new values replace all existing targetings.\n\nIn each option, a venue is targeted when it meets any of the conditions (OR logic). When you include multiple targeting options, a venue is targeted only when it meets the conditions of all the options (AND logic).\n\nExample:\n\n```json\n{\n \"targetings\": [\n {\n \"deal_targeting_option\": {\n \"deal_ids\": [\n \"OaQqQrsnSIS89FkQFzrR3w\",\n \"w7_lwxwiSl6Kwg_tUxIXkA\",\n \"4LLHNrnvTTWD4I3XG0TNHw\"\n ]\n }\n },\n {\n \"venue_type_targeting_option\": {\n \"venue_type_ids\": [\n \"1\",\n \"3\"\n ],\n \"exclude\": false\n }\n },\n {\n \"venue_targeting_option\": {\n \"venue_targeting_ids\": [\n \"tVcQWUFuTJ2OAr88vwi-Dg-XN3GJTIIOI\",\n \"tVcQWUFuTJ2OAr88vwi-Dg-MHIYWB5RHX\",\n \"7rLsD2w8SfmOwNGotS4o_g-NYC9093RD\"\n ],\n \"exclude\": true\n }\n }\n ]\n}\n```\n\nIn this example, the campaign will target venues that are:\n\n- included in any of the three deal IDs\n- AND are in the Transit (1) OR Outdoor (3) venue type categories\n- AND is NOT any of the two specific venues specified\n\nTo remove all of a campaign’s targetings, send an empty list in the targetings field:\n\n```json\n{\n \"targetings\": []\n}\n```\n\n{% admonition type=\"info\" %}\n**Note:** You can't remove targetings from an activated campaign.\n{% /admonition %}", "operationId": "DSP_SetCampaignTargetings", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.CampaignTargetings" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid JSON" } } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authorized" } } } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authenticated" } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Found" } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid Request", "data": [ { "field": "page", "messages": [ "Is not less than or equal to 100" ] } ] } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Too Many Requests" } } } } } } }, "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.DSP.SetCampaignTargetingsBody" } } }, "required": true }, "tags": [ "Targeting" ] } }, "/campaigns/{id}": { "get": { "summary": "Get Campaign by ID", "description": "Returns an individual campaign, optionally with progress information.", "operationId": "DSP_GetCampaign", "responses": { "200": { "description": "Operation completed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.Campaign" } } } }, "400": { "description": "Bad request. The request contains invalid syntax or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid JSON" } } } } } }, "401": { "description": "Not authorized. Authentication is required to access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authorized" } } } } } }, "403": { "description": "Not authenticated. Re-authenticate to access the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authenticated" } } } } } }, "404": { "description": "Not found. The requested resource doesn't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Found" } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid Request", "data": [ { "field": "page", "messages": [ "Is not less than or equal to 100" ] } ] } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Too Many Requests" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "BASIC", "PROGRESS" ], "default": "BASIC" }, "description": "Specifies which fields are returned in the response.\n\nAvailable Views:\n\n- `BASIC`: Returns campaign metadata only.\n- `PROGRESS`: Returns campaign metadata and current campaign progress information." } ], "tags": [ "Campaigns" ] }, "patch": { "summary": "Update Campaign by ID", "description": "Update an individual campaign. Specify only the properties you want to update. Properties you omit remain unchanged.", "operationId": "DSP_UpdateCampaign", "responses": { "200": { "description": "Operation completed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.Campaign" } } } }, "400": { "description": "Bad request. The request contains invalid syntax or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid JSON" } } } } } }, "401": { "description": "Not authorized. Authentication is required to access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authorized" } } } } } }, "403": { "description": "Not authenticated. Re-authenticate to access the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authenticated" } } } } } }, "404": { "description": "Not found. The requested resource doesn't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Found" } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid Request", "data": [ { "field": "page", "messages": [ "Is not less than or equal to 100" ] } ] } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Too Many Requests" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.DSP.UpdateCampaignBody" } } }, "required": true }, "tags": [ "Campaigns" ] } }, "/creative_categories": { "get": { "summary": "List Creative Categories", "description": "Returns a list of creative categories available on the DSP.", "operationId": "DSP_ListCreativeCategories", "responses": { "200": { "description": "Operation completed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.ListCreativeCategoriesResponse" } } } }, "400": { "description": "Bad request. The request contains invalid syntax or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid JSON" } } } } } }, "401": { "description": "Not authorized. Authentication is required to access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authorized" } } } } } }, "403": { "description": "Not authenticated. Re-authenticate to access the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authenticated" } } } } } }, "404": { "description": "Not found. The requested resource doesn't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Found" } } } } } }, "422": { "description": "Invalid request. One or more request parameters are invalid. See the response for more details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid Request", "data": [ { "field": "page", "messages": [ "Is not less than or equal to 100" ] } ] } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Too Many Requests" } } } } } } }, "parameters": [ { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 100, "default": 25 }, "description": "The maximum number of results to return per page." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "The zero-based page offset (page number ) to return. For example, 0 returns the first page, 1 returns the second page, and so on." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "asc", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "filter", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "description": "The field to filter by. You can specify multiple filter parameters.\n\nWhen you apply filters to different fields, the results include only records that match all specified field values (AND logic). When you apply multiple filters to the same field, the results include records that match any of the specified values in that field (OR logic).\n\nSupported Fields: `id`", "example": "id:000lYW0SSFSPuV32udyVpA" }, { "name": "search", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Performs a substring search on a specified field. The search is case-insensitive.\n\nSupported Fields: `name`", "example": "name:cosmetics" } ], "tags": [ "Creatives" ] } }, "/creative_categories/{id}": { "get": { "summary": "Get Creative Category by ID", "description": "Retrieves an individual creative category.", "operationId": "DSP_GetCreativeCategory", "responses": { "200": { "description": "Operation completed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.CreativeCategory" } } } }, "400": { "description": "Bad request. The request contains invalid syntax or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid JSON" } } } } } }, "401": { "description": "Not authorized. Authentication is required to access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authorized" } } } } } }, "403": { "description": "Not authenticated. Re-authenticate to access the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authenticated" } } } } } }, "404": { "description": "Not found. The requested resource doesn't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Found" } } } } } }, "422": { "description": "Invalid request. One or more request parameters are invalid. See the response for more details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid Request", "data": [ { "field": "page", "messages": [ "Is not less than or equal to 100" ] } ] } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Too Many Requests" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "tags": [ "Creatives" ] } }, "/creatives": { "get": { "summary": "List Creatives", "description": "Returns the list of creatives available for the current DSP seat.", "operationId": "DSP_ListCreatives", "responses": { "200": { "description": "Operation completed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.ListCreativesResponse" } } } }, "400": { "description": "Bad request. The request contains invalid syntax or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid JSON" } } } } } }, "401": { "description": "Not authorized. Authentication is required to access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authorized" } } } } } }, "403": { "description": "Not authenticated. Re-authenticate to access the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authenticated" } } } } } }, "404": { "description": "Not found. The requested resource doesn't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Found" } } } } } }, "422": { "description": "Invalid request. One or more request parameters are invalid. See the response for more details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid Request", "data": [ { "field": "page", "messages": [ "Is not less than or equal to 100" ] } ] } } } } } }, "429": { "description": "Too many requests. Your API call frequency has exceeded limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Too Many Requests" } } } } } } }, "parameters": [ { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "default": 10, "minimum": 0, "maximum": 100 }, "description": "The maximum number of results to return per page." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "default": 0, "minimum": 0 }, "description": "The zero-based page offset (page number ) to return. For example, 0 returns the first page, 1 returns the second page, and so on." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The field to sort the results by.\n\nSupported fields: `create_time`, `name`." }, { "name": "asc", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Specifies the sort direction. Set to `true` for ascending order or `false` for descending order." }, { "name": "filter", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "description": "The field to filter by. You can specify multiple filter parameters.\n\nWhen you apply filters to different fields, the results include only records that match all specified field values (AND logic). When you apply multiple filters to the same field, the results include records that match any of the specified values in that field (OR logic).\n\nSupported fields: `id`, `archived`, `campaign_ids`, `insertion_order_ids`, `advertiser_id`.", "example": "advertiser_id:SjZn7_mdSxyReVarigUV9g" }, { "name": "search", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Performs a substring search on a specified field. The search is case-insensitive.\n\nSupported fields: `name`.", "example": "name:my_asset.jpg" }, { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "BASIC", "AUDIT" ], "default": "BASIC" }, "description": "Specifies which fields are returned in the response.\n\nAvailable views:\n\n- `BASIC`: Returns creative metadata only.\n- `AUDIT`: Returns creative metadata and approval status." } ], "tags": [ "Creatives" ] }, "post": { "summary": "Create Creatives", "description": "Create Creatives", "operationId": "DSP_CreateCreatives", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.CreateCreativesResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid JSON" } } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authorized" } } } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authenticated" } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Found" } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid Request", "data": [ { "field": "page", "messages": [ "Is not less than or equal to 100" ] } ] } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Too Many Requests" } } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.CreateCreativesRequest" } } }, "required": true }, "tags": [ "Creatives" ] }, "patch": { "summary": "Update Creatives", "description": "Update up to 100 creatives in a single request. Specify only the properties you want to update. Properties you omit remain unchanged.\n\nThis endpoint is transactional. If the request succeeds, all creatives are updated. If the request fails, no creatives are updated.", "operationId": "DSP_UpdateCreatives", "responses": { "200": { "description": "Operation completed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.UpdateCreativesResponse" } } } }, "400": { "description": "Bad request. The request contains invalid syntax or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid JSON" } } } } } }, "401": { "description": "Not authorized. Authentication is required to access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authorized" } } } } } }, "403": { "description": "Not authenticated. Re-authenticate to access the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authenticated" } } } } } }, "404": { "description": "Not found. The requested resource doesn't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Found" } } } } } }, "422": { "description": "Invalid request. One or more request parameters are invalid. See the response for more details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid Request", "data": [ { "field": "page", "messages": [ "Is not less than or equal to 100" ] } ] } } } } } }, "429": { "description": "Too many requests. Your API call frequency has exceeded limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Too Many Requests" } } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.UpdateCreativesRequest" } } }, "required": true }, "tags": [ "Creatives" ] } }, "/creatives/{id}": { "get": { "summary": "Get Creative by ID", "description": "Returns an individual creative.", "operationId": "DSP_GetCreative", "responses": { "200": { "description": "Operation completed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.Creative" } } } }, "400": { "description": "Bad request. The request contains invalid syntax or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid JSON" } } } } } }, "401": { "description": "Not authorized. Authentication is required to access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authorized" } } } } } }, "403": { "description": "Not authenticated. Re-authenticate to access the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authenticated" } } } } } }, "404": { "description": "Not found. The requested resource doesn't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Found" } } } } } }, "422": { "description": "Invalid request. One or more request parameters are invalid. See the response for more details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid Request", "data": [ { "field": "page", "messages": [ "Is not less than or equal to 100" ] } ] } } } } } }, "429": { "description": "Too many requests. Your API call frequency has exceeded limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Too Many Requests" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "BASIC", "AUDIT" ], "default": "BASIC" } } ], "tags": [ "Creatives" ] }, "patch": { "summary": "Update Creative by ID", "description": "Update an individual creative. Specify only the properties you want to update. Properties you omit remain unchanged.", "operationId": "DSP_UpdateCreative", "responses": { "200": { "description": "Operation completed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.Creative" } } } }, "400": { "description": "Bad request. The request contains invalid syntax or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid JSON" } } } } } }, "401": { "description": "Not authorized. Authentication is required to access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authorized" } } } } } }, "403": { "description": "Not authenticated. Re-authenticate to access the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authenticated" } } } } } }, "404": { "description": "Not found. The requested resource doesn't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Found" } } } } } }, "422": { "description": "Invalid request. One or more request parameters are invalid. See the response for more details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid Request", "data": [ { "field": "page", "messages": [ "Is not less than or equal to 100" ] } ] } } } } } }, "429": { "description": "Too many requests. Your API call frequency has exceeded limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Too Many Requests" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.DSP.UpdateCreativeBody" } } }, "required": true }, "tags": [ "Creatives" ] } }, "/insertion_orders": { "get": { "summary": "List Insertion Orders", "description": "Returns a list of the seat’s insertion orders, optionally with progress information.", "operationId": "DSP_ListInsertionOrders", "responses": { "200": { "description": "Operation completed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.ListInsertionOrdersResponse" } } } }, "400": { "description": "Bad request. The request contains invalid syntax or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid JSON" } } } } } }, "401": { "description": "Not authorized. Authentication is required to access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authorized" } } } } } }, "403": { "description": "Not authenticated. Re-authenticate to access the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authenticated" } } } } } }, "404": { "description": "Not found. The requested resource doesn't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Found" } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid Request", "data": [ { "field": "page", "messages": [ "Is not less than or equal to 100" ] } ] } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Too Many Requests" } } } } } } }, "parameters": [ { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "The maximum number of results to return per page." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "The zero-based page offset (page number ) to return. For example, 0 returns the first page, 1 returns the second page, and so on." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The field to sort the results by." }, { "name": "asc", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Specifies the sort direction. Set to `true` for ascending order or `false` for descending order." }, { "name": "filter", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "description": "The field to filter by. You can specify multiple filter parameters.\n\nWhen you apply filters to different fields, the results include only records that match all specified field values (AND logic). When you apply multiple filters to the same field, the results include records that match any of the specified values in that field (OR logic).\n\nSupported Fields: `id`, `archived`, `insertion_order_id`, `region_code`, `active`, `pacing`, `buy_type`\n\nSpecial Filters: `in_flight`: When `true`, limits results to insertion orders where the current time falls between `start_time` and `end_time`.", "example": "in_flight:true" }, { "name": "search", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Performs a substring search on a specified field. The search is case-insensitive.\n\nSupported Fields: `name`", "example": "name:new%20york" }, { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "BASIC", "PROGRESS" ], "default": "BASIC" }, "description": "Specifies which fields are returned in the response.\n\nAvailable Views:\n\n- `BASIC`: Returns insertion order metadata only.\n- `PROGRESS`: Returns insertion order metadata and current insertion order progress information." } ], "tags": [ "Insertion Orders" ] }, "post": { "summary": "Create Insertion Orders", "description": "Create up to 100 new insertion orders in a single request.\n\nThis endpoint is transactional. If the request succeeds, all insertion orders are created. If the request fails, no insertion orders are created.", "operationId": "DSP_CreateInsertionOrders", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.CreateInsertionOrdersResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid JSON" } } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authorized" } } } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authenticated" } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Found" } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid Request", "data": [ { "field": "page", "messages": [ "Is not less than or equal to 100" ] } ] } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Too Many Requests" } } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.CreateInsertionOrdersRequest" } } }, "required": true }, "tags": [ "Insertion Orders" ] }, "patch": { "summary": "Update Insertion Orders", "description": "Update up to 100 insertion orders in a single request. Specify only the properties you want to update. Properties you omit remain unchanged.\n\nThis endpoint is transactional. If the request succeeds, all insertion orders are updated. If the request fails, no insertion orders are updated.", "operationId": "DSP_UpdateInsertionOrders", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.UpdateInsertionOrdersResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid JSON" } } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authorized" } } } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authenticated" } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Found" } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid Request", "data": [ { "field": "page", "messages": [ "Is not less than or equal to 100" ] } ] } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Too Many Requests" } } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.UpdateInsertionOrdersRequest" } } }, "required": true }, "tags": [ "Insertion Orders" ] } }, "/insertion_orders/{id}": { "get": { "summary": "Get Insertion Order by ID", "description": "Returns an individual insertion order, optionally with progress information.", "operationId": "DSP_GetInsertionOrder", "responses": { "200": { "description": "Operation completed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.InsertionOrder" } } } }, "400": { "description": "Bad request. The request contains invalid syntax or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid JSON" } } } } } }, "401": { "description": "Not authorized. Authentication is required to access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authorized" } } } } } }, "403": { "description": "Not authenticated. Re-authenticate to access the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authenticated" } } } } } }, "404": { "description": "Not found. The requested resource doesn't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Found" } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid Request", "data": [ { "field": "page", "messages": [ "Is not less than or equal to 100" ] } ] } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Too Many Requests" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "BASIC", "PROGRESS" ], "default": "BASIC" }, "description": "Specifies which fields are returned in the response.\n\nAvailable Views:\n\n- `BASIC`: Returns insertion order metadata only.\n- `PROGRESS`: Returns insertion order metadata and current insertion order progress information." } ], "tags": [ "Insertion Orders" ] }, "patch": { "summary": "Update Insertion Order by ID", "description": "Update an individual insertion order. Specify only the properties you want to update. Properties you omit remain unchanged.", "operationId": "DSP_UpdateInsertionOrder", "responses": { "200": { "description": "Operation completed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.InsertionOrder" } } } }, "400": { "description": "Bad request. The request contains invalid syntax or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid JSON" } } } } } }, "401": { "description": "Not authorized. Authentication is required to access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authorized" } } } } } }, "403": { "description": "Not authenticated. Re-authenticate to access the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Authenticated" } } } } } }, "404": { "description": "Not found. The requested resource doesn't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Not Found" } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Invalid Request", "data": [ { "field": "page", "messages": [ "Is not less than or equal to 100" ] } ] } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.external.lib.v1.Error" }, "examples": { "response": { "value": { "message": "Too Many Requests" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api.dsp.v1.DSP.UpdateInsertionOrderBody" } } }, "required": true }, "tags": [ "Insertion Orders" ] } } }, "components": { "securitySchemes": { "SessionCookie": { "type": "apiKey", "name": "Cookie", "in": "header" } }, "schemas": { "api.dsp.v1.Advertiser": { "type": "object", "properties": { "id": { "type": "string", "example": "juIGaOygS0CBBqtmXHamqA" }, "name": { "type": "string", "example": "T-Mobile", "description": "The advertiser name. It must be globally unique." } }, "description": "An advertiser identifies the brand or organization associated with an insertion order or creative.\n\nAdvertisers in the Vistar DSP are global and shared across all seats and users." }, "api.dsp.v1.Campaign": { "type": "object", "properties": { "id": { "type": "string", "example": "juIGaOygS0CBBqtmXHamqA" }, "create_time": { "type": "string", "format": "date-time", "example": "2025-07-03T21:30:40Z", "description": "The date and time the campaign was created." }, "update_time": { "type": "string", "format": "date-time", "example": "2025-07-03T21:30:40Z", "description": "The date and time the campaign was last updated." }, "archived": { "type": "boolean", "description": "Indicates whether the campaign is archived. If `true`, the campaign is archived and isn't returned by the API or displayed in the DSP user interface by default." }, "insertion_order_id": { "type": "string", "example": "juIGaOygS0CBBqtmXHamqA", "description": "The ID of the parent insertion order." }, "name": { "type": "string", "example": "A really good ad campaign", "description": "The customer-specified campaign name." }, "region_code": { "type": "string", "example": "US", "title": "Uses ISO_3166-1_alpha-2 as the region code", "description": "The country or territory where the campaign will run. Specify the value using an ISO 3166-1 alpha-2 two-letter country code (for example, US, CA, or GB)." }, "active": { "type": "boolean", "description": "Indicates whether the campaign is enabled to serve. A campaign serves only when it's enabled and its flight dates and targeting parameters are met.\n\nAfter enabling a campaign, it can take up to 20 minutes before it begins serving." }, "start_time": { "type": "string", "format": "date-time", "example": "2025-07-03T21:30:40Z", "description": "The campaign flight start time. It must be on or after the parent insertion order's `start_time`." }, "end_time": { "type": "string", "format": "date-time", "example": "2025-07-03T22:30:40Z", "description": "The campaign flight end time. This value must be on or before the parent insertion order's `end_time`." }, "activation_time": { "type": "string", "format": "date-time", "example": "2025-07-03T21:35:40Z", "description": "The time the campaign was last set to active." }, "budget_impressions": { "type": "string", "format": "uint64", "example": "8412", "description": "The target impression budget for the campaign. Required when the parent insertion order uses impression budgeting and is mutually exclusive with the `budget_money` field." }, "budget_money": { "$ref": "#/components/schemas/google.type.Money", "description": "The target spend budget for the campaign. Required when the parent insertion order uses spend budgeting and is mutually exclusive with the `budget_impressions` field." }, "cpm": { "$ref": "#/components/schemas/google.type.Money", "description": "The campaign bid CPM." }, "pacing": { "$ref": "#/components/schemas/api.dsp.v1.Campaign.PacingOption", "description": "The campaign pacing strategy. This determines how the campaign budget is spent over the course of its flight." }, "pixel_url": { "type": "string", "example": "https://apixelurl.com", "description": "An optional tracking pixel URL to call when the ad is displayed. This must be a valid HTTPS URL." }, "creatives": { "type": "array", "items": { "$ref": "#/components/schemas/api.dsp.v1.Campaign.Creative" }, "description": "The list of creatives associated with the campaign, including their flight dates and weights. Retrieve each creative separately to view its details." }, "progress": { "$ref": "#/components/schemas/api.dsp.v1.Progress", "description": "The campaign delivery progress information." }, "buy_type": { "$ref": "#/components/schemas/api.dsp.v1.Campaign.BuyType" }, "deal_bid_strategy": { "$ref": "#/components/schemas/api.dsp.v1.Campaign.BidStrategy" } }, "description": "Campaigns are the individual line items that belong to an insertion order. They specify a budget, pacing strategy, bidding strategy, targeting parameters and have associated creatives." }, "api.dsp.v1.Campaign.BidStrategy": { "type": "string", "enum": [ "OPEN", "FLOOR" ], "default": "OPEN", "description": "The strategy used to determine campaign bid CPMs for campaigns targeting PMP (Private Marketplace) deals and curations.\n\nSupported Values:\n\n- `OPEN`: Uses standard bid behavior.\n- `FLOOR`: Always bids the floor price of targeted deals. The CPM you set is the maximum CPM you'll pay for a deal." }, "api.dsp.v1.Campaign.BuyType": { "type": "string", "enum": [ "OPEN_EXCHANGE", "DEAL", "PROGRAMMATIC_GUARANTEED" ], "default": "OPEN_EXCHANGE", "description": "Indicates whether the campaign is buying inventory on the open exchange, through PMP deals and curations, or as Programmatic Guaranteed. This value is set automatically by the platform.\n\nSupported Values:\n\n- `OPEN_EXCHANGE`\n- `DEAL` (Private Marketplace or curation)\n- `PROGRAMMATIC_GUARANTEED`" }, "api.dsp.v1.Campaign.CampaignView": { "type": "string", "enum": [ "BASIC", "PROGRESS" ], "default": "BASIC" }, "api.dsp.v1.Campaign.Creative": { "type": "object", "properties": { "creative_id": { "type": "string", "example": "juIGaOygS0CBBqtmXHamqA", "description": "The ID of the creative." }, "start_time": { "type": "string", "format": "date-time", "example": "2025-07-03T21:30:40Z", "description": "The campaign creative flight start time." }, "end_time": { "type": "string", "format": "date-time", "example": "2025-07-03T22:30:40Z", "description": "The campaign creative flight end time." }, "weight": { "type": "string", "format": "int64", "example": "120", "description": "Weight determines how often a creative will serve. Creatives with higher weights serve more often than creatives with lower weights. Weighting is proportional. For example, if you give creative “A” a weight of 2 and creative “B” a weight of 1. Creative “A” serves twice as often as Creative “B” (2:1). By default, all creative weights are set at 1." } } }, "api.dsp.v1.Campaign.PacingOption": { "type": "string", "enum": [ "EVEN", "AHEAD", "ASAP" ], "default": "EVEN", "description": "The pacing strategy of the campaign. Pacing controls how quickly the campaign spends its budget over the course of its flight dates.\n\n- `EVEN`: Attempts to spend the budget evenly throughout the flight. Even pacing is recommended if your priority is to spend a consistent amount of your budget each day.\n- `AHEAD`: Front-loads delivery, aiming to spend approximately 75% of the budget by the midpoint of the flight. Line item delivery start off fasts and slows down over the course of the flight dates until the line item spends in full. Ahead pacing is recommended for line items where you want to front-load your delivery.\n- `ASAP`: Prioritizes spending the budget as quickly as possible. Here the only goal of the line item is to spend the budget over the course of the flight dates." }, "api.dsp.v1.CampaignTargetings": { "type": "object", "properties": { "targetings": { "type": "array", "items": { "$ref": "#/components/schemas/api.dsp.v1.Targeting" } } }, "example": { "targetings": [ { "deal_targeting_option": { "deal_ids": [ "OaQqQrsnSIS89FkQFzrR3w", "w7_lwxwiSl6Kwg_tUxIXkA", "4LLHNrnvTTWD4I3XG0TNHw" ] } }, { "venue_type_targeting_option": { "venue_type_ids": [ "1", "3" ], "exclude": false } }, { "venue_targeting_option": { "venue_targeting_ids": [ "tVcQWUFuTJ2OAr88vwi-Dg-XN3GJTIIOI", "tVcQWUFuTJ2OAr88vwi-Dg-MHIYWB5RHX", "7rLsD2w8SfmOwNGotS4o_g-NYC9093RD" ], "exclude": true } } ] } }, "api.dsp.v1.CreateAdvertiserRequest": { "type": "object", "properties": { "name": { "type": "string", "example": "A New Advertiser" } } }, "api.dsp.v1.CreateCampaignRequest": { "type": "object", "properties": { "insertion_order_id": { "type": "string", "example": "juIGaOygS0CBBqtmXHamqA", "description": "The ID of the parent insertion order." }, "name": { "type": "string", "example": "Insertion Order Name", "description": "The customer-specified campaign name." }, "start_time": { "type": "string", "format": "date-time", "example": "2004-09-22T16:16:42Z", "description": "The campaign flight start time. It must be on or after the parent insertion order's `start_time`." }, "end_time": { "type": "string", "format": "date-time", "example": "2004-09-22T16:16:42Z", "description": "The campaign flight end time. This value must be on or before the parent insertion order's `end_time`." }, "cpm": { "$ref": "#/components/schemas/google.type.Money", "description": "The campaign bid CPM." }, "pacing": { "$ref": "#/components/schemas/api.dsp.v1.Campaign.PacingOption", "description": "The campaign pacing strategy. This determines how the campaign budget is spent over the course of its flight." }, "budget_impressions": { "type": "string", "format": "uint64", "example": "10000", "description": "The target impression budget for the campaign. Required when the parent insertion order uses impression budgeting and is mutually exclusive with the `budget_money` field." }, "budget_money": { "$ref": "#/components/schemas/google.type.Money", "description": "The target spend budget for the campaign. Required when the parent insertion order uses spend budgeting and is mutually exclusive with the `budget_impressions` field." }, "region_code": { "type": "string", "example": "US", "title": "Uses ISO_3166-1_alpha-2 as the region code", "description": "The country or territory where the campaign will run. Specify the value using an ISO 3166-1 alpha-2 two-letter country code (for example, US, CA, or GB)." }, "pixel_url": { "type": "string", "example": "https://apixelurl.com", "description": "An optional tracking pixel URL to call when the ad is displayed. This must be a valid HTTPS URL." } } }, "api.dsp.v1.CreateCampaignsRequest": { "type": "object", "properties": { "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/api.dsp.v1.CreateCampaignRequest" } } } }, "api.dsp.v1.CreateCampaignsResponse": { "type": "object", "properties": { "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/api.dsp.v1.Campaign" } } } }, "api.dsp.v1.CreateCreativeRequest": { "type": "object", "properties": { "asset_upload_id": { "type": "string", "example": "juIGaOygS0CBBqtmXHamqA" }, "campaign_ids": { "type": "array", "example": [ "juIGaOygS0CBBqtmXHamqA" ], "items": { "type": "string" } }, "name": { "type": "string", "example": "Some-Advertising-Campaign-2025.jpg" }, "pixel_url": { "type": "string", "example": "https://apixelurl.com" }, "category_ids": { "type": "array", "example": [ "juIGaOygS0CBBqtmXHamqA" ], "items": { "type": "string" } }, "insertion_order_ids": { "type": "array", "example": [ "juIGaOygS0CBBqtmXHamqA" ], "items": { "type": "string" } }, "advertiser_id": { "type": "string", "example": "juIGaOygS0CBBqtmXHamqA" } } }, "api.dsp.v1.CreateCreativesRequest": { "type": "object", "properties": { "creatives": { "type": "array", "items": { "$ref": "#/components/schemas/api.dsp.v1.CreateCreativeRequest" } } } }, "api.dsp.v1.CreateCreativesResponse": { "type": "object", "properties": { "creatives": { "type": "array", "items": { "$ref": "#/components/schemas/api.dsp.v1.Creative" } } } }, "api.dsp.v1.CreateInsertionOrderRequest": { "type": "object", "properties": { "advertiser_id": { "type": "string", "example": "juIGaOygS0CBBqtmXHamqA", "description": "The ID of the insertion order's advertiser. You can set the advertiser only when you create the insertion order." }, "name": { "type": "string", "example": "My Insertion Order Name", "description": "The insertion order's name for display purposes." }, "start_time": { "type": "string", "format": "date-time", "example": "2004-09-22T16:16:42Z", "description": "The insertion order's flight start time." }, "end_time": { "type": "string", "format": "date-time", "example": "2004-09-22T16:16:42Z", "description": "The insertion order's flight end time." }, "contract_number": { "type": "string", "example": "C-102930", "description": "A contract number associated with the insertion order. Contract numbers are for the buyer's use and aren't used by the DSP." }, "budget_impressions": { "type": "string", "format": "uint64", "example": "10000", "description": "The target impression budget for the insertion order. This field is mutually exclusive with `budget_money`." }, "budget_money": { "$ref": "#/components/schemas/google.type.Money", "description": "The target spend budget for the insertion order. This field is mutually exclusive with `budget_impressions`. Specify the budget in the seat's billing currency." } } }, "api.dsp.v1.CreateInsertionOrdersRequest": { "type": "object", "properties": { "insertion_orders": { "type": "array", "items": { "$ref": "#/components/schemas/api.dsp.v1.CreateInsertionOrderRequest" } } } }, "api.dsp.v1.CreateInsertionOrdersResponse": { "type": "object", "properties": { "insertion_orders": { "type": "array", "items": { "$ref": "#/components/schemas/api.dsp.v1.InsertionOrder" } } } }, "api.dsp.v1.Creative": { "type": "object", "properties": { "id": { "type": "string", "example": "juIGaOygS0CBBqtmXHamqA" }, "campaign_ids": { "type": "array", "example": [ "juIGaOygS0CBBqtmXHamqA" ], "items": { "type": "string" } }, "create_time": { "type": "string", "format": "date-time", "example": "2004-09-22T16:16:42Z" }, "name": { "type": "string", "example": "Some-Advertising-Campaign-2025.jpg" }, "thumbnail_url": { "type": "string", "example": "https://transcodes.vistarmedia.com.s3.amazonaws.com/abc123/thumb.png" }, "pixel_url": { "type": "string", "example": "https://apixelurl.com" }, "duration_ms": { "type": "integer", "format": "int32", "example": 1500 }, "category_ids": { "type": "array", "example": [ "juIGaOygS0CBBqtmXHamqA" ], "items": { "type": "string" } }, "archived": { "type": "boolean", "example": false }, "type": { "$ref": "#/components/schemas/api.dsp.v1.Creative.CreativeType" }, "requires_audio": { "type": "boolean", "example": true }, "processing_status": { "$ref": "#/components/schemas/api.dsp.v1.Creative.CreativeStatus" }, "asset": { "$ref": "#/components/schemas/api.dsp.v1.Creative.Asset" }, "audits": { "type": "array", "items": { "$ref": "#/components/schemas/api.dsp.v1.Creative.Audit" } }, "advertiser_id": { "type": "string", "example": "juIGaOygS0CBBqtmXHamqA" }, "insertion_order_ids": { "type": "array", "example": [ "juIGaOygS0CBBqtmXHamqA" ], "items": { "type": "string" } } } }, "api.dsp.v1.Creative.Asset": { "type": "object", "properties": { "url": { "type": "string", "example": "https://transcodes.vistarmedia.com.s3.amazonaws.com/abc123/abc123-1920x1080.png" }, "height": { "type": "integer", "format": "int32", "example": 1080 }, "width": { "type": "integer", "format": "int32", "example": 1920 }, "format": { "type": "string", "example": "video/mp4" }, "file_size_bytes": { "type": "integer", "format": "int32", "example": 1024 } } }, "api.dsp.v1.Creative.Audit": { "type": "object", "properties": { "publisher_id": { "type": "string", "example": "juIGaOygS0CBBqtmXHamqA", "description": "The ID of the media owner that must approve the creative." }, "publisher_name": { "type": "string", "example": "Some Publisher Name", "description": "The name of the media owner that must approve the creative." }, "status": { "$ref": "#/components/schemas/api.dsp.v1.Creative.Audit.AuditStatus" }, "message": { "type": "string", "example": "Looks good to me!", "description": "An optional message from the media owner that may explain why the creative was approved or denied or provide other relevant information." }, "last_reviewed": { "type": "string", "format": "date-time", "example": "2004-09-22T16:16:42Z", "description": "The time of the most recent approval or denial." } }, "description": "Before Vistar's DSP serves an ad to a screen, the screen's media owner must approve the creative. Each media owner approval has a separate audit object. A media owner can have multiple approvals for the same creative, depending on how their screens are configured in Vistar's DSP." }, "api.dsp.v1.Creative.Audit.AuditStatus": { "type": "string", "enum": [ "PENDING", "APPROVED", "DENIED" ], "default": "PENDING", "description": "The approval status. Possible values include:\n\n- `PENDING`: The audit is in the media owner's queue awaiting review.\n- `APPROVED`: The creative is approved for display.\n- `DENIED`: The creative is denied and won't serve to the media owner. Check the audit's `message` property for more information." }, "api.dsp.v1.Creative.CreativeStatus": { "type": "string", "enum": [ "PROCESSING", "PROCESSED", "FAILED" ], "default": "PROCESSING" }, "api.dsp.v1.Creative.CreativeType": { "type": "string", "enum": [ "NONE", "DYNAMIC", "SAGE_AND_ARCHER_DYNAMIC", "IMAGE", "VIDEO", "AUDIO", "UNKNOWN" ], "default": "NONE" }, "api.dsp.v1.Creative.CreativeView": { "type": "string", "enum": [ "BASIC", "AUDIT" ], "default": "BASIC" }, "api.dsp.v1.CreativeCategory": { "type": "object", "properties": { "id": { "type": "string", "example": "juIGaOygS0CBBqtmXHamqA" }, "name": { "type": "string", "example": "Food & Groceries" } } }, "api.dsp.v1.DSP.SetCampaignTargetingsBody": { "type": "object", "properties": { "targetings": { "type": "array", "items": { "$ref": "#/components/schemas/api.dsp.v1.SetCampaignTargetingsRequest.Targeting" } } } }, "api.dsp.v1.DSP.UpdateCampaignBody": { "type": "object", "properties": { "name": { "type": "string", "example": "A really good ad campaign" }, "active": { "type": "boolean" }, "start_time": { "type": "string", "format": "date-time", "example": "2025-07-03T21:30:40Z" }, "end_time": { "type": "string", "format": "date-time", "example": "2025-07-03T22:30:40Z" }, "budget_impressions": { "type": "string", "format": "uint64", "example": "8412" }, "budget_money": { "$ref": "#/components/schemas/google.type.Money" }, "cpm": { "$ref": "#/components/schemas/google.type.Money" }, "pacing": { "$ref": "#/components/schemas/api.dsp.v1.Campaign.PacingOption" }, "pixel_url": { "type": "string", "example": "https://apixelurl.com" }, "deal_bid_strategy": { "$ref": "#/components/schemas/api.dsp.v1.Campaign.BidStrategy" } } }, "api.dsp.v1.DSP.UpdateCreativeBody": { "type": "object", "properties": { "pixel_url": { "type": "string", "example": "https://apixelurl.com" }, "campaign_ids": { "type": "array", "example": [ "juIGaOygS0CBBqtmXHamqA" ], "items": { "type": "string" } }, "category_ids": { "type": "array", "example": [ "juIGaOygS0CBBqtmXHamqA" ], "items": { "type": "string" } }, "insertion_order_ids": { "type": "array", "example": [ "juIGaOygS0CBBqtmXHamqA" ], "items": { "type": "string" } } } }, "api.dsp.v1.DSP.UpdateInsertionOrderBody": { "type": "object", "properties": { "contract_number": { "type": "string", "example": "C-102930", "description": "A contract number associated with the insertion order. Contract numbers are for the buyer's use and aren't used by the DSP." }, "name": { "type": "string", "example": "A really good ad campaign", "description": "The insertion order's name for display purposes." }, "start_time": { "type": "string", "format": "date-time", "example": "2004-09-22T16:16:42Z", "description": "The insertion order's flight start time." }, "end_time": { "type": "string", "format": "date-time", "example": "2004-09-22T17:16:42Z", "description": "The insertion order's flight end time." }, "budget_impressions": { "type": "string", "format": "uint64", "example": "8412", "description": "The target impression budget for the insertion order. This field is mutually exclusive with `budget_money`." }, "budget_money": { "$ref": "#/components/schemas/google.type.Money" } } }, "api.dsp.v1.DealTargetingOption": { "type": "object", "properties": { "deal_ids": { "type": "array", "example": [ "xuh_zhjLQX2XrJRCNbd4OQ" ], "items": { "type": "string" } } } }, "api.dsp.v1.InsertionOrder": { "type": "object", "properties": { "id": { "type": "string", "example": "juIGaOygS0CBBqtmXHamqA" }, "create_time": { "type": "string", "format": "date-time", "example": "2004-09-22T16:16:42Z", "description": "The date and time the insertion order was created." }, "update_time": { "type": "string", "format": "date-time", "example": "2004-09-22T16:16:42Z", "description": "The date and time the insertion order was last updated." }, "archived": { "type": "boolean", "description": "Shows whether the insertion order is archived. If `true`, the insertion order is archived and isn't returned by the API or displayed in the DSP by default." }, "advertiser_id": { "type": "string", "example": "juIGaOygS0CBBqtmXHamqA", "description": "The ID of the insertion order's advertiser. You can set the advertiser only when you create the insertion order." }, "contract_number": { "type": "string", "example": "C-102930", "description": "A contract number associated with the insertion order. Contract numbers are for the buyer's use and aren't used by the DSP." }, "name": { "type": "string", "example": "My Insertion Order Name", "description": "The insertion order's name for display purposes." }, "start_time": { "type": "string", "format": "date-time", "example": "2004-09-22T16:16:42Z", "description": "The insertion order's flight start time." }, "end_time": { "type": "string", "format": "date-time", "example": "2004-09-22T17:16:42Z", "description": "The insertion order's flight end time." }, "budget_impressions": { "type": "string", "format": "uint64", "example": "10000", "description": "The target impression budget for the insertion order. This field is mutually exclusive with `budget_money`." }, "budget_money": { "$ref": "#/components/schemas/google.type.Money", "description": "The target spend budget for the insertion order. This field is mutually exclusive with `budget_impressions`. Specify the budget in the seat's billing currency." }, "progress": { "$ref": "#/components/schemas/api.dsp.v1.Progress", "description": "The insertion order's delivery progress information." }, "creative_ids": { "type": "array", "items": { "type": "string" } } } }, "api.dsp.v1.InsertionOrder.InsertionOrderView": { "type": "string", "enum": [ "BASIC", "PROGRESS" ], "default": "BASIC" }, "api.dsp.v1.ListAdvertisersResponse": { "type": "object", "properties": { "advertisers": { "type": "array", "items": { "$ref": "#/components/schemas/api.dsp.v1.Advertiser" } }, "total_size": { "type": "integer", "format": "int64", "example": 1 } } }, "api.dsp.v1.ListCampaignsResponse": { "type": "object", "properties": { "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/api.dsp.v1.Campaign" } }, "total_size": { "type": "integer", "format": "int64", "example": 1 } } }, "api.dsp.v1.ListCreativeCategoriesResponse": { "type": "object", "properties": { "creative_categories": { "type": "array", "items": { "$ref": "#/components/schemas/api.dsp.v1.CreativeCategory" } }, "total_size": { "type": "integer", "format": "int64" } } }, "api.dsp.v1.ListCreativesResponse": { "type": "object", "properties": { "creatives": { "type": "array", "items": { "$ref": "#/components/schemas/api.dsp.v1.Creative" } }, "total_size": { "type": "integer", "format": "int64", "example": 1 } } }, "api.dsp.v1.ListInsertionOrdersResponse": { "type": "object", "properties": { "insertion_orders": { "type": "array", "items": { "$ref": "#/components/schemas/api.dsp.v1.InsertionOrder" } }, "total_size": { "type": "integer", "format": "int64", "example": 1 } } }, "api.dsp.v1.ListPublishersResponse": { "type": "object", "properties": { "publishers": { "type": "array", "items": { "$ref": "#/components/schemas/api.dsp.v1.Publisher" } }, "total_size": { "type": "integer", "format": "int64" } } }, "api.dsp.v1.ListVenueTypesResponse": { "type": "object", "properties": { "venue_types": { "type": "array", "items": { "$ref": "#/components/schemas/api.dsp.v1.VenueType" } }, "total_size": { "type": "integer", "format": "int64" } } }, "api.dsp.v1.Progress": { "type": "object", "properties": { "impressions_delivered": { "type": "string", "format": "uint64", "description": "The number of impressions delivered so far.", "example": "10000" }, "money_spent": { "$ref": "#/components/schemas/google.type.Money", "description": "The total amount spent so far." } } }, "api.dsp.v1.Publisher": { "type": "object", "properties": { "id": { "type": "string", "example": "kxYItBGFSsCtRbK6j0usXw" }, "name": { "type": "string", "example": "Some Publisher Name" }, "region_code": { "type": "string", "example": "US" }, "targeting_eligible": { "type": "boolean" } } }, "api.dsp.v1.PublisherTargetingOption": { "type": "object", "properties": { "publisher_ids": { "type": "array", "example": [ "kxYItBGFSsCtRbK6j0usXw" ], "items": { "type": "string" } }, "exclude": { "type": "boolean", "example": false } } }, "api.dsp.v1.SetCampaignTargetingsRequest.Targeting": { "x-tags": [ "Targeting" ], "title": "Targeting Options", "type": "object", "properties": { "venue_targeting_option": { "$ref": "#/components/schemas/api.dsp.v1.SetCampaignTargetingsRequest.Targeting.VenueTargetingOption" }, "deal_targeting_option": { "$ref": "#/components/schemas/api.dsp.v1.SetCampaignTargetingsRequest.Targeting.DealTargetingOption" }, "publisher_targeting_option": { "$ref": "#/components/schemas/api.dsp.v1.SetCampaignTargetingsRequest.Targeting.PublisherTargetingOption" }, "venue_type_targeting_option": { "$ref": "#/components/schemas/api.dsp.v1.SetCampaignTargetingsRequest.Targeting.VenueTypeTargetingOption" } } }, "api.dsp.v1.SetCampaignTargetingsRequest.Targeting.DealTargetingOption": { "type": "object", "properties": { "deal_ids": { "type": "array", "example": [ "xuh_zhjLQX2XrJRCNbd4OQ" ], "items": { "type": "string" } } }, "title": "Deal Targeting", "description": "Target deals and curations.\n\n- Use the Vistar deal ID.\n- You can target public deals and one-to-one deals.\n- You can target up to 100 deals.\n- You can't add or remove deal targeting after a campaign is activated.\n- Adding deal targeting automatically sets a campaign’s `deal_bid_strategy` to `FLOOR`. The campaign then always bids the floor price of targeted deals and uses the configured CPM as the maximum CPM. To change this behavior, update the campaign’s `deal_bid_strategy` to `OPEN`.\n- Adding deal targeting doesn't adjust the campaign’s CPM, so be mindful of the deal’s pricing and set your CPM accordingly.", "example": { "deal_ids": [ "OaQqQrsnSIS89FkQFzrR3w", "w7_lwxwiSl6Kwg_tUxIXkA", "4LLHNrnvTTWD4I3XG0TNHw" ] } }, "api.dsp.v1.SetCampaignTargetingsRequest.Targeting.PublisherTargetingOption": { "type": "object", "properties": { "publisher_ids": { "type": "array", "example": [ "kxYItBGFSsCtRbK6j0usXw" ], "items": { "type": "string" } }, "exclude": { "type": "boolean", "example": false } }, "title": "Publisher Targeting", "description": "Target specific publishers (media owners).\n\n- Use the Vistar publisher id (also known account id or media owner id).\n- Publishers must be in the same country as the campaign.\n- You can include or exclude publishers." }, "api.dsp.v1.SetCampaignTargetingsRequest.Targeting.VenueTargetingOption": { "type": "object", "properties": { "venue_targeting_ids": { "type": "array", "example": [ "juIGaOygS0CBBqtmXHamqA-Venue007" ], "items": { "type": "string" } }, "exclude": { "type": "boolean", "example": false } }, "title": "Venue Targeting", "description": "Target specific venues (screens).\n\nYou can include or exclude venues.\n\n- Use the venue’s targeting ID. This ID is available from the Vistar SSP platform and the [venue drop](https://help.vistarmedia.com/hc/en-us/articles/360045126551-Access-Vistar-s-SSP-venue-drop) file.\n- You can target up to 2,500 venues.\n- Venues must be in the same country as the campaign.", "example": { "venue_targeting_ids": [ "tVcQWUFuTJ2OAr88vwi-Dg-XN3GJTIIOI", "tVcQWUFuTJ2OAr88vwi-Dg-MHIYWB5RHX", "k6BCwQDOTJmcZYhgTV_9wA-FL056FMCCS01", "k6BCwQDOTJmcZYhgTV_9wA-AZ120AACLD01", "4500pvspR3SlFLXP0iU17A-BAR-112617", "7rLsD2w8SfmOwNGotS4o_g-NYC9093RD" ], "exclude": false } }, "api.dsp.v1.SetCampaignTargetingsRequest.Targeting.VenueTypeTargetingOption": { "type": "object", "properties": { "venue_type_ids": { "type": "array", "example": [ "804" ], "items": { "type": "string" } }, "exclude": { "type": "boolean", "example": false } }, "title": "Venue Type Targeting", "description": "Target specific venue types.\n\nMedia owners define their screen venue types.\n\n- Use [OpenOOH Venue Taxonomy 1.0 Category IDs](https://github.com/openooh/venue-taxonomy/blob/main/specification-1.0.md). Parent and child categories are supported. Grandchild categories aren't supported.\n- You can include or exclude venue types.", "example": { "venue_type_ids": [ "3", "105", "801" ], "exclude": false } }, "api.dsp.v1.Targeting": { "type": "object", "properties": { "id": { "type": "string", "example": "juIGaOygS0CBBqtmXHamqA" }, "targeting_type": { "$ref": "#/components/schemas/api.dsp.v1.TargetingType" }, "venue_targeting_option": { "$ref": "#/components/schemas/api.dsp.v1.VenueTargetingOption" }, "deal_targeting_option": { "$ref": "#/components/schemas/api.dsp.v1.DealTargetingOption" }, "publisher_targeting_option": { "$ref": "#/components/schemas/api.dsp.v1.PublisherTargetingOption" }, "venue_type_targeting_option": { "$ref": "#/components/schemas/api.dsp.v1.VenueTypeTargetingOption" } } }, "api.dsp.v1.TargetingType": { "type": "string", "enum": [ "TARGETING_TYPE_UNSPECIFIED", "TARGETING_TYPE_VENUE", "TARGETING_TYPE_PUBLISHER", "TARGETING_TYPE_DEAL", "TARGETING_TYPE_DAY_PART", "TARGETING_TYPE_AUDIENCE", "TARGETING_TYPE_CURRENT_WEATHER", "TARGETING_TYPE_GEOGRAPHY", "TARGETING_TYPE_POI", "TARGETING_TYPE_CREATIVE_CATEGORY", "TARGETING_TYPE_NETWORK", "TARGETING_TYPE_VENUE_TYPE" ], "default": "TARGETING_TYPE_UNSPECIFIED" }, "api.dsp.v1.UpdateCampaignRequest": { "type": "object", "properties": { "id": { "type": "string", "example": "juIGaOygS0CBBqtmXHamqA", "description": "The ID of the campaign to update." }, "name": { "type": "string", "example": "A really good ad campaign", "description": "The customer-specified campaign name." }, "active": { "type": "boolean", "description": "Indicates whether the campaign is enabled to serve. A campaign serves only when it's enabled and its flight dates and targeting parameters are met.\n\nAfter enabling a campaign, it can take up to 20 minutes before it begins serving." }, "start_time": { "type": "string", "format": "date-time", "example": "2025-07-03T21:30:40Z", "description": "The campaign flight start time. It must be on or after the parent insertion order's `start_time`." }, "end_time": { "type": "string", "format": "date-time", "example": "2025-07-03T22:30:40Z", "description": "The campaign flight end time. This value must be on or before the parent insertion order's `end_time`." }, "budget_impressions": { "type": "string", "format": "uint64", "example": "10000", "description": "The target impression budget for the campaign. Required when the parent insertion order uses impression budgeting and is mutually exclusive with the `budget_money` field." }, "budget_money": { "$ref": "#/components/schemas/google.type.Money", "description": "The target spend budget for the campaign. Required when the parent insertion order uses spend budgeting and is mutually exclusive with the `budget_impressions` field." }, "cpm": { "$ref": "#/components/schemas/google.type.Money", "description": "The campaign bid CPM." }, "pacing": { "$ref": "#/components/schemas/api.dsp.v1.Campaign.PacingOption", "description": "The campaign pacing strategy. This determines how the campaign budget is spent over the course of its flight." }, "pixel_url": { "type": "string", "example": "https://apixelurl.com", "description": "An optional tracking pixel URL to call when the ad is displayed. This must be a valid HTTPS URL." }, "deal_bid_strategy": { "$ref": "#/components/schemas/api.dsp.v1.Campaign.BidStrategy" } } }, "api.dsp.v1.UpdateCampaignsRequest": { "type": "object", "properties": { "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/api.dsp.v1.UpdateCampaignRequest" } } } }, "api.dsp.v1.UpdateCampaignsResponse": { "type": "object", "properties": { "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/api.dsp.v1.Campaign" } } } }, "api.dsp.v1.UpdateCreativeRequest": { "type": "object", "properties": { "id": { "type": "string", "example": "juIGaOygS0CBBqtmXHamqA" }, "pixel_url": { "type": "string", "example": "https://apixelurl.com" }, "campaign_ids": { "type": "array", "example": [ "juIGaOygS0CBBqtmXHamqA" ], "items": { "type": "string" } }, "category_ids": { "type": "array", "example": [ "juIGaOygS0CBBqtmXHamqA" ], "items": { "type": "string" } }, "insertion_order_ids": { "type": "array", "example": [ "juIGaOygS0CBBqtmXHamqA" ], "items": { "type": "string" } } } }, "api.dsp.v1.UpdateCreativesRequest": { "type": "object", "properties": { "creatives": { "type": "array", "items": { "$ref": "#/components/schemas/api.dsp.v1.UpdateCreativeRequest" } } } }, "api.dsp.v1.UpdateCreativesResponse": { "type": "object", "properties": { "creatives": { "type": "array", "items": { "$ref": "#/components/schemas/api.dsp.v1.Creative" } } } }, "api.dsp.v1.UpdateInsertionOrderRequest": { "type": "object", "properties": { "id": { "type": "string", "example": "juIGaOygS0CBBqtmXHamqA", "description": "The ID of the insertion order to update." }, "contract_number": { "type": "string", "example": "C-102930", "description": "A contract number associated with the insertion order. Contract numbers are for the buyer's use and aren't used by the DSP." }, "name": { "type": "string", "example": "My Insertion Order Name", "description": "The insertion order's name for display purposes." }, "start_time": { "type": "string", "format": "date-time", "example": "2004-09-22T16:16:42Z", "description": "The insertion order's flight start time." }, "end_time": { "type": "string", "format": "date-time", "example": "2004-09-22T17:16:42Z", "description": "The insertion order's flight end time." }, "budget_impressions": { "type": "string", "format": "uint64", "example": "10000", "description": "The target impression budget for the insertion order. This field is mutually exclusive with `budget_money`." }, "budget_money": { "$ref": "#/components/schemas/google.type.Money", "description": "The target spend budget for the insertion order. This field is mutually exclusive with `budget_impressions`. Specify the budget in the seat's billing currency." } } }, "api.dsp.v1.UpdateInsertionOrdersRequest": { "type": "object", "properties": { "insertion_orders": { "type": "array", "items": { "$ref": "#/components/schemas/api.dsp.v1.UpdateInsertionOrderRequest" } } } }, "api.dsp.v1.UpdateInsertionOrdersResponse": { "type": "object", "properties": { "insertion_orders": { "type": "array", "items": { "$ref": "#/components/schemas/api.dsp.v1.InsertionOrder" } } } }, "api.dsp.v1.VenueTargetingOption": { "type": "object", "properties": { "exclude": { "type": "boolean", "example": false }, "venue_ids": { "type": "array", "example": [ "juIGaOygS0CBBqtmXHamqA" ], "items": { "type": "string" } } } }, "api.dsp.v1.VenueType": { "type": "object", "properties": { "id": { "type": "string", "example": "101" }, "name": { "type": "string", "example": "Airports" } } }, "api.dsp.v1.VenueTypeTargetingOption": { "type": "object", "properties": { "venue_type_ids": { "type": "array", "example": [ "804" ], "items": { "type": "string" } }, "exclude": { "type": "boolean", "example": false } } }, "api.external.lib.v1.Error": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/api.external.lib.v1.Error.FieldError" } } } }, "api.external.lib.v1.Error.FieldError": { "type": "object", "properties": { "field": { "type": "string" }, "messages": { "type": "array", "items": { "type": "string" } } } }, "google.type.Money": { "type": "object", "properties": { "currency_code": { "type": "string", "description": "The three-letter currency code defined in ISO 4217.", "example": "USD" }, "units": { "type": "string", "format": "int64", "description": "The whole units of the amount.\nFor example if `currencyCode` is `\"USD\"`, then 1 unit is one US dollar.", "example": "1" }, "nanos": { "type": "integer", "format": "int32", "description": "Number of nano (10^-9) units of the amount.\nThe value must be between -999,999,999 and +999,999,999 inclusive.\nIf `units` is positive, `nanos` must be positive or zero.\nIf `units` is zero, `nanos` can be positive, zero, or negative.\nIf `units` is negative, `nanos` must be negative or zero.\nFor example $-1.75 is represented as `units`=-1 and `nanos`=-750,000,000.", "example": 750000000 } }, "description": "Represents an amount of money with its currency type." } } } }