Chain Mutations by Using Field References
| AVAILABLE API VERSION |
|---|
| Beta v59.0–65.0 |
| Generally available v66.0 and later |
Create a mutation request with an operation that references another operation by using field references. You can create a record and a parent or child record in the same transaction. You can also chain operations such as creating a user and then creating an account whose owner is the newly created user.
When working with multiple operations in a single mutation request, consider setting the allOrNone boolean to false so that some operations successfully execute even if there are independent unsuccessful operations.
Chain Operations with Multiple Field Reference Patterns
There are multiple ways to reference fields in chained mutations. Assuming ref is the name or alias of a previous mutation operation from the same request, supported field reference patterns are:
@{ref.Record.Id}- Explicit record ID reference. Available in API v67.0 and later.@{ref.Record.FieldName.value}- GraphQL field reference. For example,Name { value }in a GraphQL query is@{ref.Record.Name.value}. Available in API v67.0 and later.@{ref}-IdOrRefscalar reference that accepts a record ID value or the name or alias of another operation. Available in API v59.0 and later.
When chaining operations, place an operation after the operation it references. If you order an operation that references another operation first, the request fails because the operation can’t find the referenced operation.
Note
Example: Chain Account, Contact, and Opportunity Creation
This example chains the creation of an account, a contact, and an opportunity in a single request and uses multiple field reference patterns. The child contact creation requires the AccountId field value from the account creation operation. The contact create operation passes in @{AccountCreate} to the Contact.AccountId field to reference the Id field on the newly created account. The contact creation also requires the LastName field value from the account creation operation. The contact create operation passes in @{AccountCreate.Record.Name.value} to the Contact.LastName field. The opportunity creation also requires the AccountId field value from the account creation operation. In this example, the opportunity create operation passes in @{AccountCreate.Record.Id} to reference the Id of the record explicitly.
1mutation CreateAccountAndContact {
2 uiapi(input: { allOrNone: false }) {
3 AccountCreate(input: {
4 Account: {
5 Name: "Mutation Fun"
6 }
7 }) {
8 Record {
9 Id # referenced in 'OpportunityCreate'
10 Name { value } # referenced in 'ContactCreate'
11 }
12 }
13 ContactCreate(input: {
14 Contact: {
15 MailingCity: "Paris"
16 LastName: "@{AccountCreate.Record.Name.value}"
17 AccountId: "@{AccountCreate}" # equivalent to AccountCreate.Record.Id
18 }
19 }) {
20 Record {
21 Id
22 LastName { value } # referenced in 'OpportunityCreate'
23 MailingCity { value } # referenced in 'OpportunityCreate'
24 }
25 }
26 OpportunityCreate(input: {
27 Opportunity: {
28 Name: "@{ContactCreate.Record.LastName.value}" # 'ContactCreate' reference
29 Description: "@{ContactCreate.Record.MailingCity.value}" # 'ContactCreate' reference
30 AccountId: "@{AccountCreate.Record.Id}" # 'AccountCreate' reference
31 StageName: "Value Proposition"
32 CloseDate: "2026-12-31"
33 }
34 }) {
35 Record {
36 Id
37 AccountId { value }
38 Name { value }
39 Description { value }
40 }
41 }
42 }
43}The response looks like this.
1{
2 "data": {
3 "uiapi": {
4 "AccountCreate": {
5 "Record": {
6 "Id": "001LT000011naPRYAY",
7 "Name": {
8 "value": "Mutation Fun"
9 }
10 }
11 },
12 "ContactCreate": {
13 "Record": {
14 "Id": "003LT00000ArlizYAB",
15 "LastName": {
16 "value": "Mutation Fun"
17 },
18 "MailingCity": {
19 "value": "Paris"
20 }
21 }
22 },
23 "OpportunityCreate": {
24 "Record": {
25 "Id": "006LT000005R4HZYA0",
26 "AccountId": {
27 "value": "001LT000011naPRYAY"
28 },
29 "Name": {
30 "value": "Mutation Fun"
31 },
32 "Description": {
33 "value": "Paris"
34 }
35 }
36 }
37 }
38 },
39 "errors": [],
40 "extensions": {}
41}Example: Chain Contact Update and Opportunity Creation
This example updates a contact and then creates an opportunity for the related account with the contact’s name.
1mutation UpdateContactAndCreateOpportunity{
2 uiapi {
3 contact: ContactUpdate(input: {
4 Contact: {
5 MailingCity: "Paris"
6 },
7 Id: "003xx000004WjJEAA0"
8 }) {
9 Record {
10 Id
11 Name { value } # referenced in 'oppty'
12 AccountId { value } # referenced in 'oppty'
13 }
14 }
15 oppty: OpportunityCreate(input: {
16 Opportunity: {
17 AccountId: "@{contact.Record.AccountId.value}" # 'contact' field reference
18 ContactId: "@{contact.Record.Id}" # 'contact' field reference
19 Name: "@{contact.Record.Name.value}" # 'contact' field reference
20 StageName: "Value Proposition"
21 CloseDate: "2026-12-31"
22 }
23 }) {
24 Record {
25 Id
26 AccountId { value }
27 ContactId { value }
28 Name { value }
29 Description { value }
30 }
31 }
32 }
33}The response looks like this.
1{
2 "data": {
3 "uiapi": {
4 "contact": {
5 "Record": {
6 "Id": "003LT00000ArlizYAB",
7 "Name": {
8 "value": "Mutation Fun"
9 },
10 "AccountId": {
11 "value": "001LT000011naPRYAY"
12 }
13 }
14 },
15 "oppty": {
16 "Record": {
17 "Id": "006LT000005R5FFYA0",
18 "AccountId": {
19 "value": "001LT000011naPRYAY"
20 },
21 "ContactId": {
22 "value": "003LT00000ArlizYAB"
23 },
24 "Name": {
25 "value": "Mutation Fun"
26 },
27 "Description": null
28 }
29 }
30 }
31 },
32 "errors": [],
33 "extensions": {}
34}
j