# Get recommendations by campaign

- Operation ID: `GetRecommendationsByCampaignV2`
- HTTP method: `GET`
- Path: `/recommendations/v2/recommend/campaigns/{campaignIdentifier}`
- [Human-readable API reference](https://hub.synerise.com/api-reference/ai-recommendations#tag/Recommendations/operation/GetRecommendationsByCampaignV2)

## Self-contained OpenAPI method

The fenced document below contains this method's documentation and all of its local references. It is self-contained; no category or master specification fetch is required.

```yaml
openapi: 3.0.0
info:
  title: Synerise Public API
  version: 1.9.1
paths:
  /recommendations/v2/recommend/campaigns/{campaignIdentifier}:
    get:
      summary: Get recommendations by campaign
      description: |
        This method allows you to retrieve recommendations based on a campaignID or a slug and a context. The context is built based on:

          - campaign identifier (required)
          - profile UUID
          - items (for example, items currently in the basket)
          - item exclusions


          This is the recommended and simplest way to fetch recommendations.

          Before you use this method, you must to create a recommendations campaign in Synerise. All the recommendation filters and parameters will be handled for you automatically according to a campaign's configuration.


        ---

        **API consumers:** <span title="Deprecated">AI API key (legacy)</span>, <a href="/docs/settings/tool/tracking_codes" target="_blank" rel="noopener" title="Pass your tracker key in the request header">Web SDK Tracker</a>, <a href="/api-reference/authorization?tag=Authorization&amp;operationId=profileLogin" target="_blank" rel="noopener">Workspace (Business Profile)</a>

        **API key permission required:** `API_MATERIALIZER_V2_RECOMMEND_CAMPAIGNS_RECOMMENDATIONS_READ`
      operationId: GetRecommendationsByCampaignV2
      security:
        - TrackerKey: []
        - JWT: []
      tags:
        - Recommendations
      parameters:
        - name: campaignIdentifier
          in: path
          description: Recommendation campaign identifier - a campaignID or a slug
          required: true
          schema:
            type: string
        - in: query
          name: clientUUID
          description: |
            Profile UUID. This parameter is required for these recommendation types:
              - Personalized
              - Last seen
              - Recent interactions
              - Section
              - Attribute

            This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
          required: false
          schema:
            type: string
        - name: itemId
          in: query
          description: |
            Item ID or item IDs for the recommendation context. This parameter is:

            - required for similar/complementary items campaigns.

            - optional for personalized campaigns.

            This parameter can be passed in all recommendations. In recommendations which don't use the context item as part of the recommendation model, the context item can only be used to create filters.

            You can repeat this parameter in order to pass a number of context-creating items, for example, in a cart recommendation campaign.

            This overrides the `itemsSource` settings of the campaign definition.

            Alternatively, you can pass the `itemsSourceType` and `itemsSourceId` parameters to use context items from source (aggregate or expression). These parameters can't be used at the same request with `itemId`.
          required: false
          schema:
            type: string
        - name: inventoryChannelId
          in: query
          description: Inventory context identifier used to evaluate inventory-related filters and boosting strategies. If not provided, no inventory context will be applied.
          required: false
          schema:
            type: string
        - in: query
          name: itemsSourceType
          description: |
            Item ID or item IDs source type for the recommendation context.

            Must be used with `itemSourceId`. This overrides the `itemsSource` settings of the campaign definition.

            In recommendations whose models doesn't use the item context, the attributes of those items can only be used in filters.  

            If the items' source type is 'aggregate', the aggregate result will be used as context items. If the items' source type is 'expression', the expression result will be used as context items.

            The item ID source (aggregate or expression) should return a string or an array of strings. If it returns numerical values, the recommendations engine attempts to convert them into strings while processing the request.

            Alternatively, you can pass the `itemId` parameter to define context items directly. Only one of these options is allowed at the same time.
          required: false
          schema:
            type: string
            enum:
              - aggregate
              - expression
        - in: query
          name: itemsSourceId
          description: |
            Source of item IDs for the recommendation context. In recommendations whose models doesn't use the item context, the attributes of those items can only be used in filters.

            Must be used with `itemsSourceType`.

            If the items' source type is 'aggregate', this is the aggregate's ID. If the items' source type is 'expression', this is the expression's ID.

            The item ID source (aggregate or expression) should return a string or an array of strings. If it returns numerical values, the recommendations engine attempts to convert them into strings while processing the request.

            Alternatively, you can pass the `itemId` parameter to define context items directly. Only one of these options is allowed at the same time.
          required: false
          schema:
            type: string
        - name: externalItemId
          in: query
          description: |
            Items provided by an external recommendation model to be returned as recommendation results.

            You can repeat this parameter to pass multiple external items.

            This parameter is used with campaigns of type "external-items".
          required: false
          schema:
            type: string
        - name: itemIdExcluded
          in: query
          description: IDs of items that will be excluded from the generated recommendations. For example, items already added to the basket.
          required: false
          schema:
            type: string
        - name: additionalFilters
          in: query
          required: false
          schema:
            type: string
          description: |
            <hr>
            <strong>IMPORTANT</strong>:

            - The `filtersJoiner` attribute is REQUIRED when `additionalFilters` is included. If `filtersJoiner` is missing, the additional filters do not work.  
            - Do NOT send multiple instances of this parameter.

            <hr>

            Additional filters. These are merged with the campaign's own filters according to the logic in `filtersJoiner`.

            This parameter must include all the additional filters as a single string, for example `additionalFilters=effectivePrice>300 AND effectivePrice<400` (the spaces are required).
          example: effectivePrice>300 AND effectivePrice<400
        - name: filtersJoiner
          in: query
          required: false
          schema:
            type: string
            enum:
              - AND
              - OR
              - REPLACE
          description: |
            Defines the logic of merging `additionalFilters` with the campaign's existing filters.
            - `REPLACE` replaces the campaign's filters with your filters.
            - `AND` matches if both your filters and the campaign filters are met.
            - `OR` matches if at least one of the filters is met.
        - name: additionalElasticFilters
          in: query
          required: false
          schema:
            type: string
          description: |
            <hr>
            <strong>IMPORTANT</strong>:

            - The `elasticFiltersJoiner` attribute is REQUIRED when `additionalElasticFilters` is included. If `elasticFiltersJoiner` is missing, the additional filters do not work.  
            - Do NOT send multiple instances of this parameter.

            <hr>

            Additional elastic filters. These are merged with the campaign's own elastic filters according to the logic in `elasticFiltersJoiner`.

            This parameter must include all the additional filters as a single string, for example `additionalElasticFilters=effectivePrice>300 AND effectivePrice<400` (the spaces are required).
          example: effectivePrice>300 AND effectivePrice<400
        - name: elasticFiltersJoiner
          in: query
          required: false
          schema:
            type: string
            enum:
              - AND
              - OR
              - REPLACE
          description: |
            Defines the logic of merging `additionalElasticFilters` with the campaign's existing elastic filters.
            - `REPLACE` replaces the campaign's filters with your filters.
            - `AND` matches if both your filters and the campaign filters are met.
            - `OR` matches if at least one of the filters is met.
        - name: displayAttribute
          in: query
          required: false
          schema:
            type: string
          description: Item attribute whose value will be returned in the recommendation response. The parameter value will be merged with the configuration of the recommendation. This parameter can be passed multiple times.
        - name: includeContextItems
          in: query
          description: When true, the recommendation response will include context items metadata.
          required: false
          schema:
            type: boolean
        - name: params
          in: query
          required: false
          description: |
            List of extra params that will be added to the `recommendation.generated` event. They must be in the `name:value` format. The total size must not exceed 500 bytes when written as a JSON object.
          example:
            - source:mobile
          schema:
            type: array
            items:
              type: string
      responses:
        "200":
          description: Recommendations for the provided context. The response schema depends on your Workspace configuration. The schema below only includes the static elements.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: Recommended items
                    items:
                      type: object
                      properties:
                        itemId:
                          type: string
                          description: Item identifier
                      required:
                        - itemId
                  extras:
                    type: object
                    description: Additional data
                    properties:
                      correlationId:
                        type: string
                        description: Correlation identifier of a recommendation request
                      contextItems:
                        type: array
                        description: A list of context items provided in request
                        items:
                          type: object
                          properties:
                            itemId:
                              type: string
                              description: Item identifier (`itemId` in item catalog)
                          additionalProperties: {}
                          required:
                            - itemId
                      slots:
                        type: array
                        description: A list of slots data
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              description: Slot identifier. Matches the index (zero-based numbering) of the slot provided in request
                            name:
                              type: string
                              description: Slot name provided in request
                            itemIds:
                              type: array
                              description: A list of item ids that meet the slot criteria
                              items:
                                type: string
                                description: Item identifier (`itemId` in item catalog)
                            error:
                              type: object
                              description: Error details, if applicable
                              properties:
                                status:
                                  type: integer
                                  description: Status code
                                error:
                                  type: string
                                  description: Summary of the error
                                message:
                                  type: string
                                  description: Description of the problem
                              required:
                                - status
                                - error
                                - message
                          required:
                            - id
                            - itemIds
                    required:
                      - correlationId
                      - slots
        "404":
          description: No recommendations could be generated for the specified campaign and context.
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    format: date-time
                    description: Time when the error occurred
                  status:
                    type: integer
                    description: Status code
                  error:
                    type: string
                    description: Summary of the error
                  message:
                    type: string
                    description: Description of the problem
                  path:
                    type: string
                    description: URL of the requested resource
                required:
                  - timestamp
                  - status
                  - message
        "500":
          description: An error occurred
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    format: date-time
                    description: Time when the error occurred
                  status:
                    type: integer
                    description: Status code
                  error:
                    type: string
                    description: Summary of the error
                  message:
                    type: string
                    description: Description of the problem
                  path:
                    type: string
                    description: URL of the requested resource
                required:
                  - timestamp
                  - status
                  - message
      x-snr-doc-urls:
        - /api-reference/ai-recommendations#tag/Recommendations/operation/GetRecommendationsByCampaignV2
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: |-
            curl --request GET \
              --url 'https://api.synerise.com/recommendations/v2/recommend/campaigns/%7BcampaignIdentifier%7D?clientUUID=SOME_STRING_VALUE&itemId=SOME_STRING_VALUE&inventoryChannelId=SOME_STRING_VALUE&itemsSourceType=SOME_STRING_VALUE&itemsSourceId=SOME_STRING_VALUE&externalItemId=SOME_STRING_VALUE&itemIdExcluded=SOME_STRING_VALUE&additionalFilters=effectivePrice%3E300%20AND%20effectivePrice%3C400&filtersJoiner=SOME_STRING_VALUE&additionalElasticFilters=effectivePrice%3E300%20AND%20effectivePrice%3C400&elasticFiltersJoiner=SOME_STRING_VALUE&displayAttribute=SOME_STRING_VALUE&includeContextItems=SOME_BOOLEAN_VALUE&params=source%3Amobile' \
              --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
        - lang: Python
          label: Python
          source: |-
            import http.client

            conn = http.client.HTTPSConnection("api.synerise.com")

            headers = { 'Authorization': "Bearer REPLACE_BEARER_TOKEN" }

            conn.request("GET", "/recommendations/v2/recommend/campaigns/%7BcampaignIdentifier%7D?clientUUID=SOME_STRING_VALUE&itemId=SOME_STRING_VALUE&inventoryChannelId=SOME_STRING_VALUE&itemsSourceType=SOME_STRING_VALUE&itemsSourceId=SOME_STRING_VALUE&externalItemId=SOME_STRING_VALUE&itemIdExcluded=SOME_STRING_VALUE&additionalFilters=effectivePrice%3E300%20AND%20effectivePrice%3C400&filtersJoiner=SOME_STRING_VALUE&additionalElasticFilters=effectivePrice%3E300%20AND%20effectivePrice%3C400&elasticFiltersJoiner=SOME_STRING_VALUE&displayAttribute=SOME_STRING_VALUE&includeContextItems=SOME_BOOLEAN_VALUE&params=source%3Amobile", headers=headers)

            res = conn.getresponse()
            data = res.read()

            print(data.decode("utf-8"))
        - lang: JavaScript
          label: JavaScript
          source: |-
            const data = null;

            const xhr = new XMLHttpRequest();
            xhr.withCredentials = true;

            xhr.addEventListener("readystatechange", function () {
              if (this.readyState === this.DONE) {
                console.log(this.responseText);
              }
            });

            xhr.open("GET", "https://api.synerise.com/recommendations/v2/recommend/campaigns/%7BcampaignIdentifier%7D?clientUUID=SOME_STRING_VALUE&itemId=SOME_STRING_VALUE&inventoryChannelId=SOME_STRING_VALUE&itemsSourceType=SOME_STRING_VALUE&itemsSourceId=SOME_STRING_VALUE&externalItemId=SOME_STRING_VALUE&itemIdExcluded=SOME_STRING_VALUE&additionalFilters=effectivePrice%3E300%20AND%20effectivePrice%3C400&filtersJoiner=SOME_STRING_VALUE&additionalElasticFilters=effectivePrice%3E300%20AND%20effectivePrice%3C400&elasticFiltersJoiner=SOME_STRING_VALUE&displayAttribute=SOME_STRING_VALUE&includeContextItems=SOME_BOOLEAN_VALUE&params=source%3Amobile");
            xhr.setRequestHeader("Authorization", "Bearer REPLACE_BEARER_TOKEN");

            xhr.send(data);
        - lang: Node.js
          label: Node.js
          source: |-
            const http = require("https");

            const options = {
              "method": "GET",
              "hostname": "api.synerise.com",
              "port": null,
              "path": "/recommendations/v2/recommend/campaigns/%7BcampaignIdentifier%7D?clientUUID=SOME_STRING_VALUE&itemId=SOME_STRING_VALUE&inventoryChannelId=SOME_STRING_VALUE&itemsSourceType=SOME_STRING_VALUE&itemsSourceId=SOME_STRING_VALUE&externalItemId=SOME_STRING_VALUE&itemIdExcluded=SOME_STRING_VALUE&additionalFilters=effectivePrice%3E300%20AND%20effectivePrice%3C400&filtersJoiner=SOME_STRING_VALUE&additionalElasticFilters=effectivePrice%3E300%20AND%20effectivePrice%3C400&elasticFiltersJoiner=SOME_STRING_VALUE&displayAttribute=SOME_STRING_VALUE&includeContextItems=SOME_BOOLEAN_VALUE&params=source%3Amobile",
              "headers": {
                "Authorization": "Bearer REPLACE_BEARER_TOKEN"
              }
            };

            const req = http.request(options, function (res) {
              const chunks = [];

              res.on("data", function (chunk) {
                chunks.push(chunk);
              });

              res.on("end", function () {
                const body = Buffer.concat(chunks);
                console.log(body.toString());
              });
            });

            req.end();
        - lang: PHP
          label: PHP
          source: |-
            <?php

            $request = new HttpRequest();
            $request->setUrl('https://api.synerise.com/recommendations/v2/recommend/campaigns/%7BcampaignIdentifier%7D');
            $request->setMethod(HTTP_METH_GET);

            $request->setQueryData([
              'clientUUID' => 'SOME_STRING_VALUE',
              'itemId' => 'SOME_STRING_VALUE',
              'inventoryChannelId' => 'SOME_STRING_VALUE',
              'itemsSourceType' => 'SOME_STRING_VALUE',
              'itemsSourceId' => 'SOME_STRING_VALUE',
              'externalItemId' => 'SOME_STRING_VALUE',
              'itemIdExcluded' => 'SOME_STRING_VALUE',
              'additionalFilters' => 'effectivePrice>300 AND effectivePrice<400',
              'filtersJoiner' => 'SOME_STRING_VALUE',
              'additionalElasticFilters' => 'effectivePrice>300 AND effectivePrice<400',
              'elasticFiltersJoiner' => 'SOME_STRING_VALUE',
              'displayAttribute' => 'SOME_STRING_VALUE',
              'includeContextItems' => 'SOME_BOOLEAN_VALUE',
              'params' => 'source:mobile'
            ]);

            $request->setHeaders([
              'Authorization' => 'Bearer REPLACE_BEARER_TOKEN'
            ]);

            try {
              $response = $request->send();

              echo $response->getBody();
            } catch (HttpException $ex) {
              echo $ex;
            }
        - lang: Java
          label: Java
          source: |-
            HttpResponse<String> response = Unirest.get("https://api.synerise.com/recommendations/v2/recommend/campaigns/%7BcampaignIdentifier%7D?clientUUID=SOME_STRING_VALUE&itemId=SOME_STRING_VALUE&inventoryChannelId=SOME_STRING_VALUE&itemsSourceType=SOME_STRING_VALUE&itemsSourceId=SOME_STRING_VALUE&externalItemId=SOME_STRING_VALUE&itemIdExcluded=SOME_STRING_VALUE&additionalFilters=effectivePrice%3E300%20AND%20effectivePrice%3C400&filtersJoiner=SOME_STRING_VALUE&additionalElasticFilters=effectivePrice%3E300%20AND%20effectivePrice%3C400&elasticFiltersJoiner=SOME_STRING_VALUE&displayAttribute=SOME_STRING_VALUE&includeContextItems=SOME_BOOLEAN_VALUE&params=source%3Amobile")
              .header("Authorization", "Bearer REPLACE_BEARER_TOKEN")
              .asString();
servers:
  - description: Microsoft Azure EU
    url: https://api.synerise.com
  - description: Microsoft Azure USA
    url: https://api.azu.synerise.com
  - description: Google Cloud Platform
    url: https://api.geb.synerise.com
tags:
  - name: Recommendations
components:
  securitySchemes:
    TrackerKey:
      type: apiKey
      name: token
      in: query
      description: Authorization by tracker key sent as a query parameter. This is the same key as used in the website tracking code.
    JWT:
      type: http
      scheme: bearer
      description: |-
        JWT Bearer token. The header looks like this: `Bearer {JWT}`

        Remember to include the space between 'Bearer' and the token.

        Generate a token via the **Authorization** endpoints.
```