How to define the path for selecting JSON objects

Coupler.io lets you connect to almost any API that returns JSON data.

In most cases, when you fetch a list of objects, a JSON array is returned.

A JSON array is an ordered sequence of values.

A JSON array can appear at different levels in the response. Depending on where it appears, you need to set the Path parameter accordingly. Below are the most common cases and the right settings to use in Coupler.io.

To check the JSON array structure returned by your API, use the API documentation and an API client such as Postman.

JSON array at the root level

This is the simplest setup. For example, the API response looks like this:

[
   {
      "id":"76013791",
      "customerName":"JOHN DOE",
      "total":1409.62
    }
]

Leave the Path parameter empty in Coupler.io:

You will get the following result in the destination:

JSON array inside a JSON object

Another common case is when the list of objects is placed inside a JSON object with one key:

{
   "orders":[
      {
         "id":"76013791",
         "customerName":"JOHN DOE",
         "total":1409.62
      }
   ]
}

If you leave the Path parameter empty in Coupler.io, the result headers will be named like this: orders.id, orders.customerName, orders.total.

To get clean header names, use the key that appears before :[ in the JSON response as the Path value. In this example, set Path to orders:

You will get the following result in the destination:

JSON array inside nested JSON objects

This is similar to the previous case, but the array is nested inside several objects:

{
   "results":{
      "orders":[
         {
            "id":"76013791",
            "customerName":"JOHN DOE",
            "total":1409.62
         }
      ]
   }
}

If you leave the Path parameter empty in Coupler.io, the result headers will look like this:

To get clean header names, use the full nested key path that appears before :[ in the JSON response. In this example, set Path to results.orders:

You will get the following result in the destination:

JSON array with a nested JSON array

Some APIs return the list you need inside another list. For example, a products list can sit inside an orders list:

{
   "results":{
      "orders":[
         {
            "id":"76013791",
            "customerName":"JOHN DOE",
            "total":1409.62,
            "products":[
               {
                  "id":"prod1",
                  "name":"T-Shirt",
                  "size":"M",
                  "quantity":"3",
                  "total":54.99
               }
            ]
         }
      ]
   }
}

If you leave the Path parameter empty in Coupler.io, you will get the following result, with all the data in a single row:

As you can see in the screenshot above, the number 0 appears after results.orders. It is the index of the first order in the orders array. The same applies to results.orders.0.products: the 0 there is the index of the product in the products array.

A JSON array is zero-indexed, so the first item has index 0. Read more.

To extract orders with their products, use results.orders as the Path value:

You will get the order data in the destination, plus one row per product in each order. In this example, the order data shown in yellow will be duplicated.

Note: In the image below, the second product, prod2, was added for clarity. It was not included in the original JSON above.

To extract only the products for a specific order, use results.orders.0.products as the Path value. In this example, it points to the first order because there is only one:

Note: The first element in an array has index 0, the second has index 1, and so on.

Only the product data will be saved to the destination:

If you run into issues while defining the Path value, contact our Support Team at [e-mail].