# Get recommendations by campaign and profile identifier

- Operation ID: `PostRecommendationsByCampaignAndidentifierNameV2`
- HTTP method: `POST`
- Path: `/recommendations/v2/recommend/campaigns/{campaignIdentifier}/by/{identifierName}`
- [Human-readable API reference](https://hub.synerise.com/api-reference/campaigns#operation/PostRecommendationsByCampaignAndidentifierNameV2)

## 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}/by/{identifierName}:
    post:
      summary: Get recommendations by campaign and profile identifier
      description: |
        
        **Before you use this method**: you must [create a recommendations campaign in Synerise](https://help.synerise.com/docs/campaign/recommendations-v2/). All the recommendation filters and parameters will be handled for you automatically according to a campaign's configuration.

        The method allows you to retrieve recommendations based on a campaignID or a slug, profile's identifier name (the value of the identifier is provided in the request body), and a context. The context is built based on:

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


        ---

        **API consumers:** <a href="/api-reference/authorization?tag=Authorization&amp;operationId=profileLogin" target="_blank" rel="noopener">Workspace (Business Profile)</a>, <a href="/api-reference/authorization?tag=Authorization&amp;operationId=userLogin" target="_blank" rel="noopener">Synerise User</a>

        **API key permission required:** `API_MATERIALIZER_V2_RECOMMEND_WITH_CUSTOM_ID_RECOMMENDATIONS_READ`

        **User role permission required:** `campaigns_recommendations: read`
      operationId: PostRecommendationsByCampaignAndidentifierNameV2
      security:
        - JWT: []
      tags:
        - Recommendations
      parameters:
        - name: campaignIdentifier
          in: path
          description: Recommendation campaign identifier - a campaignID or a slug
          required: true
          schema:
            type: string
        - name: identifierName
          in: path
          description: The name of the profile identifier to use for the request. By default, the allowed identifier types are `id`, `uuid`, `email`, and `custom_identify`. This may be changed in the workspace configuration.
          required: true
          schema:
            type: string
            enum:
              - id
              - uuid
              - email
              - custom_identify
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - type: object
                  required:
                    - identifierValue
                  properties:
                    identifierValue:
                      type: string
                      description: Value of the identifier selected in the path attributes
                - type: object
                  properties:
                    items:
                      type: array
                      description: |
                        An array of item identifiers (`itemId` in the item feed) for the context. This could be, for example, the current basket, or the item that is currently being viewed.  

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

                        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.

                        Alternatively, you can use the `itemsSource` object to get item IDs from an aggregate or expression. `items` and `itemsSource` can't be used at the same time.
                      items:
                        type: string
                        description: "`itemId` from the item feed"
                    itemsSource:
                      type: object
                      description: |
                        Source of the Item ID or item IDs for the recommendation context.

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

                        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.

                        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.
                      properties:
                        type:
                          type: string
                          enum:
                            - aggregate
                            - expression
                          description: Type of the items' source.
                        id:
                          type: string
                          description: ID of the items' source (aggregate or expression)
                    itemsExcluded:
                      type: array
                      minItems: 0
                      description: Items (identified by `itemId` in the item feed) that will be excluded from the generated recommendations. For example, items already added to the basket.
                      items:
                        type: string
                        description: Items (identified by `itemId` in the item feed) that will be excluded from the generated recommendations. For example, items already added to the basket.
                    additionalFilters:
                      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
                    filtersJoiner:
                      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.
                    additionalElasticFilters:
                      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
                    elasticFiltersJoiner:
                      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.
                    displayAttributes:
                      type: array
                      minItems: 0
                      items:
                        type: string
                      description: An array of item attributes which value will be returned in a recommendation response. The array will be merged together with the configuration of the recommendation.
                    includeContextItems:
                      type: boolean
                      description: When true, the recommendation response will include context items metadata.
                    recommendedItemsFromExternalModel:
                      type: array
                      minItems: 0
                      items:
                        type: array
                        items:
                          type: string
                      description: |
                        Items provided by an external recommendation model to be returned as recommendation results.

                        This parameter is used with campaigns of type "external-items".
                    inventoryContext:
                      description: |
                        Inventory context used to evaluate inventory-related filters and boosting strategies.
                        Can be either a single inventory context or
                        a multi-inventory context (set of channel IDs per inventory).
                      oneOf:
                        - type: object
                          description: |
                            Single inventory context.
                          properties:
                            channelIds:
                              type: array
                              items:
                                type: string
                              description: |
                                List of channel identifiers used to evaluate inventory-related filters and boosting strategies.
                          required:
                            - channelIds
                        - type: object
                          description: |
                            Multi-inventory context where each inventory can have its own set of channel IDs.
                          properties:
                            inventoryCatalogs:
                              type: object
                              additionalProperties:
                                type: object
                                description: |
                                  Context definition for a specific inventory.
                                properties:
                                  channelIds:
                                    type: array
                                    items:
                                      type: string
                                    description: |
                                      List of channel identifiers for this specific inventory.
                              description: |
                                Map of inventory ID to inventory context definition. Each inventory can have its own set of channel IDs.
                          required:
                            - inventoryCatalogs
                    params:
                      type: object
                      example:
                        source: mobile
                      description: Extra parameters that will be added to the `recommendation.generated` event. The total size must not exceed 500 bytes.
                      additionalProperties: true
      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/PostRecommendationsByCampaignAndidentifierNameV2
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: |-
            curl --request POST \
              --url https://api.synerise.com/recommendations/v2/recommend/campaigns/%7BcampaignIdentifier%7D/by/%7BidentifierName%7D \
              --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
              --header 'content-type: application/json' \
              --data '{"identifierValue":"string","items":["string"],"itemsSource":{"type":"aggregate","id":"string"},"itemsExcluded":["string"],"additionalFilters":"effectivePrice>300 AND effectivePrice<400","filtersJoiner":"AND","additionalElasticFilters":"effectivePrice>300 AND effectivePrice<400","elasticFiltersJoiner":"AND","displayAttributes":["string"],"includeContextItems":true,"recommendedItemsFromExternalModel":[["string"]],"inventoryContext":{"channelIds":["string"]},"params":{"source":"mobile"}}'
        - lang: Python
          label: Python
          source: |-
            import http.client

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

            payload = "{\"identifierValue\":\"string\",\"items\":[\"string\"],\"itemsSource\":{\"type\":\"aggregate\",\"id\":\"string\"},\"itemsExcluded\":[\"string\"],\"additionalFilters\":\"effectivePrice>300 AND effectivePrice<400\",\"filtersJoiner\":\"AND\",\"additionalElasticFilters\":\"effectivePrice>300 AND effectivePrice<400\",\"elasticFiltersJoiner\":\"AND\",\"displayAttributes\":[\"string\"],\"includeContextItems\":true,\"recommendedItemsFromExternalModel\":[[\"string\"]],\"inventoryContext\":{\"channelIds\":[\"string\"]},\"params\":{\"source\":\"mobile\"}}"

            headers = {
                'Authorization': "Bearer REPLACE_BEARER_TOKEN",
                'content-type': "application/json"
                }

            conn.request("POST", "/recommendations/v2/recommend/campaigns/%7BcampaignIdentifier%7D/by/%7BidentifierName%7D", payload, headers)

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

            print(data.decode("utf-8"))
        - lang: JavaScript
          label: JavaScript
          source: |-
            const data = JSON.stringify({
              "identifierValue": "string",
              "items": [
                "string"
              ],
              "itemsSource": {
                "type": "aggregate",
                "id": "string"
              },
              "itemsExcluded": [
                "string"
              ],
              "additionalFilters": "effectivePrice>300 AND effectivePrice<400",
              "filtersJoiner": "AND",
              "additionalElasticFilters": "effectivePrice>300 AND effectivePrice<400",
              "elasticFiltersJoiner": "AND",
              "displayAttributes": [
                "string"
              ],
              "includeContextItems": true,
              "recommendedItemsFromExternalModel": [
                [
                  "string"
                ]
              ],
              "inventoryContext": {
                "channelIds": [
                  "string"
                ]
              },
              "params": {
                "source": "mobile"
              }
            });

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

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

            xhr.open("POST", "https://api.synerise.com/recommendations/v2/recommend/campaigns/%7BcampaignIdentifier%7D/by/%7BidentifierName%7D");
            xhr.setRequestHeader("Authorization", "Bearer REPLACE_BEARER_TOKEN");
            xhr.setRequestHeader("content-type", "application/json");

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

            const options = {
              "method": "POST",
              "hostname": "api.synerise.com",
              "port": null,
              "path": "/recommendations/v2/recommend/campaigns/%7BcampaignIdentifier%7D/by/%7BidentifierName%7D",
              "headers": {
                "Authorization": "Bearer REPLACE_BEARER_TOKEN",
                "content-type": "application/json"
              }
            };

            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.write(JSON.stringify({
              identifierValue: 'string',
              items: ['string'],
              itemsSource: {type: 'aggregate', id: 'string'},
              itemsExcluded: ['string'],
              additionalFilters: 'effectivePrice>300 AND effectivePrice<400',
              filtersJoiner: 'AND',
              additionalElasticFilters: 'effectivePrice>300 AND effectivePrice<400',
              elasticFiltersJoiner: 'AND',
              displayAttributes: ['string'],
              includeContextItems: true,
              recommendedItemsFromExternalModel: [['string']],
              inventoryContext: {channelIds: ['string']},
              params: {source: 'mobile'}
            }));
            req.end();
        - lang: PHP
          label: PHP
          source: |-
            <?php

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

            $request->setHeaders([
              'Authorization' => 'Bearer REPLACE_BEARER_TOKEN',
              'content-type' => 'application/json'
            ]);

            $request->setBody('{"identifierValue":"string","items":["string"],"itemsSource":{"type":"aggregate","id":"string"},"itemsExcluded":["string"],"additionalFilters":"effectivePrice>300 AND effectivePrice<400","filtersJoiner":"AND","additionalElasticFilters":"effectivePrice>300 AND effectivePrice<400","elasticFiltersJoiner":"AND","displayAttributes":["string"],"includeContextItems":true,"recommendedItemsFromExternalModel":[["string"]],"inventoryContext":{"channelIds":["string"]},"params":{"source":"mobile"}}');

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

              echo $response->getBody();
            } catch (HttpException $ex) {
              echo $ex;
            }
        - lang: Java
          label: Java
          source: |-
            HttpResponse<String> response = Unirest.post("https://api.synerise.com/recommendations/v2/recommend/campaigns/%7BcampaignIdentifier%7D/by/%7BidentifierName%7D")
              .header("Authorization", "Bearer REPLACE_BEARER_TOKEN")
              .header("content-type", "application/json")
              .body("{\"identifierValue\":\"string\",\"items\":[\"string\"],\"itemsSource\":{\"type\":\"aggregate\",\"id\":\"string\"},\"itemsExcluded\":[\"string\"],\"additionalFilters\":\"effectivePrice>300 AND effectivePrice<400\",\"filtersJoiner\":\"AND\",\"additionalElasticFilters\":\"effectivePrice>300 AND effectivePrice<400\",\"elasticFiltersJoiner\":\"AND\",\"displayAttributes\":[\"string\"],\"includeContextItems\":true,\"recommendedItemsFromExternalModel\":[[\"string\"]],\"inventoryContext\":{\"channelIds\":[\"string\"]},\"params\":{\"source\":\"mobile\"}}")
              .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:
    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.
```