# Add mapping

- Operation ID: `addMapping`
- HTTP method: `POST`
- Path: `/catalogs/bags/{catalogId}/mappings`
- [Human-readable API reference](https://hub.synerise.com/api-reference/data-management#tag/Catalogs/operation/addMapping)

## 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:
  /catalogs/bags/{catalogId}/mappings:
    post:
      tags:
        - Catalogs
      summary: Add mapping
      description: |
        Add a new mapping. Mappings can be used to enrich events with data from catalogs.

        For example, you can map the product's SKU from the "product.buy" event to the column in the catalog that includes the SKU. Whenever someone purchases an item with that SKU, you can extract data from the catalog (for example, the product's brand and category) and show that additional in the event log in the Synerise GUI.

        ---

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

        **API key permission required:** `CATALOGS_MAPPING_CATALOG_CREATE`

        **User role permission required:** `assets_catalogs: create`
      operationId: addMapping
      security:
        - JWT: []
      parameters:
        - in: path
          name: catalogId
          description: ID of the catalog
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  description: The `action` field of the event
                  example: transaction.charge
                paramKey:
                  type: string
                  description: The parameter in the event that corresponds to the catalog column with the unique identifiers
                  example: sku
      responses:
        "200":
          description: Mapping data
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: Details of the mapping
                    properties:
                      bpActionParamKey:
                        type: string
                        description: The unique identifier of this mapping
                      bagId:
                        type: integer
                        description: The catalog associated with this mapping
                      action:
                        type: string
                        description: The `action` field of the event
                        example: transaction.charge
                      paramKey:
                        type: string
                        description: The parameter in the event that corresponds to the catalog column with the unique identifiers
                        example: sku
                      enrichmentFields:
                        type: array
                        items:
                          type: string
                        description: enrichment fields
                  metaData:
                    type: object
                    description: This object holds the metadata of the response.
                    properties:
                      totalCount:
                        type: integer
                        description: The total number of matching values (key-value pairs; array items; objects) in the database
                      requestTime:
                        type: string
                        description: The processing time of the request
                        example: 0.11 [s]
        "400":
          description: Invalid or insufficient data
          content:
            text/plain:
              schema:
                type: string
        "401":
          description: "Unauthorized: token missing/expired/invalid; invalid API key; etc."
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: Status code
                  error:
                    type: string
                    description: Error summary
                  message:
                    type: string
                    description: Error message
                  timestamp:
                    type: string
                    description: Time when the error occurred
        "403":
          description: "Forbidden: insufficient permissions; wrong consumer scope"
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: Status code
                  error:
                    type: string
                    description: Error summary
                  message:
                    type: string
                    description: Error message
                  timestamp:
                    type: string
                    description: Time when the error occurred
        "404":
          description: Entity not found
          content:
            text/plain:
              schema:
                type: string
      x-snr-doc-urls:
        - /api-reference/data-management#tag/Catalogs/operation/addMapping
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: |-
            curl --request POST \
              --url https://api.synerise.com/catalogs/bags/%7BcatalogId%7D/mappings \
              --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
              --header 'content-type: application/json' \
              --data '{"action":"transaction.charge","paramKey":"sku"}'
        - lang: Python
          label: Python
          source: |-
            import http.client

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

            payload = "{\"action\":\"transaction.charge\",\"paramKey\":\"sku\"}"

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

            conn.request("POST", "/catalogs/bags/%7BcatalogId%7D/mappings", payload, headers)

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

            print(data.decode("utf-8"))
        - lang: JavaScript
          label: JavaScript
          source: |-
            const data = JSON.stringify({
              "action": "transaction.charge",
              "paramKey": "sku"
            });

            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/catalogs/bags/%7BcatalogId%7D/mappings");
            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": "/catalogs/bags/%7BcatalogId%7D/mappings",
              "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({action: 'transaction.charge', paramKey: 'sku'}));
            req.end();
        - lang: PHP
          label: PHP
          source: |-
            <?php

            $request = new HttpRequest();
            $request->setUrl('https://api.synerise.com/catalogs/bags/%7BcatalogId%7D/mappings');
            $request->setMethod(HTTP_METH_POST);

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

            $request->setBody('{"action":"transaction.charge","paramKey":"sku"}');

            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/catalogs/bags/%7BcatalogId%7D/mappings")
              .header("Authorization", "Bearer REPLACE_BEARER_TOKEN")
              .header("content-type", "application/json")
              .body("{\"action\":\"transaction.charge\",\"paramKey\":\"sku\"}")
              .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: Catalogs
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.
```