Parsing JSON Response Bodies Using Dot Notation

Feature Snapshot

Summary:
JSON is a hierarchically structured, human-readable format for representing data. Dot Notation is a shorthand technique for drilling into a json object to extract the contents of a particular parameter from a response body.

To learn more about JSON, see: https://www.tutorialspoint.com/json/index.htm.

Key Benefits:

• Drill into response-body JSON to extract specific parameters.
• Configure response parsing for accepted vs. rejected leads using response mappings.
• Extract a rejection reason (including when the reason lives inside a nested object or array).
• Override an incorrect or missing JSON Content-Type header when parsing doesn’t work.

Typical Use Cases:

• Identify an accepted lead when the response contains a simple JSON object like {"result":"success","error":""}.
• Extract a rejection reason from a simple field (for example, error).
• Parse nested JSON structures (for example, leads[0].lead.result).
• Select a specific element in a JSON array using an index (for example, errors[0]).
• Force JSON parsing when the recipient system doesn’t set the Content-Type header correctly.

How dot notation works?

Dot Notation begins with the outermost (root) level of the json object. You drill down into the object by specifying the names of ever-deeper parameters, delimiting between each with a dot, until you reach the one you need to extract.

If a parameter’s value is an array (surrounded by square brackets [ ]) rather than a simple value or another json object (curly brackets { }), use an integer enclosed in square brackets to identify which element of the array to select for that level of the traverse.

Step‑by‑Step Instructions

1. Start with the JSON you receive in the response body.
   Example accepted response body:

   {"result":"success","error":""}
   

2. Map the outcome fields using the response body.
   Configure mappings so the parser can find the outcome using:

   • Outcome Search Path → the parameter name to evaluate (for example, result)
   • Outcome Search Term → the value to look for (for example, success)

   

3. If leads can be rejected, map the rejection reason.
   Example rejected response body:

   {"result":"rejected", "error":"Quota filled for red cars"}
   

   Configure:

   • Reason Path → the parameter that contains the rejection reason (for example, error)

   

4. For nested JSON, build a dot-notation path to the value you need.
   Example accepted response body:

   {
    "leads": [
      {
      "lead": {
        "id": "12345678",
        "result": "success",
        "errors": []
      }
     }
    ]
   }
   

   Example rejected response body:

   {
    "leads": 
    [
      {
        "lead": {
          "id": "",
          "result": "rejected",
          "errors": [
            { "error": "Leads not accepted for NY" },
            { "error": "Must be older than 18 years" }
          ]
        }
      }
    ]
   }
   

5. Map nested paths (including array indexes) into the response mappings.
   For the examples above, the response mappings would be:

   • Outcome Search Path → leads[0].lead.result
   • Outcome Search Term → success
   • Reason Path → leads[0].lead.errors[0].error

   

Expected Result:
For a rejected lead, the event should show a failure outcome and the selected rejection reason. Even though only one error (usually index 0) is mapped as the Reason Path, LeadConduit also automatically captures all of the reasons as appended data.

Validation & Monitoring (optional)

• Test the Setup: Send a test accepted and a test rejected lead and confirm the outcome and reason are parsed correctly in the event.
• Where to Monitor?: Review the event results to confirm the outcome and reason, and to see any appended error data.

Best Practices

• When you need to validate a dot-notation expression, use the online tester: https://jsonpath.curiousconcept.com/.
• When the rejection reason is an array, map a single element (usually index 0) as the reason, and rely on appended data for the complete list of reasons.
• If parsing doesn’t work despite correct mappings, verify the response Content-Type header (and use a Response Content-Type Override if needed).

Troubleshooting

Frequently Asked Questions (FAQ)

What is dot notation?

It’s a shorthand technique for drilling into a json object by specifying ever-deeper parameter names separated by dots, until you reach the parameter you need to extract.

For a brief tutorial about dot notation, see: https://idratherbewriting.com/learnapidoc/docapis_diving_into_dot_notation.html.

How do I select a value inside a JSON array?

Use an integer in square brackets to pick the element at that level (for example, errors[0]).

What if the rejection reasons are in an array with more than one reason?

Map a single element (usually index 0) as the reason path. LeadConduit also automatically captures all of the reasons as appended data.

My parsing mappings look correct, but parsing still isn’t working. What should I check?

Confirm the response Content-Type header is correct. If it isn’t, set the desired Content-Type in the Response Content Type Override mapping.

Glossary

• dot_notation-success_outcome.png20 KB
• dot_notation-error_reason.png10 KB
• dot_notation-complex_mapping.png30 KB
• dot_notation-rejection_outcome.jpg40 KB
• dot_notation-content_type.png10 KB