# Add mapping
- Operation ID: `addMapping`
- HTTP method: `POST`
- Path: `/catalogs/bags/{catalogId}/mappings`
- [Human-readable API reference](https://hub.synerise.com/api-reference/asset-management#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.5
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:** Synerise User, Workspace (Business Profile)
**API key permission required:** `CATALOGS_MAPPING_CATALOG_CREATE`
**User role permission required:** `assets_catalogs: create`
operationId: addMapping
security:
- JWT: []
- BasicAuth: []
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: Basic REPLACE_BASIC_AUTH' \
--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': "Basic REPLACE_BASIC_AUTH",
'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", "Basic REPLACE_BASIC_AUTH");
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": "Basic REPLACE_BASIC_AUTH",
"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: |-
setUrl('https://api.synerise.com/catalogs/bags/%7BcatalogId%7D/mappings');
$request->setMethod(HTTP_METH_POST);
$request->setHeaders([
'Authorization' => 'Basic REPLACE_BASIC_AUTH',
'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 response = Unirest.post("https://api.synerise.com/catalogs/bags/%7BcatalogId%7D/mappings")
.header("Authorization", "Basic REPLACE_BASIC_AUTH")
.header("content-type", "application/json")
.body("{\"action\":\"transaction.charge\",\"paramKey\":\"sku\"}")
.asString();
servers:
- url: https://api.synerise.com
description: Microsoft Azure EU
- url: https://api.azu.synerise.com
description: Microsoft Azure USA
- url: https://api.geb.synerise.com
description: Google Cloud Platform
tags:
- name: Catalogs
components:
securitySchemes:
JWT:
type: http
scheme: bearer
description: |
Synerise uses [JSON Web Token (JWT)](https://jwt.io/) as the authorization method.
The token is generated by the *auth/login* endpoints.
You need to include it in the `Authorization` header of your requests, with a `Bearer` prefix.
By default, the token is valid for **one week** (see [workspace settings](https://hub.synerise.com/docs/settings/tool/iam-for-apps/general/#jwt-lifetime)).
You can request a refreshed key for the session by using the *auth/refresh* endpoint **before** the current token expires.
You can verify your JWT signature by using the [public key](https://api.synerise.com/v4/public.pem).
See Developer Guides on JWT API authentication for:
- [profiles](https://hub.synerise.com/developers/api/api-authorization/client-login/);
- [workspaces](https://hub.synerise.com/developers/api/api-authorization/workspace-login/#api-authentication-with-jwt);
- [users](https://hub.synerise.com/developers/api/api-authorization/user-login/).
BasicAuth:
type: http
scheme: basic
description: |
Basic authentication with login (workspace GUID) and password (workspace API key) encoded with Base64 and sent in the `Authorization` header. **Must be enabled in the settings of the API key**.
This is less secure than JWTs. Limit the API key permissions to only those that you need. Consider API key rotation and other security measures.
You can still use JWTs from the same API key when basic authentication is enabled.
For details, see ["Workspace authentication"](https://hub.synerise.com/jwt-or-basic/#basic-api-authentication-with-api-keys).
```