Skip to main content

JSON Paths and Variables

How to use JSON paths and variables to insert data supplied in the Send API request or the User Profile into a notification.

The Notification Designer allows you to use external data in many places as you build your notification. This data, supplied by the data and profile objects of the Send API request or the Profiles API, can be accessed using a path.

Paths are used in the following:

Path​

A path is a JSONPath expression used to query the Courier Notification Context JavaScript object. This object contains notification related information, such as:

  • data- An object passed to the send method
  • profile - An object containing merged profile data passed to the send method and stored in Courier.
{
  “data”: { … },
  “profile”: { ... }
}

You can build JSONPath expressions to access different data from this object.

Learn More: JSONPath Sytax.

Referencing Profile Information​

If you want to access data from the profile object or data from the User Profile created with the Profiles API, use a full JSONPath expression such as $.profile.someProp. IE if you wanted to access the email, you could use the expression $.profile.email.

Referencing Tenant Information​

If you want to access properties from the associated tenant object created with the Tenants API, use a full JSONPath expression such as $.tenant.company_name.

Referencing Brand Information​

If you want to access data from the active brand, use a full JSONPath expression such as $.brand.

{
  id: string;
  colors: {
    primary: string;
    secondary: string;
    tertiary: string;
  };
  inapp: {
    borderRadius: string;
    disableMessageIcon: boolean;
    placement: "top" | "bottom" | "left" | "right";
    emptyState: {
      textColor: string;
      text: string;
    };
    icons: {
      bell: string;
      message: string;
    };
  };
  email: {
    header: {
      barColor: string;
      logo: {
        href: string;
        image: string;
      };
    };
  };
  social: {
    facebook?: string;
    instagram?: string;
    linkedin?: string;
    medium?: string;
    twitter?: string;
  };
}

Learn More: JSONPath Sytax.

Referencing Data Information​

Because the majority of the data you'll want to access is in the data object, Courier has simplified that path. Instead of providing a full JSONPath expression such as $.data.someProp, you can just use someProp. Courier will query data for any path not prefixed with $.

Substitution Variables​

Substitution Variables allow you to display the value of a path. You can create one by wrapping the path with curly braces. If you want to display the value of the name property passed in the data object, you can use {name}.

You can include variables in your content blocks. At send time, Courier will replace the variable with the value located in the path.

If we have the following text:

  • Ahoy {name}!

and the following data:

{
  “data”: {
    “name”: “Patrick”
  }
}

The result would be:

Ahoy Patrick!

If we need to access a value nested in the data object, we can do so using a JSONPath expression. If our data object looked like the following:

{
  “data”: {
    “name”: {
      “first”: “Patrick”,
      “last”: “Star”
    }
  }
}

We would need to modify our variable path to our text to get the same result:

Ahoy {name.first}!

Note

Because there is no way to create a fallback, if a value is not found, the variable path will be returned.

Was this helpful?