Create a mapping
curl --request POST \
--url https://api-dev.narrative.io/mappings/companies/{company_id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"attribute_id": 123,
"dataset_id": 456,
"mapping": {
"type": "object_mapping",
"property_mappings": [
{
"path": "product.brand",
"expression": "itemBrand"
},
{
"path": "product.category",
"expression": "itemCategory"
},
{
"path": "product.id.type",
"expression": "'SKU'"
},
{
"path": "product.id.value",
"expression": "itemID"
}
]
}
}
EOFimport requests
url = "https://api-dev.narrative.io/mappings/companies/{company_id}"
payload = {
"attribute_id": 123,
"dataset_id": 456,
"mapping": {
"type": "object_mapping",
"property_mappings": [
{
"path": "product.brand",
"expression": "itemBrand"
},
{
"path": "product.category",
"expression": "itemCategory"
},
{
"path": "product.id.type",
"expression": "'SKU'"
},
{
"path": "product.id.value",
"expression": "itemID"
}
]
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
attribute_id: 123,
dataset_id: 456,
mapping: {
type: 'object_mapping',
property_mappings: [
{path: 'product.brand', expression: 'itemBrand'},
{path: 'product.category', expression: 'itemCategory'},
{path: 'product.id.type', expression: '\'SKU\''},
{path: 'product.id.value', expression: 'itemID'}
]
}
})
};
fetch('https://api-dev.narrative.io/mappings/companies/{company_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-dev.narrative.io/mappings/companies/{company_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'attribute_id' => 123,
'dataset_id' => 456,
'mapping' => [
'type' => 'object_mapping',
'property_mappings' => [
[
'path' => 'product.brand',
'expression' => 'itemBrand'
],
[
'path' => 'product.category',
'expression' => 'itemCategory'
],
[
'path' => 'product.id.type',
'expression' => '\'SKU\''
],
[
'path' => 'product.id.value',
'expression' => 'itemID'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-dev.narrative.io/mappings/companies/{company_id}"
payload := strings.NewReader("{\n \"attribute_id\": 123,\n \"dataset_id\": 456,\n \"mapping\": {\n \"type\": \"object_mapping\",\n \"property_mappings\": [\n {\n \"path\": \"product.brand\",\n \"expression\": \"itemBrand\"\n },\n {\n \"path\": \"product.category\",\n \"expression\": \"itemCategory\"\n },\n {\n \"path\": \"product.id.type\",\n \"expression\": \"'SKU'\"\n },\n {\n \"path\": \"product.id.value\",\n \"expression\": \"itemID\"\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-dev.narrative.io/mappings/companies/{company_id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"attribute_id\": 123,\n \"dataset_id\": 456,\n \"mapping\": {\n \"type\": \"object_mapping\",\n \"property_mappings\": [\n {\n \"path\": \"product.brand\",\n \"expression\": \"itemBrand\"\n },\n {\n \"path\": \"product.category\",\n \"expression\": \"itemCategory\"\n },\n {\n \"path\": \"product.id.type\",\n \"expression\": \"'SKU'\"\n },\n {\n \"path\": \"product.id.value\",\n \"expression\": \"itemID\"\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-dev.narrative.io/mappings/companies/{company_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"attribute_id\": 123,\n \"dataset_id\": 456,\n \"mapping\": {\n \"type\": \"object_mapping\",\n \"property_mappings\": [\n {\n \"path\": \"product.brand\",\n \"expression\": \"itemBrand\"\n },\n {\n \"path\": \"product.category\",\n \"expression\": \"itemCategory\"\n },\n {\n \"path\": \"product.id.type\",\n \"expression\": \"'SKU'\"\n },\n {\n \"path\": \"product.id.value\",\n \"expression\": \"itemID\"\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0",
"attribute_id": 291,
"created_at": "2021-12-10T00:00:00Z",
"dataset_id": 3,
"mapping": {
"type": "value_mapping",
"expression": "lower(email)",
"dependencies": {
"properties": [
"email"
]
}
},
"status": "active",
"updated_at": "2021-12-10T00:00:00Z",
"created_by": 1,
"updated_by": 1,
"company_id": 100,
"scope": "global",
"source": "company",
"derived_from": null,
"tags": [],
"derived_mappings": [
{
"attribute_id": 76,
"created_at": "2021-12-10T00:00:00Z",
"dataset_id": 3,
"mapping": {
"type": "value_mapping",
"expression": "SHA2(lower(email), 256)",
"dependencies": {
"properties": [
"email"
]
}
},
"status": "active",
"updated_at": "2021-12-10T00:00:00Z",
"created_by": 1,
"updated_by": 1,
"company_id": 100,
"scope": "global",
"source": "derived",
"provenance": {
"source_mapping_id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0",
"source_attribute_id": 291,
"derivation_path": [
42
],
"lossy": true,
"imprecise": false
},
"tags": [],
"derived_from": null
}
]
}Mappings
Create a mapping
Create a mapping between an attribute and one of the company’s datasets. The created mapping is
owned by the company and has global scope.
The response also lists, under derived_mappings, the derived mappings the new mapping unlocks: the rows
GET /mappings?source=derived would return for it, in the same shape.
Supports mapping types: cached_mapping, object_mapping, and value_mapping.
POST
/
mappings
/
companies
/
{company_id}
Create a mapping
curl --request POST \
--url https://api-dev.narrative.io/mappings/companies/{company_id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"attribute_id": 123,
"dataset_id": 456,
"mapping": {
"type": "object_mapping",
"property_mappings": [
{
"path": "product.brand",
"expression": "itemBrand"
},
{
"path": "product.category",
"expression": "itemCategory"
},
{
"path": "product.id.type",
"expression": "'SKU'"
},
{
"path": "product.id.value",
"expression": "itemID"
}
]
}
}
EOFimport requests
url = "https://api-dev.narrative.io/mappings/companies/{company_id}"
payload = {
"attribute_id": 123,
"dataset_id": 456,
"mapping": {
"type": "object_mapping",
"property_mappings": [
{
"path": "product.brand",
"expression": "itemBrand"
},
{
"path": "product.category",
"expression": "itemCategory"
},
{
"path": "product.id.type",
"expression": "'SKU'"
},
{
"path": "product.id.value",
"expression": "itemID"
}
]
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
attribute_id: 123,
dataset_id: 456,
mapping: {
type: 'object_mapping',
property_mappings: [
{path: 'product.brand', expression: 'itemBrand'},
{path: 'product.category', expression: 'itemCategory'},
{path: 'product.id.type', expression: '\'SKU\''},
{path: 'product.id.value', expression: 'itemID'}
]
}
})
};
fetch('https://api-dev.narrative.io/mappings/companies/{company_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-dev.narrative.io/mappings/companies/{company_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'attribute_id' => 123,
'dataset_id' => 456,
'mapping' => [
'type' => 'object_mapping',
'property_mappings' => [
[
'path' => 'product.brand',
'expression' => 'itemBrand'
],
[
'path' => 'product.category',
'expression' => 'itemCategory'
],
[
'path' => 'product.id.type',
'expression' => '\'SKU\''
],
[
'path' => 'product.id.value',
'expression' => 'itemID'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-dev.narrative.io/mappings/companies/{company_id}"
payload := strings.NewReader("{\n \"attribute_id\": 123,\n \"dataset_id\": 456,\n \"mapping\": {\n \"type\": \"object_mapping\",\n \"property_mappings\": [\n {\n \"path\": \"product.brand\",\n \"expression\": \"itemBrand\"\n },\n {\n \"path\": \"product.category\",\n \"expression\": \"itemCategory\"\n },\n {\n \"path\": \"product.id.type\",\n \"expression\": \"'SKU'\"\n },\n {\n \"path\": \"product.id.value\",\n \"expression\": \"itemID\"\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-dev.narrative.io/mappings/companies/{company_id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"attribute_id\": 123,\n \"dataset_id\": 456,\n \"mapping\": {\n \"type\": \"object_mapping\",\n \"property_mappings\": [\n {\n \"path\": \"product.brand\",\n \"expression\": \"itemBrand\"\n },\n {\n \"path\": \"product.category\",\n \"expression\": \"itemCategory\"\n },\n {\n \"path\": \"product.id.type\",\n \"expression\": \"'SKU'\"\n },\n {\n \"path\": \"product.id.value\",\n \"expression\": \"itemID\"\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-dev.narrative.io/mappings/companies/{company_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"attribute_id\": 123,\n \"dataset_id\": 456,\n \"mapping\": {\n \"type\": \"object_mapping\",\n \"property_mappings\": [\n {\n \"path\": \"product.brand\",\n \"expression\": \"itemBrand\"\n },\n {\n \"path\": \"product.category\",\n \"expression\": \"itemCategory\"\n },\n {\n \"path\": \"product.id.type\",\n \"expression\": \"'SKU'\"\n },\n {\n \"path\": \"product.id.value\",\n \"expression\": \"itemID\"\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0",
"attribute_id": 291,
"created_at": "2021-12-10T00:00:00Z",
"dataset_id": 3,
"mapping": {
"type": "value_mapping",
"expression": "lower(email)",
"dependencies": {
"properties": [
"email"
]
}
},
"status": "active",
"updated_at": "2021-12-10T00:00:00Z",
"created_by": 1,
"updated_by": 1,
"company_id": 100,
"scope": "global",
"source": "company",
"derived_from": null,
"tags": [],
"derived_mappings": [
{
"attribute_id": 76,
"created_at": "2021-12-10T00:00:00Z",
"dataset_id": 3,
"mapping": {
"type": "value_mapping",
"expression": "SHA2(lower(email), 256)",
"dependencies": {
"properties": [
"email"
]
}
},
"status": "active",
"updated_at": "2021-12-10T00:00:00Z",
"created_by": 1,
"updated_by": 1,
"company_id": 100,
"scope": "global",
"source": "derived",
"provenance": {
"source_mapping_id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0",
"source_attribute_id": 291,
"derivation_path": [
42
],
"lossy": true,
"imprecise": false
},
"tags": [],
"derived_from": null
}
]
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
The id of an existing company
Query Parameters
Skip validation of the mapping expressions against the query engine. Structural validation of the request still runs. The flag is enabled by being present; any value is ignored.
Body
application/json
The target attribute's ID.
The source dataset's ID.
Mapping definition for create/update requests. Dependencies are computed server-side and not provided by the client.
- Option 1
- Option 2
- Option 3
Show child attributes
Show child attributes
Status to create the mapping in. Defaults to active when omitted. Narrower than
MappingStatus — a mapping cannot be created already archived.
Available options:
active, pending, null Free-form labels on the mapping. Null and an empty array both mean no tags; nio:-prefixed tags
are reserved for Narrative.
Example:
["nio:rosetta"]
Optional source for the mapping. Null or omitted defaults to company.
Only company and rosetta_stone are allowed for user-created mappings.
Available options:
company, rosetta_stone, null Response
200 - application/json
Ok
The mapping that was created, plus the derived mappings it unlocks.
The target attribute's ID.
ISO-8601 timestamp indicating when the mapping was created.
Example:
"2021-08-26T21:06:07.710357Z"
The source dataset's ID.
- Option 1
- Option 2
- Option 3
Show child attributes
Show child attributes
The status of the mapping.
active- Active mappings can be usedarchived- Archived/Deleted mappings - mapping no longer in usepending- Pending mappings need to be accepted before they can be usedrejected- Proposed mappings the owner turned down. Can still be accepted later
Available options:
active, archived, pending, rejected ISO-8601 timestamp indicating when the mapping was last updated.
Example:
"2021-08-26T21:06:07.710357Z"
Unique id from a user who created it.
Example:
20
Unique id from a user who updated it.
Example:
20
The scope of the mapping.
global- Mappings available to allprivate- Company private mappings
Available options:
global, private The source of the mapping.
company- Company private mappingadmin- Admin created/promoted mappingsystem- System (Automated/ML) mappingslineage- Lineage-derived mappings (editable without admin)rosetta_stone- Rosetta Stone mappings (editable without admin)derived- Computed on the request from a stored mapping and a derivation rule. Not stored, so it has noid; listed only when asked for by source
Available options:
company, admin, system, lineage, rosetta_stone, derived The derived mappings the new mapping unlocks: the rows GET /mappings?source=derived would return for
it, in the same shape (source: derived, no id, a provenance). Empty when the mapping's attribute is
not the source of any derivation rule, when the mapping was created pending, or when every target
attribute already has an explicit mapping on the dataset.
Show child attributes
Show child attributes
Absent on a derived mapping (source: derived), which is computed per request and cannot be fetched or
changed by id.
Example:
"ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0"
The company that owns the mapping. Null for platform-wide mappings.
Example:
345
How a derived mapping was produced. Present only when source is derived.
Show child attributes
Show child attributes
Example:
{ "source_mapping_id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0", "source_attribute_id": 291, "derivation_path": [42], "lossy": true, "imprecise": false }
Free-form labels on the mapping. Null and an empty array both mean no tags; nio:-prefixed tags
are reserved for Narrative.
Example:
["nio:rosetta"]
The stored mapping this one was copied from when it was authored (lineage). Unrelated to derivation rules;
see provenance for those. Null when the mapping was authored directly.
Example:
"ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0"
Was this page helpful?