Zoho CRM Composite API: Group Related Calls

Many integration tasks need several related API calls: create a contact, link it to an account, then create a deal for it. Made one by one, each call adds network time, and if the third fails you are left with half-finished data to clean up. The Zoho CRM composite API lets you send up to five sub-requests in a single call, reference the output of one sub-request in another, and optionally roll everything back if any part fails. This guide explains how composite requests work, when they help and when they do not, how rollback and parallel execution interact, how they consume credits, and how to design integrations around them.

How the Zoho CRM composite API works

According to Zoho's Composite API documentation, a composite call consists of one to five sub-requests sent to a single endpoint. Each sub-request specifies a method, a URI and, where needed, parameters and a body, and can carry a sub_request_id so others can refer to it. Using more than five sub-requests returns an error.

Two options control behaviour, according to the same documentation:

• rollback_on_fail: whether the whole composite request is rolled back if any sub-request fails; the default is false
• parallel_execution: whether independent sub-requests run in parallel; the default is true, but it defaults to false when rollback_on_fail is true, and the two cannot both be true

References let one sub-request use the output of another. The documented structure is the sub-request ID followed by a JSONPath to the value, so a sub-request that updates a record can use the ID returned when an earlier sub-request created it.

When a composite request helps

Composite requests suit small groups of related operations:

• Creating linked records together, such as a contact and the deal that belongs to it
• Making a change and reading back the result in one round trip
• Operations that must not be left half done, using rollback
• Integrations where network latency between your server and Zoho dominates the time taken

They are not a substitute for bulk APIs. Five sub-requests is a small ceiling, so large volumes still belong in Bulk Write or batched record APIs. Our guide to Zoho CRM API limits covers how to plan high-volume work within your edition's limits.

Rollback, parallel execution and automation

Rollback is the main reason to use composite requests for critical operations. If you create an account, a contact and a deal, and the deal fails validation, rollback removes the account and contact too, so you do not leave orphaned records.

Rollback has consequences worth understanding. Because sub-requests run in sequence when rollback is enabled, the call takes longer. Zoho's documentation also explains that with rollback enabled, workflows run only once all sub-requests have succeeded and no rollback is performed, whereas without rollback, automation actions trigger as normal for each sub-request. Read the documentation's notes on which operations are supported with rollback before relying on it; it lists restrictions, such as bulk delete not being supported.

Parallel execution speeds up independent sub-requests, such as reading three unrelated records, but any sub-request that references another must wait for it, so dependencies still run in order.

Credits and concurrency

Composite calls are accounted differently from single calls. Zoho's documentation explains how many API credits a composite call uses depending on rollback and outcome, and states that each composite call consumes five concurrency credits regardless of the number of sub-requests. That matters for integrations that already run close to their concurrency limit: replacing two simple calls with one composite call does not always reduce pressure on concurrency. Check the current figures in the documentation and against your own usage before redesigning an integration around composite calls.

Worked example: creating a customer and deal from a web order

Suppose an online training company creates a contact and a deal in Zoho CRM whenever someone buys a corporate package on its website. It wants either both records or neither, so it uses a composite request with rollback. This simplified, untested request body shows the structure; the field names are standard Zoho fields, and the values are fictitious.

{
  "rollback_on_fail": true,
  "parallel_execution": false,
  "__composite_requests": [
    {
      "sub_request_id": "1",
      "method": "POST",
      "uri": "/crm/v8/Contacts",
      "body": {"data": [{"Last_Name": "Okafor", "First_Name": "Ada", "Email": "[email protected]"}]}
    },
    {
      "sub_request_id": "2",
      "method": "POST",
      "uri": "/crm/v8/Deals",
      "body": {"data": [{"Deal_Name": "Corporate package - Okafor", "Stage": "Closed Won",
                         "Contact_Name": {"id": "@{1:$.data[0].details.id}"}}]}
    }
  ]
}

The deal links to the contact through a reference to the ID returned by sub-request 1, following the reference structure in Zoho's documentation. If the deal fails, for example because a required field is missing, rollback removes the contact too. The integration logs the response for both sub-requests and, on failure, stores the order for retry after the cause is fixed. In practice, the company would first check whether the contact already exists, or use upsert, to avoid duplicates.

Designing around composite requests

A few practices keep composite integrations reliable:

• Keep each composite request to one business operation, so a rollback has a clear meaning
• Log the full response, including each sub-request's result, for troubleshooting
• Make retries safe by checking for existing records or using upsert in the first sub-request
• Validate data before sending, because a rollback still costs time and credits
• Fall back gracefully if the composite endpoint returns an error for the whole request, rather than retrying in a tight loop

Our guide to Zoho CRM API error handling covers retry and logging patterns that apply equally to composite calls.

Testing composite requests

Test composite requests in a sandbox or test account before going live, and test the failure paths as carefully as the success path. Send a request where the last sub-request is deliberately invalid and confirm that, with rollback enabled, no records remain. Check that workflows behave as you expect in both the success and rollback cases. Confirm that references resolve correctly when the earlier sub-request returns more than one record. Record the response times too, so you know whether sequential execution with rollback is fast enough for your use case.

Common mistakes

• Expecting the composite API to replace bulk APIs for large volumes
• Packing unrelated operations into one request, so a failure in one rolls back the others
• Enabling rollback without understanding its effect on workflows and timing
• Ignoring concurrency consumption when an integration is near its limit
• Logging only the overall status and not each sub-request's result
• Creating duplicates on retry because the first sub-request always inserts

Frequently Asked Questions

What is the Zoho CRM composite API?

It lets you send up to five related sub-requests in one API call, reference outputs between them and optionally roll back all changes if any part fails.

How many sub-requests can one composite call include?

Zoho's documentation says a composite call can include a maximum of five sub-requests; using more returns an error.

What does rollback_on_fail do?

When true, the whole composite request is rolled back if any sub-request fails, so related records are not left half created. It defaults to false.

Does the composite API save API credits?

Not necessarily. Zoho documents specific credit and concurrency consumption for composite calls, so compare it with your current usage before switching.

Keep related changes consistent

We design Zoho CRM integrations that group related operations safely and log every result. See our Zoho CRM automation services, or talk to us about your integration.

About the Author

Manav Sharma is the founder of Insyrge and a CRM solutions architect. He works across Zoho, Salesforce, HubSpot, Odoo and more, designing the CRM setups, integrations and automations that keep sales and operations teams working from the same data.