Knowledge Base

API Reference Documentation for Testing & Creating a Mapping

Below is a guide on how to test and create mappings using Narrative’s Mapping API. Mappings are written in NQL (Narrative Query Language). Note that some identifiers such as "value" and "type" are reserved keywords and must be wrapped in quotes in your NQL expressions.

For more information on Narrative APIs, visit the official documentation at api.narrative.io.

1. Testing a Mapping

This step allows you to verify how your NQL expressions will transform specific sample records before committing the mapping.

Endpoint

POST https://app.narrative.io/mappings/test

Request Body

{
    "attribute_id": 1,
    "dataset_id": 11035,
    "mapping": {
        "type": "object_mapping",
        "property_mappings": [
            {
                "path": "type",
                "expression": "'sha256_email'"
            },
            {
                "path": "value",
                "expression": "lower(trim(email))"
            }
        ]
    }
}

Field	Type	Required	Description
`attribute_id`	number	Yes	Numeric identifier for the attribute you’re mapping.
`dataset_id`	number	Yes	Numeric identifier for the dataset in Narrative.
`mapping`	object	Yes	The core definition of the mapping, written in NQL.
`type`	string	Yes	For object-type mappings, use `"object_mapping"`.
`property_mappings`	array	Yes	A list of mappings from source fields (e.g., `email`) to output.
`path`	string	Yes	The target output field (e.g., `"type"`, `"value"`) which are reserved words and must be in quotes.
`expression`	string	Yes	The NQL expression used to transform data (e.g., `"lower(trim(email))"`).

Note: In the above mapping, "type" is set to a constant 'sha256_email', and "value" is transformed with lower(trim(email)).

Example Response

Status Code: 200 OK

{
    "records": [
        {
            "input": {
                "email": "someone@example.com"
            },
            "output": {
                "unique_id": {
                    "type": "sha256_email",
                    "value": "someone@example.com"
                }
            }
        },
        {
            "input": {
                "email": "anotherperson@example.net"
            },
            "output": {
                "unique_id": {
                    "type": "sha256_email",
                    "value": "anotherperson@example.net"
                }
            }
        }
    ]
}

input: Shows the original record values (e.g., "someone@example.com").
output: Demonstrates how the mapping transforms each record (i.e., setting "type" to "sha256_email" and "value" to the lowercased version of the email).

2. Creating a Mapping

Once your mapping is tested and verified, you can create (or update) a mapping for your company so that Narrative will process your dataset using these rules.

Endpoint

POST https://app.narrative.io/mappings/companies/{{attribute_id}}

Replace {{attribute_id}} with the numeric attribute_id you’re configuring.

Request Body

{
    "attribute_id": 1,
    "dataset_id": 11035,
    "mapping": {
        "type": "object_mapping",
        "property_mappings": [
            {
                "path": "type",
                "expression": "'sha256_email'"
            },
            {
                "path": "value",
                "expression": "lower(trim(email))"
            }
        ]
    }
}

This request is nearly identical to the test request, except it targets the company-specific endpoint and permanently saves the mapping.

Example Response

Status Code: 200 OK

{
    "id": "dd7941b8-89c3-422c-aae2-e6ca15e894b8",
    "attribute_id": 1,
    "company_id": 1,
    "created_at": "2025-02-21T23:39:11.603803Z",
    "created_by": 321,
    "dataset_id": 11035,
    "derived_from": null,
    "mapping": {
        "type": "object_mapping",
        "property_mappings": [
            {
                "path": "type",
                "expression": "'sha256_email'"
            },
            {
                "path": "value",
                "expression": "lower(trim(email))"
            }
        ]
    },
    "scope": "private",
    "source": "company",
    "status": "active",
    "tags": [],
    "updated_at": "2025-02-21T23:39:11.603803Z",
    "updated_by": 321
}

Field	Description
`id`	The unique identifier for the newly created mapping.
`company_id`	The numeric identifier for your company in Narrative.
`scope`	Indicates whether this mapping is `private` (only accessible to your company) or shared.
`status`	`active` indicates the mapping is ready and will be applied to the dataset’s records.
`mapping`	Returns the full mapping definition, confirming your transformation rules.

Additional Tips

Reserved Terms: Wrap "type" and "value" in quotes if you use them as output fields in your mapping expressions.
NQL Functions: Examples include lower(), trim(), concat(), etc. For more details, see api.narrative.io.
Testing First: Always use the /mappings/test endpoint to validate transformations before creating or updating a production mapping.
Case Sensitivity: Functions like lower() ensure consistent formatting, especially helpful for emails.