Using JSONPath

Introduction

JSONPath ↗ is a query language for JSON, similar to how XPath works for XML. In Formcrafts, JSONPath is used in different places, such as in webhooks, to extract specific values from JSON responses. You can test your JSON paths using this tool ↗.

Basic syntax

JSONPath expressions always start with $ which represents the root of the JSON document. You then use dot notation or bracket notation to navigate through the structure.

Expression Description
$ Root object
. Child operator
[] Array index or child operator

Examples

Given this JSON response:

{
  "user": {
    "id": "usr_12345",
    "name": "John Doe",
    "email": "[email protected]"
  },
  "order": {
    "id": "ord_67890",
    "items": [
      { "name": "Product A", "price": 29.99 },
      { "name": "Product B", "price": 49.99 }
    ],
    "total": 79.98
  },
  "status": "completed"
}

Accessing simple properties

JSONPath Result
$.status "completed"
$.user.id "usr_12345"
$.user.name "John Doe"
$.order.total 79.98

Accessing nested objects

JSONPath Result
$.user.email "[email protected]"
$.order.id "ord_67890"

Accessing array elements

Use zero-based index numbers in square brackets:

JSONPath Result
$.order.items[0] { "name": "Product A", "price": 29.99 }
$.order.items[0].name "Product A"
$.order.items[1].price 49.99

Accessing the last array element

Use negative indices to count from the end:

JSONPath Result
$.order.items[-1].name "Product B"

Common patterns

API responses with data wrapper

Many APIs wrap their response in a data object:

{
  "data": {
    "id": "12345",
    "attributes": {
      "name": "Example"
    }
  }
}
JSONPath Result
$.data.id "12345"
$.data.attributes.name "Example"

Extracting IDs from created resources

When creating a resource via webhook, you often need the returned ID:

{
  "id": "rec_abc123",
  "created_at": "2024-01-15T10:30:00Z"
}
JSONPath Result
$.id "rec_abc123"

Nested arrays

For deeply nested structures:

{
  "results": {
    "records": [
      { "id": "1", "value": "first" },
      { "id": "2", "value": "second" }
    ]
  }
}
JSONPath Result
$.results.records[0].id "1"
$.results.records[1].value "second"

Using multiple paths

In Formcrafts webhook configuration, you can extract multiple values by separating JSONPath expressions with commas:

$.data.id, $.data.status, $.meta.timestamp

Each extracted value becomes available for use in subsequent workflow actions.

Notes

  1. JSONPath expressions are case-sensitive. $.User.Id is different from $.user.id.

  2. If a path doesn’t match anything in the response, no value is extracted (no error is thrown).

  3. JSONPath only works with JSON responses. If your webhook returns a different content type, values cannot be extracted.