> ## Documentation Index > Fetch the complete documentation index at: https://docs.topsort.com/llms.txt > Use this file to discover all available pages before exploring further. # Get a placement. > Retrieve a V2 placement by external identifier. The external placement identifier matches slotId on public sponsored-brand campaigns. ## OpenAPI ````yaml /openapi.json get /public/v1/placement-service/placements/{external-placement-id} openapi: 3.1.0 info: title: Topsort Endpoints v2 API Reference description: > In order for a storefront to be able to run auctions in Topsort and report auction-related events back to Topsort, both the `/v2/auctions` and `/v2/events` endpoints must be integrated. Below are the endpoint and model definitions for each. contact: email: wicha@topsort.com license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html x-logo: url: https://assets.topsort.com/Topsort_logo_icon_dark.svg backgroundColor: '#fff' altText: Topsort version: 2.0.0 servers: - url: https://api.topsort.com description: Base API URL security: [] tags: - name: Auctions description: >- An auction determines which products should be promoted based on the vendors' bids. - name: Events description: >- Events are sent to Topsort as part of the attribution and reporting journey. - name: Toptimize description: > An out-of-the-box solution for prediction, ranking, retrieval, and other elements of ad selection. - name: Toppie API description: Toppie management API. - name: Campaign API description: Full-featured campaign management API for banners and sponsored listings. - name: Catalog API description: Products catalog management API. - name: Billing API description: Marketplace and Vendor Billing management API. - name: Reporting API description: Marketplace, Vendor, Campaign, and product reporting API. - name: Invitation API description: Vendor invitations management API. - name: User API description: User management API. - name: Webhooks API description: Webhooks API that allows event-driven automation. - name: Assets API description: Assets management API. - name: Segments Service description: Segments Service. - name: Forecasting Service description: Toptimize Forecasting Service. - name: Offsite Ads API description: Offsite Ads API that allows to manage offsite ads campaigns. - name: Media API description: Ad configuration API. - name: Placement API description: Placement management API for sponsored brand slots. paths: /public/v1/placement-service/placements/{external-placement-id}: get: tags: - Placement API summary: Get a placement. description: >- Retrieve a V2 placement by external identifier. The external placement identifier matches slotId on public sponsored-brand campaigns. operationId: public_get_placement parameters: - name: external-placement-id in: path required: true schema: type: string description: >- External identifier for the placement. Same value as slotId on public sponsored-brand campaigns. description: >- External identifier for the placement. Same value as slotId on public sponsored-brand campaigns. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Advanced_APIs_Placement' '404': description: Placement or marketplace not found. '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/Advanced_APIs_HTTPValidationError' security: - Advanced_APIs_HTTPBearer: [] components: schemas: Advanced_APIs_Placement: properties: placementId: type: string format: uuid title: Placementid description: Unique identifier for the placement externalPlacementId: type: string maxLength: 255 pattern: ^[A-Za-z0-9_-]+$ title: Externalplacementid description: >- External identifier for the placement. Same value as slotId on public sponsored-brand campaigns. name: type: string maxLength: 50 minLength: 5 title: Name description: Name of the placement logo: description: Logo configuration oneOf: - $ref: '#/components/schemas/Advanced_APIs_Logo' - type: 'null' title: description: Title configuration oneOf: - $ref: '#/components/schemas/Advanced_APIs_Title' - type: 'null' products: $ref: '#/components/schemas/Advanced_APIs_Products' description: Products configuration previewTemplate: $ref: '#/components/schemas/Advanced_APIs_PreviewTemplate' description: Preview template configuration jsonTemplateId: title: Jsontemplateid description: The ID of the JSON template used for the placement oneOf: - type: string format: uuid - type: 'null' jsonTemplate: description: The JSON template used for the placement oneOf: - $ref: '#/components/schemas/Advanced_APIs_JsonTemplate' - type: 'null' createdAt: type: string format: date-time title: Createdat description: The time the placement was created updatedAt: type: string format: date-time title: Updatedat description: The time the placement was last updated type: object required: - placementId - externalPlacementId - name - products - previewTemplate - createdAt - updatedAt title: Placement Advanced_APIs_HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/Advanced_APIs_ValidationError' type: array title: Detail type: object title: HTTPValidationError Advanced_APIs_Logo: properties: min: type: integer maximum: 1 minimum: 1 title: Min description: Minimum number of logos max: type: integer maximum: 1 minimum: 1 title: Max description: Maximum number of logos type: object required: - min - max title: Logo description: >- Logo configuration. Defines the minimum and maximum number of logos that can be added. Advanced_APIs_Title: properties: minLength: type: integer maximum: 250 minimum: 5 title: Minlength description: Minimum title length maxLength: type: integer maximum: 250 minimum: 5 title: Maxlength description: Maximum title length type: object required: - minLength - maxLength title: Title description: >- Title configuration. Defines the minimum and maximum length of the title. Advanced_APIs_Products: properties: min: type: integer maximum: 200 minimum: 0 title: Min description: Minimum products that needs to be chosen max: type: integer maximum: 200 minimum: 0 title: Max description: Maximum products that can be chosen assets: $ref: '#/components/schemas/Advanced_APIs_Assets' description: Asset configuration for products. type: object required: - min - max - assets title: Products description: >- Product placement configuration. Defines how many products can be chosen and how many assets can be added to each product. Advanced_APIs_PreviewTemplate: properties: html: title: Html description: HTML template for previewing the placement oneOf: - type: string - type: 'null' css: title: Css description: CSS template for previewing the placement oneOf: - type: string - type: 'null' type: object title: PreviewTemplate description: Defines how to preview the placement. Advanced_APIs_JsonTemplate: properties: id: type: string format: uuid title: Id description: The ID of the JSON template marketplaceId: type: string format: uuid title: Marketplaceid description: The ID of the marketplace name: type: string title: Name description: The name of the JSON template description: type: string title: Description description: The description of the JSON template isArchived: type: boolean title: Isarchived description: Whether the JSON template is archived default: false previewScreenshot: title: Previewscreenshot description: Preview screenshot of the JSON template oneOf: - type: string maxLength: 2083 minLength: 1 format: uri - type: 'null' previewUrl: title: Previewurl description: Preview URL of the JSON template oneOf: - type: string maxLength: 2083 minLength: 1 format: uri - type: 'null' jsonSchema: additionalProperties: true type: object title: Jsonschema description: The JSON schema of the JSON template createdAt: type: string format: date-time title: Createdat description: The creation time of the JSON template updatedAt: type: string format: date-time title: Updatedat description: The update time of the JSON template adFormat: $ref: '#/components/schemas/Advanced_APIs_JsonTemplateAdFormat' description: The ad format of the JSON template type: object required: - id - marketplaceId - name - description - jsonSchema - createdAt - updatedAt - adFormat title: JsonTemplate Advanced_APIs_ValidationError: properties: loc: items: oneOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError Advanced_APIs_Assets: properties: min: type: integer maximum: 1 minimum: 1 title: Min description: Minimum number of assets max: type: integer maximum: 1 minimum: 1 title: Max description: Maximum number of assets type: object required: - min - max title: Assets description: >- Asset configuration. Defines the minimum and maximum number of assets that can be added. Advanced_APIs_JsonTemplateAdFormat: type: string enum: - banner - sponsored_brand title: JsonTemplateAdFormat description: The type of the ad format of the JSON template. securitySchemes: Advanced_APIs_HTTPBearer: type: http description: >- A valid API key generated in Topsort's UI. Use the TSE API key if calling auctions or events API, otherwise use the TSC API key. scheme: bearer ````