> For the complete documentation index, see [llms.txt](https://developers.citrusad.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.citrusad.com/partner/reference/listplacements.md).

# Returns a list of placements

Returns a list of all placements

{% hint style="info" %}
Epsilon Retail Media's documentation is now centralized with our knowledgebase!

For up to date guides, please view [this page](https://help.citrusad.com/retail-media-interface/partner/global-api/placements/listplacements) in the new Partner APIs space of our documentation.
{% endhint %}

***

### description: "Returns a list of all placements"

## Returns a list of placements

{% hint style="info" %}
Special character restriction

Special characters are currently not allowed in the namespace and environment fields due to backend validation. This limitation will be addressed in the upcoming release.
{% endhint %}

## Returns a list of placements

> Returns a list of all placements

```json
{"openapi":"3.0.0","info":{"title":"Citrus API","version":"1.1.0"},"tags":[{"description":"A placement is a single area of ad space within a retailer's site. Essentially, any placement on the retailer's site that needs to be individually selected will be a placement.","name":"Placements"}],"servers":[{"description":"Production","url":"https://api.citrusad.com/v1"},{"description":"Sandbox","url":"https://sandbox.api.citrusad.com/v1"},{"description":"Development","url":"https://dev-api.citrusad.com/v1"}],"security":[{"BearerToken":[]}],"components":{"securitySchemes":{"BearerToken":{"bearerFormat":"JWT","description":"For accessing the API a valid JWT token must be passed in all queries in\nthe 'Authorization' header. The following syntax must be used in the\n'Authorization' header.<br><br>\n\nBearer xxx.yyy.zzz\n","scheme":"bearer","type":"http"}},"schemas":{"PlacementPaginatedSchema":{"properties":{"links":{"$ref":"#/components/schemas/Links"},"placements":{"items":{"$ref":"#/components/schemas/Placement"},"type":"array"}},"required":["placements"]},"Links":{"properties":{"next":{"description":"The link to navigate to the next page.","type":"string"}},"type":"object"},"Placement":{"properties":{"adGenId":{"description":"Immutable Ad generation identifier","type":"string"},"archived":{"description":"Indicates if the placement is archived. Placement still exists and existing campaigns with this placement still work, but creating new one is not possible.","type":"boolean"},"blockedFilters":{"description":"Blocked filters for campaign requests","items":{"description":"Blocked filter","type":"string"},"type":"array"},"campaignTypes":{"description":"Array of campaign types supported by the placement","items":{"$ref":"#/components/schemas/CampaignType"},"minItems":1,"readOnly":true,"type":"array","uniqueItems":true},"catalogIds":{"description":"Array of catalog IDs associated with the placement","items":{"description":"Unique identifier of a catalog","type":"string"},"minItems":1,"type":"array","uniqueItems":true},"customTooltipText":{"description":"Custom tooltip text","type":"string"},"displayName":{"description":"Human readable name of the placement. Useful for showing within a client application","type":"string"},"id":{"description":"Unique identifier of the placement","readOnly":true,"type":"string"},"namespace":{"description":"Namespace for the placement","type":"string"},"targeting":{"$ref":"#/components/schemas/PlacementTargeting"}},"required":["id","adGenId","displayName","catalogIds","campaignTypes","namespace","targeting","blockedFilters"],"type":"object"},"CampaignType":{"description":"The type of campaign supported by Citrus Ad","enum":["BANNER","DISPLAY","BANNER_X","BRAND_PAGE"],"type":"string"},"PlacementTargeting":{"description":"The type of ad placement the campaign will target. For example, if the campaignTarget is SEARCH_ONLY then these will be search ads and the relevant configuration for this ad type is described in SearchConfig.","properties":{"campaignTarget":{"$ref":"#/components/schemas/CampaignTarget"},"categoryConfig":{"$ref":"#/components/schemas/CategoryConfig"},"customTargetedLocationsAllowed":{"description":"Indicates if custom targeted locations are allowed","type":"boolean"},"searchConfig":{"$ref":"#/components/schemas/SearchConfig"}},"required":["customTargetedLocationsAllowed"],"type":"object"},"CampaignTarget":{"description":"Targeting strategy for campaigns","enum":["SEARCH_ONLY","CATEGORY_AND_SEARCH","CATEGORY_ONLY","BROAD_DISPLAY","CROSS_SELL","UPSELL","RUN_OF_SITE","CATEGORY_CROSS_SELL"],"type":"string"},"CategoryConfig":{"description":"Configuration for category targeting, only available when `campaignTarget` is CATEGORY_ONLY or CATEGORY_AND_SEARCH","properties":{"customTargetedCategoriesAllowed":{"description":"Indicates if custom targeted categories are allowed","type":"boolean"}},"required":["customTargetedCategoriesAllowed"],"type":"object"},"SearchConfig":{"description":"Configuration for search targeting, only available when `campaignTarget` is SEARCH_ONLY","properties":{"customSearchTermAllowed":{"description":"Indicates if custom search terms are allowed","type":"boolean"},"searchTermTypeLabel":{"description":"Label for search term type","type":"string"},"suggestedSearchTermEnabled":{"description":"Indicates if suggested search terms are enabled","type":"boolean"},"suggestedSearchTermType":{"$ref":"#/components/schemas/SearchTermType"}},"required":["suggestedSearchTermEnabled","customSearchTermAllowed"],"type":"object"},"SearchTermType":{"description":"Type of suggested search term","enum":["CROSS_SELL","ORGANIC","SUBSTITUTE","UNDEFINED"],"type":"string"},"Error":{"properties":{"message":{"description":"Error message returned from the API","type":"string"}},"required":["message"],"type":"object"}},"responses":{"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized. This request could not be processed due to an invalid token.<br><br>\nPossible example error messages:<br> - `Unauthorized`<br> - `Failed to parse token`: The token is not in the correct format, or has expired.<br> - `token can't be empty`: Missing Authorization Bearer token in header\n"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden. This request could not be processed due a token that does not have permission to access the requested resource.<br><br>\nPossible example error messages:<br> - `Forbidden`\n"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too many requests. This request could not be processed as the rate limit has been exceeded.<br><br>\nPossible example error messages:<br> - `Too many requests`\n"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Generic Error. The request could not be processed due to an unknown error.<br><br>\n"}}},"paths":{"/placements":{"get":{"description":"Returns a list of all placements","operationId":"listPlacements","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlacementPaginatedSchema"}}},"description":"Expected response to a valid request"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"429":{"$ref":"#/components/responses/429"},"default":{"$ref":"#/components/responses/default"}},"summary":"Returns a list of placements","tags":["Placements"]}}}}
```