Composite Subrequest Result

The composite subrequest result describes the result for a subrequest.

Properties

Name	Type	Description
`body`	The type depends on the response type of the subrequest.	The response body of this subrequest. See the documentation for the subrequest resource for more information. If the subrequest returns an error, the body includes the error code and message. For more details on error responses, see Status Codes and Error Responses.
`httpHeaders`	Map<String, String>	Response headers and their values for this subrequest. The Composite resource doesn’t support the Content-Length header, so subrequest responses don’t include this header and neither does the top-level response.
`httpStatusCode`	Integer	An HTTP status code for this subrequest. If `allOrNone` is set to true in the composite request and a subrequest returns an error, all other subrequests return the 400 HTTP status code.
`referenceId`	String	The reference ID specified in the subrequest. This property lets you easily associate subrequests with their results.

Example

1{
2   "body": {
3      "id": "001R00000064wdtIAA",
4      "success": true,
5      "errors": []
6   },
7   "httpHeaders": {
8      "Location": "/services/data/v67.0/sobjects/Account/001R00000064wdtIAA"
9   },
10   "httpStatusCode": 201,
11   "referenceId": "refAccount"
12}

The following example shows the response for a subrequest that had an error while trying to create a Contact:

1{
2  "body" : [ {
3    "message" : "Email: invalid email address: Not a real email address",
4    "errorCode" : "INVALID_EMAIL_ADDRESS",
5    "fields" : [ "Email" ]
6  } ],
7  "httpHeaders" : { },
8  "httpStatusCode" : 400,
9  "referenceId" : "badContact"
10}

Behavior and Responses If There Are Illegal Characters in Reference IDs

The referenceIds must not contain anything besides letters, numbers, and underscores (’_’).

The API’s behavior if there are illegal characters depends on the API version and the release. (The pertinent API version that is used to make the composite request. That version isn’t necessarily the same as the API version specified in the url parameters in the subrequests.)

For example, consider the following request. It attempts to do the following:

Create an account named “Cloudy Consulting”.
Create a Contact, “Mary Smith”, linked to the Cloudy Consulting account.
Create another new account, named “Easy Spaces”.

It has illegal characters in the first reference ID, refNewAccount[1].

1{
2  "allOrNone": false,
3  "compositeRequest": [
4    {
5      "method": "POST",
6      "body": {
7        "name": "Cloudy Consulting"
8      },
9      "url": "/services/data/vXX.X/sobjects/Account/",
10      "referenceId": "refNewAccount[1]"
11    },
12    {
13      "method": "POST",
14      "body": {
15        "AccountId": "@{refNewAccount[1].id}",
16        "FirstName": "Mary",
17        "LastName": "Smith”
18      },
19      "url": "/services/data/vXX.X/sobjects/Contact",
20      "referenceId": "refNewContact"
21    },
22    {
23      "method": "POST",
24      "body": {
25        "name": "Easy Spaces"
26      },
27      "url": "/services/data/vXX.X/sobjects/Account/",
28      "referenceId": "refNewAccount2"
29    }
30  ]
31}

Version 51.0 and Earlier

In API version 51.0 and earlier, illegal characters in a reference ID cause all the subrequests that use that reference ID to fail. In this example, the response is:

1HTTP/1.1 200 OK
2{
3   "compositeResponse" : [
4      {
5         "body" : {
6            "id" : "001R0000006hfeZIAQ",
7            "success" : true,
8            "errors" : [ ]
9         },
10         "httpHeaders" : {
11            "Location" : "/services/data/v51.0/sobjects/Account/001R0000006hfeZIAQ"
12         },
13         "httpStatusCode" : 201,
14         "referenceId" : "refNewAccount[1]"
15      },
16      {
17         "body" : [
18            {
19               "errorCode" : "PROCESSING_HALTED",
20               "message" : "Invalid reference specified. No value for refNewAccount[1].id found in refNewAccount.
21            }
22         ],
23         "httpHeaders" : { },
24         "httpStatusCode" : 400,
25         "referenceId" : "refNewContact"
26      },
27      {
28         "body" : {
29            "id" : "001R0000006hfeeIAA",
30            "success" : true,
31            "errors" : [ ]
32         },
33         "httpHeaders" : {
34            "Location" : "/services/data/v51.0/sobjects/Account/001R0000006hfeeIAA"
35         },
36         "httpStatusCode" : 201,
37         "referenceId" : "refNewAccount2"
38      }
39   ]
40}

The two accounts are created (even though the first account uses illegal characters in its reference ID). But the attempt to create a contact (using the reference ID containing illegal characters) fails.

Responses for Version 51.0 and Earlier in Previous Releases

The response shown above is that for the Summer ’21 release and later. In releases before Summer ’21, problematic reference IDs in the response were truncated if the IDs contained ‘(’ or ‘[’. So the response would have been:

1{
2   "compositeResponse" : [
3      {
4         "body" : {
5            "id" : "001R0000006hfeZIAQ",
6            "success" : true,
7            "errors" : [ ]
8         },
9         "httpHeaders" : {
10            "Location" : "/services/data/v51.0/sobjects/Account/001R0000006hfeZIAQ"
11         },
12         "httpStatusCode" : 201,
13         "referenceId" : "refNewAccount"
14      },
15     ...
16}

Starting with the Summer ’21 release, problematic reference IDs are no longer truncated. This change makes it easier to match the parts of the response to the request.

Version 52.0 and Later

In API version 52.0 and later, any illegal characters in reference IDs cause the whole request to fail. The response to the example above is:

1HTTP/1.1 400 Bad Request
2[
3   {
4      "message" : "Provided referenceId ('refNewAccount[1]') must start with a letter or a number, and it can contain only letters, numbers and underscores ('_').",
5      "errorCode" : "JSON_PARSER_ERROR"
6   }
7]

Summary

a summary of the error responses

Behavior for References to Null Fields

The API’s behavior if there are references to null fields depends on the API version. (The pertinent API version is that used to make the composite request. That version isn’t necessarily the same as the API version specified in the url parameters in the subrequests.)

This behavior only applies to requests where the parent request uses an sObject Rows resource (for example, /services/data/vXX.X/sobjects/Contact/id).

Note

For example, consider this request. It locates an existing Contact and then uses @{refContact.FirstName} and @{refContact.LastName} to create a record.

1POST https://MyDomainName.my.salesforce.com/services/data/vXX.X/composite -H "Authorization: Bearer token"
2
3   "compositeRequest" : [
4      {
5         "method" : "GET",
6         "url" : "/services/data/v51.0/sobjects/Contact/003RO0000016kOuYAI?fields=FirstName,LastName",
7         "referenceId" : "refContact"
8      },
9      {
10         "method" : "POST",
11         "url" : "/services/data/v51.0/sobjects/Contact",
12         "referenceId" : "newContact",
13         "body" : {
14            "FirstName" : "@{refContact.FirstName}",
15            "LastName" : "@{refContact.LastName}",
16            "AccountId" : "001RO000001nGCdYAM"
17         }
18      }
19   ]
20}

What happens if the Contact’s first name is null (not set)?

Responses for Version 51.0 and Earlier

In API version 51.0 and earlier, the fact that the Contact’s FirstName field is null causes the dependent subrequest to fail.

1{
2   "compositeResponse" : [
3      {
4         "body" : {
5            "attributes" : {
6               "type" : "Contact",
7               "url" : "/services/data/v51.0/sobjects/Contact/003RO0000016kOuYAI"
8            },
9            "FirstName" : null,
10            "LastName" : "Wong",
11            "Id" : "003RO0000016kOuYAI"
12         },
13         "httpHeaders" : { },
14         "httpStatusCode" : 200,
15         "referenceId" : "refContact"
16      },
17      {
18         "body" : [
19            {
20               "errorCode" : "PROCESSING_HALTED",
21               "message" : "Invalid reference specified. No value for refContact.FirstName found in refContact.
22              Provided referenceId ('refContact.FirstName') must start with a letter or a number, 
23              and it can contain only letters, numbers and underscores ('_')."
24            }
25         ],
26         "httpHeaders" : { },
27         "httpStatusCode" : 400,
28         "referenceId" : "newContact"
29      }
30   ]
31}

That example assumes that allOrNone is set to false. If it’s true, the whole composite request is rolled back. See allOrNone Parameters in Composite and Collections Requests.

Responses for Version 52.0 and Later

In API version 52.0 and later, the request succeeds.

1{
2   "compositeResponse" : [
3      {
4         "body" : {
5            "attributes" : {
6               "type" : "Contact",
7               "url" : "/services/data/v51.0/sobjects/Contact/003RO0000016kOuYAI"
8            },
9            "FirstName" : null,
10            "LastName" : "Wong",
11            "Id" : "003RO0000016kOuYAI"
12         },
13         "httpHeaders" : { },
14         "httpStatusCode" : 200,
15         "referenceId" : "refContact"
16      },
17      {
18         "body" : {
19            "id" : "003RO0000016kRAYAY",
20            "success" : true,
21            "errors" : [ ]
22         },
23         "httpHeaders" : {
24            "Location" : "/services/data/v51.0/sobjects/Contact/003RO0000016kRAYAY"
25         },
26         "httpStatusCode" : 201,
27         "referenceId" : "newContact"
28      }
29   ]
30}

Behavior for References to Fields That Aren’t Specified in the Parent Request

In dependent subrequests, you must always only use fields that are explicitly selected in parent requests. If this practice isn’t followed, the API’s behavior depends on the API version. (The pertinent API version is that used to make the composite request. That version isn’t necessarily the same as the API version specified in the url parameters in the subrequests.)

For example, consider the following request. It attempts to:

Locate a specific Contact.
Use @{refContact.records[0].AccountId} to get that Contact’s Account ID.

However, the parent request doesn’t explicitly query for the AccountId.

1POST https://MyDomainName.my.salesforce.com/services/data/vXX.X/composite -H "Authorization: Bearer token"
2
3{
4   "compositeRequest" : [
5      {
6         "method" : "GET",
7         "url" : "/services/data/v51.0/query?q=select Id, Account.Name from Contact where Id='003RO0000016kOuYAI'",
8         "referenceId" : "refContact"
9      },
10      {
11         "method" : "GET",
12         "url" : "/services/data/v50.0/query?q=select Name from Account where Id = '@{refContact.records[0].AccountId}'",
13         "referenceId" : "refAccount"
14      }
15   ]
16}

Responses for Version 51.0 and Earlier

In API version 51.0 and earlier, there are rare cases where such a request succeeds.

The fact that a request like this sometimes succeeds should never be relied upon. If you plan to use a field from a parent request’s result, you should always explicitly select that field in the parent request.