JSON in Salesforce Apex: The Complete Guide

Salesforce applications rarely work in isolation. They frequently exchange data with external systems, including payment gateways, ERP platforms, Microsoft Dynamics 365, SAP, AI services, and custom REST APIs. In most of these modern enterprise integrations, data is transmitted and received in JSON (JavaScript Object Notation) format.

Whether you are building an Apex HTTP callout, consuming a third-party REST API, or integrating Salesforce with another cloud application, mastering JSON in Salesforce Apex is critical. You must convert Apex objects into JSON before sending a request and parse JSON responses back into runtime memory. Understanding these processing techniques is an essential architectural skill for every Salesforce developer.

In this comprehensive guide, we will explore the most commonly used techniques for handling JSON in Salesforce Apex, including serialization, deserialization, strongly typed wrapper classes, nested arrays, and dynamic parsing using JSON.deserializeUntyped().

What is JSON?

JSON (JavaScript Object Notation) is a lightweight, text-based format used to store and exchange data between applications. Although it originated in JavaScript syntax, JSON is language-independent and natively supported by almost every modern programming language, including Apex.

JSON organizes data using clean key-value pairs, making it both human-readable and highly efficient for systems to process. It has become the definitive standard format for data exchange in REST APIs and cloud web services.

JSON

{  
  "customerId": 101,  
  "name": "John Smith",  
  "email": "john@testdemo.com",  
  "isActive": true 
}

JSON Key	Value Component	Data Type Reference
customerId	101	Number
name	"John Smith"	String
email	"john@testdemo.com"	String
isActive	true	Boolean

Understanding the fundamentals of JSON structure lays the essential groundwork for writing secure, performant integrations inside your Salesforce org.

Why JSON is Important in Salesforce

Whenever an Apex application triggers an outbound HTTP callout to an external REST endpoint, the request data is typically sent as a JSON payload. Similarly, the external server returns its execution response in JSON format. Apex developers must then parse that payload to extract the required variables and update records within Salesforce.

JSON is also the native language of Salesforce’s standard platform APIs. External web or mobile applications that create, update, query, or delete Salesforce records through the native REST API send and receive data as JSON.

Common Salesforce Integration Scenarios:

• Sending transactional customer or order data to an external fulfillment engine.
• Receiving financial master records from ERP systems like SAP or Microsoft Dynamics 365.
• Authorizing real-time subscription charges through payment gateways like Stripe or PayPal.
• Communicating with generative AI services such as OpenAI or autonomous Salesforce Agentforce engines.
• Exchanging data through custom Apex REST web services hosted directly in your org.

Understanding JSON Schema Structures

Before writing parsing logic in Apex, you must understand how a JSON payload organizes its internal schema layer. It relies on three primary building blocks: keys, nested objects, and arrays.

1. Primitive Key-Value Pairs

A standard JSON object is enclosed in curly braces {} and contains one or more key-value attributes. Each key is enclosed in double quotes, followed by a colon (:). The values must conform to valid JSON primitive data types:

Data Type	Example Payload	Apex Mapping Target
String	"ABC Corporation"	String
Number	250 or 18.95	Integer, Long, or Decimal
Boolean	true	Boolean
Null	null	null
Object	{"city": "Columbus"}	Class or Map<String, Object>
Array	["Admin", "Developer"]	List<String>

2. Nested JSON Objects

A JSON property can contain another JSON object as its value. This is known as a nested structure, used to group related properties logically.

JSON
{
"customerId": 101,
"name": "John Smith",
"address": {
"street": "123 Main Street",
"city": "Columbus",
"state": "Ohio",
"zipCode": "43065"
}
}

3. JSON Arrays

A JSON array stores an ordered collection of values or objects and is enclosed in square brackets []. Arrays are returned when an external API passes a list of multiple records.

JSON

{  
  "customerId": 101,  
  "orders": [  
    { "orderId": 1001, "amount": 250 },  
    { "orderId": 1002, "amount": 175 }  
  ]  
}

Serialization: From Apex to JSON

Serialization is the process of converting an in-memory Apex object into a raw JSON string payload. Apex provides a native, global engine through a JSON.serialize() method to execute this action.

JSON.serialize() automatically maps standard sObjects, primitive data types, collections (List/Map), and custom class properties into a valid, standard-compliant JSON format.

Code Example: Serializing a Salesforce sObject

Java

Account acc = new Account(); 
acc.Name = 'ABC Corporation'; 
acc.Phone = '600-000-0000'; 
acc.Website = 'https://www.abccorp.com'; 

// Serialize the runtime record into a raw JSON payload string
String jsonPayload = JSON.serialize(acc); 
System.debug('Serialized String: ' + jsonPayload);

Serialized JSON Output:

JSON

{  
  "Name": "ABC Corporation",  
  "Phone": "600-000-0000",  
  "Website": "https://www.abccorp.com"  
}

Architecture Best Practice: Always serialize native Apex objects or custom structures instead of manually stitching JSON payload strings together using string concatenation. Hand-crafting JSON strings makes your code fragile, unreadable, and prone to escape-character formatting errors that cause external API breaks.

Deserialization: From JSON to Apex

Deserialization transforms an incoming JSON string payload back into a strongly typed object inside your Apex execution thread. This is the cornerstone pattern when processing inbound HTTP response bodies.

Apex handles standard deserialization using JSON.deserialize(). This method directly maps JSON attributes onto matching variables defined within a concrete target class configuration.

Code Example: Parsing JSON via an Apex Class Target

Suppose an external endpoint returns the following flat customer schema text string:

JSON

{  
  "customerId": 101,  
  "name": "John Smith",  
  "email": "john@example.com"  
}

First, construct a clean, targeted inner or standalone Apex class structure (commonly known as a Wrapper Class) that matches your expected keys:

Java

public class Customer {  
    public Integer customerId;  
    public String name;  
    public String email;  
}

Next, use JSON.deserialize() to map the payload string directly into the class context:

Java

String jsonString = '{"customerId":101,"name":"John Smith","email":"john@example.com"}'; 

// Deserialize and cast the generic untyped result back to the explicit target class
Customer cust = (Customer)JSON.deserialize(jsonString, Customer.class); 

System.debug('Customer ID: ' + cust.customerId); 
System.debug('Name: ' + cust.name); 
System.debug('Email: ' + cust.email);

Handling Complex Frameworks with Wrapper Classes

In production enterprise integrations, API payloads are rarely completely flat. They often feature complex multi-layered objects or internal array nests. To safely deserialize these models, you can nest your Apex wrapper structures to mirror the structural properties of the target payload.

Real-World Deep Nest Example:

JSON

{  
  "customerId": 101,  
  "name": "John Smith",  
  "email": "john@testdemo.com",  
  "address": {  
    "street": "123 Main Street",  
    "city": "Columbus",  
    "state": "Ohio"  
  }  
}

The Architectural Wrapper Solution:

Create a parent class that references an internal, strongly typed child wrapper class property:

Java

public class CustomerWrapper {  
    public Integer customerId;  
    public String name;  
    public String email;  
    public AddressWrapper address; // References the nested object mapping layer
    
    public class AddressWrapper {  
        public String street;  
        public String city;  
        public String state;  
    }  
}

Parsing the Complex JSON Data Model:

Java

String jsonResponse = '{"customerId":101,"name":"John Smith","email":"john@testdemo.com","address":{"street":"123 Main Street","city":"Columbus","state":"Ohio"}}';

CustomerWrapper customer = (CustomerWrapper)JSON.deserialize(jsonResponse, CustomerWrapper.class);  
  
System.debug('Parent Name: ' + customer.name);  
System.debug('Nested Address City: ' + customer.address.city);  
System.debug('Nested Address State: ' + customer.address.state);

Dynamic Parsing via JSON.deserializeUntyped()

There are scenarios where the incoming JSON structure is unpredictable, dynamic, or shifts formats based on request parameters. Creating rigid, predefined class files for thousands of dynamic combinations is impractical.

To solve this, Apex provides JSON.deserializeUntyped(). Instead of mapping data to an explicit class blueprint, it parses the payload directly into a generic collection hierarchy:

• Curly brace JSON objects {} convert into a flexible Map<String, Object>.
• Square bracket arrays [] convert into a flexible List<Object>.

Code Example: Parsing Dynamically Without a Class File

Java

String jsonString = '{"customerId":101,"name":"John Smith","email":"john@testdemo.com","isActive":true}';  
  
// Deserialize raw payload into a generic, key-addressable string map block
Map<String, Object> payloadMap = (Map<String, Object>)JSON.deserializeUntyped(jsonString);  
  
// Extrapolate values dynamically by key strings and explicit type-casting loops
Integer cId = (Integer)payloadMap.get('customerId');
String cName = (String)payloadMap.get('name');
Boolean checkActive = (Boolean)payloadMap.get('isActive');

System.debug('Dynamic Extracted Name: ' + cName);

Advanced Troubleshooting: Real-World Edge Cases

Production payloads don’t always cooperate with native Apex properties. Here is how to handle advanced integration roadblocks.

Edge Case 1: The Apex Reserved Keyword Trap

The Problem: An external API payload returns a key named after an Apex reserved word (e.g., "class", "object", or "currency"). You cannot declare public String class; in a class definition without throwing a compilation error.

The Solution: Sanitize the raw payload string using string substitution primitives before passing the stream into the deserializer:

Java

String rawJson = '{"customerId":101, "class":"Premium Tier"}';

// Substitute the reserved token string identifier safely inside memory
String sanitizedJson = rawJson.replace('"class":', '"customerClass":');

// Now your wrapper can securely extract 'customerClass' without compiler breaks

Edge Case 2: Handling Gaps & Missing Payload Keys

The Problem: Certain external architectures omit optional keys entirely when their database values are blank. Attempting to directly cast or interact with non-existent keys throws a runtime NullPointerException.

The Solution: When parsing untyped data maps, always deploy a structural validation check using .containsKey() combined with null evaluations before execution:

Java

Map<String, Object> dataMap = (Map<String, Object>)JSON.deserializeUntyped(jsonStream);

if(dataMap.containsKey('optionalTaxRate') && dataMap.get('optionalTaxRate') != null) {
    Decimal tax = (Decimal)dataMap.get('optionalTaxRate');
} else {
    Decimal tax = 0.00; // Safe graceful fallback definition
}

Production Testing & Mock Execution Framework

To ensure your parsing architectures achieve deployment-ready code coverage matching production quality gates, you must build robust testing frameworks. Below is the full implementation layout for testing dynamic JSON handlers using mock abstractions.

1. The Callout Mock Class Implementation

Java

@isTest
global class CustomerIntegrationMock implements HttpCalloutMock {
    global HTTPResponse respond(HTTPRequest req) {
        HttpResponse res = new HttpResponse();
        res.setHeader('Content-Type', 'application/json');
        res.setBody('{"customerId":101,"name":"John Smith","email":"john@testdemo.com"}');
        res.setStatusCode(200);
        return res;
    }
}

2. The Verification Unit Test Method

Java

@isTest
private class CustomerIntegrationTest {
    @isTest static void testInboundCustomerParsing() {
        // Associate the framework processing thread to use our mock dataset layer
        Test.setMock(HttpCalloutMock.class, new CustomerIntegrationMock());
        
        Test.startTest();
        // Simulate operation triggering your execution parsing logic layers
        String samplePayload = '{"customerId":101,"name":"John Smith","email":"john@testdemo.com"}';
        Customer processedCustomer = (Customer)JSON.deserialize(samplePayload, Customer.class);
        Test.stopTest();
        
        // Assertions ensuring structural conversion variables pass cleanly
        System.assertEquals('John Smith', processedCustomer.name, 'Name mapping mismatch verified');
        System.assertEquals(101, processedCustomer.customerId, 'ID indexing check failed');
    }
}

Conclusion​

Working with JSON is an essential core technical competency for Salesforce developers because modern web architectures rely on it completely. Mastering when to apply rigid serialization via JSON.serialize() type-safe parsing via wrapped classes, or schema-agnostic handling via JSON.deserializeUntyped() allows you to construct highly resilient integrations.

By applying these core structural design patterns, you ensure your integration layers stay readable, maintainable, and decoupled from external API schema drift.

Join the Conversation Assembly

Did you run into a strange, non-standard JSON parsing exception or an unexpected character-escaping error while building an integration? Don’t waste hours troubleshooting sandbox execution loops in isolation.

Share your custom payload workarounds with our engineering group over on our SF Monk Contributors Page, or submit a tactical resolution guide via our active Write For Us program to help your fellow developers master platform architecture!