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.

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} - IdOrRef scalar 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.

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.

The response looks like this.

This example updates a contact and then creates an opportunity for the related account with the contact’s name.

The response looks like this.