Data connectors now support mapping from both JSON and XML API responses. If your API returns XML, Intercom will convert it to JSON automatically before mapping objects and arrays. All mapping rules and limitations described below apply to the converted JSON structure.

Objects and arrays you can map

Note: In order to map date data to a Datetime attribute on a Custom Object, we only support mapping strings with an ISO 8601 format, e.g. 2008-01-10T11:00:00-05:00

Simple JSON object

You can map root API objects to People, Conversation and Custom objects. All API attributes are accessible.

{
	"type": "admin",
	"id": "493881",
	"name": "Hoban Washburne",
	"email": "wash@serenity.io",
	"away_mode_enabled": false,
	"away_mode_reassign": false
}

Nested JSON objects

You can map 3 API objects (root, order, client_details) to People, Conversation and Custom objects. All API attributes are accessible.

{
	"order": {
		"id": 450789469,
		"admin_graphql_api_id": "gid://shopify/Order/450789469",
		"app_id": null,
		"browser_ip": "0.0.0.0",
		"buyer_accepts_marketing": false,
		"cancel_reason": null,
		"cancelled_at": null,
		"cart_token": "68778783ad298f1c80c3bafcddeea02f",
		"checkout_id": 901414060,
		"checkout_token": "bd5a8aa1ecd019dd3520ff791ee3a24c",
		"client_details": {
			"accept_language": null,
			"browser_height": null,
			"browser_ip": "0.0.0.0",
			"browser_width": null,
			"session_hash": null,
			"user_agent": null
		}
	}
}

Top level arrays

Root object is array

You can map the root array to a Custom Object type. All API attributes of an element are accessible (the first element is taken as representative).

[
	{
		"type": "admin",
		"id": "493881",
		"name": "Hoban Washburne",
		"email": "wash@serenity.io",
		"away_mode_enabled": false,
		"away_mode_reassign": false
	},
	{
		"type": "admin",
		"email": "mal@serenity.io",
		"id": "646303",
		"name": "Malcolm Reynolds ",
		"away_mode_enabled": true,
		"away_mode_reassign": false
	}
]

Nested arrays

You can map access arrays nested inside of objects (not other arrays). You can map these arrays to Custom Objects.

{
	"order": {
		"id": 450789469,
		"discount_codes": [
			{
				"code": "TENOFF",
				"amount": "10.00",
				"type": "fixed_amount"
			}
		],
		"note_attributes": [
			{
				"name": "custom engraving",
				"value": "Happy Birthday"
			},
			{
				"name": "colour",
				"value": "green"
			}
		]
	}
}

Arrays you can’t map

Arrays nested inside of other arrays

You can’t access arrays that are nested inside of elements of other arrays. This is because we don’t know which element of the top level array to pick. So in the example below, you can map the order array to a Custom object. But not discount_codes arrays, as they are nested inside the orders array.

{
	"orders": [
		{
			"id": 1,
			"discount_codes": [
				{
					"code": "TENOFF",
					"amount": "10.00",
					"type": "fixed_amount"
				}
			],
			"note_attributes": [
				{
					"name": "custom engraving",
					"value": "Happy Birthday"
				},
				{
					"name": "colour",
					"value": "green"
				}
			]
		},
		{
			"id": 2,
			"discount_codes": [
				{
					"code": "TENOFF",
					"amount": "10.00",
					"type": "fixed_amount"
				}
			],
			"note_attributes": [
				{
					"name": "custom engraving",
					"value": "Happy Birthday"
				},
				{
					"name": "colour",
					"value": "green"
				}
			]
		}
	]
}

Sending nested objects in requests

Data connectors currently only support sending flat (key/value) parameters in request bodies. Nested object and array parameters are not supported.

This means that if a third-party API requires a nested object as part of the request — for example, Shopify's order cancellation and refund endpoints require a buyer_identity object — the action cannot be completed successfully via a Data connector.

Support for nested object and array parameters in request bodies is on our roadmap. We'll update this article when it becomes available.

💡Tip

Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts

How to set up Data connectors for Workflows and Inbox

JSON objects and arrays supported for Data connectors response mapping