Response JMESPath

Note API Connector includes a built-in JMESPath interactive editor that allows you to transform JSON responses from an API.

JMESPath is a powerful query language for JSON that enables you to:

✅ Filter specific fields from an API response.
✅ Rename fields for better readability.
✅ Extract only relevant data based on conditions.
✅ Query deeply nested JSON structures.
✅ Select a specific top-level array when multiple arrays exist.

Using JMESPath in Note API Connector

To access the JMESPath editor:

1️⃣ Open the Response Field Mapping view.
2️⃣ Click Advanced Settings.
3️⃣ In the API Response section, view the raw API response.
4️⃣ Enter your JMESPath query in the editor to filter and transform the response.

✅ The JMESPath Result panel on the right shows the transformed data in real-time.

tip

You can explore the official JMESPath tutorial to learn about writing JMESPath queries.

Keep Only Specific Fields

You can filter an API response to retain only relevant fields.

Example: Extracting Employee Names and IDs

Suppose an API returns the following JSON with employee details:

{
  "employees": [
    {
      "id": 101,
      "name": "Alice Johnson",
      "department": "Engineering",
      "salary": 75000,
      "location": "New York"
    },
    {
      "id": 102,
      "name": "Bob Smith",
      "department": "Marketing",
      "salary": 68000,
      "location": "San Francisco"
    },
    {
      "id": 103,
      "name": "Charlie Adams",
      "department": "Finance",
      "salary": 72000,
      "location": "Chicago"
    }
  ]
}

If we only want to keep the id and name fields, we can use this JMESPath expression:

employees[].{id: id, name: name}

Explanation:

• employees[] → Selects all objects inside the employees array.
• {id: id, name: name} → Extracts only the id and name fields.

✅ Transformed JSON Output:

[
  {
    "id": 101,
    "name": "Alice Johnson"
  },
  {
    "id": 102,
    "name": "Bob Smith"
  },
  {
    "id": 103,
    "name": "Charlie Adams"
  }
]

This is useful when an API returns extra data you don’t need, and you want to import only relevant fields into Notion.

Transform Field Names

JMESPath allows renaming fields to make data easier to work with.

Example: Renaming full_name to name

{
  "users": [
    {
      "id": 1,
      "full_name": "Jane Doe",
      "email": "[email protected]"
    },
    {
      "id": 2,
      "full_name": "John Smith",
      "email": "[email protected]"
    }
  ]
}

JMESPath Expression:

users[].{id: id, name: full_name}

✅ Transformed JSON Output:

[
  {
    "id": 1,
    "name": "Jane Doe"
  },
  {
    "id": 2,
    "name": "John Smith"
  }
]

Filter Data Based on Conditions

You can filter data dynamically using conditions like ==, >, <, and &&.

Example: Filtering Orders Above $50

{
  "orders": [
    {
      "order_id": 1001,
      "customer": "Alice",
      "total": 75.5
    },
    {
      "order_id": 1002,
      "customer": "Bob",
      "total": 42.0
    },
    {
      "order_id": 1003,
      "customer": "Charlie",
      "total": 120.0
    }
  ]
}

JMESPath Expression:

orders[?total > `50`]

✅ Transformed JSON Output:

[
  {
    "order_id": 1001,
    "customer": "Alice",
    "total": 75.5
  },
  {
    "order_id": 1003,
    "customer": "Charlie",
    "total": 120.0
  }
]

Extract Nested Data

Many APIs return nested JSON objects, and JMESPath allows extracting values efficiently.

Example: Extracting Usernames from Nested Profiles

{
  "users": [
    {
      "profile": {
        "username": "janedoe",
        "age": 28
      }
    },
    {
      "profile": {
        "username": "johnsmith",
        "age": 35
      }
    }
  ]
}

JMESPath Expression:

users[].profile.username

✅ Transformed JSON Output:

[
  "janedoe",
  "johnsmith"
]

Select a Specific Top-Level Array

If an API returns multiple arrays, you can choose which array to process.

Example: Selecting Products Instead of Customers

{
  "customers": [
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" }
  ],
  "products": [
    { "id": "A1", "name": "Laptop" },
    { "id": "B2", "name": "Phone" }
  ]
}

JMESPath Expression:

products[]

✅ Transformed JSON Output:

[
  {
    "id": "A1",
    "name": "Laptop"
  },
  {
    "id": "B2",
    "name": "Phone"
  }
]

This is useful when an API returns multiple arrays, and you only need data from one of them.

Summary

JMESPath allows powerful JSON transformations, helping you filter, rename, and extract data before sending it to Notion.

📌 Key Takeaways:

✅ Use [].{} syntax to extract only needed fields.
✅ Rename fields using new_name: existing_field syntax.
✅ Filter data using [?condition] expressions.
✅ Navigate nested structures with object.field syntax.
✅ Select a specific top-level array using array_name[].

For more advanced queries, check the official JMESPath documentation.