From Campaign Leads to Sales Orders with Zoho CRM Mass Action APIs

From Campaign Leads to Sales Orders with Zoho CRM Mass Action APIs



Hello all!!
In growing businesses, sales teams often deal with a large volume of records every day - leads from campaigns, qualified prospects ready for conversion, and approved quotes that must be converted into sales orders. Performing these actions one by one can be time-consuming. Zoho CRM's Mass Action APIs let you perform the same operation on multiple records asynchronously.

In this Kaizen post, let us look at a real-world sales scenario where Zylker uses the following APIs:
  1. Mass Change Owner API
  2. Mass Convert Lead API
  3. Mass Convert Inventory Records API
  4. Corresponding Status APIs to track the background jobs
We will use these APIs to automate a campaign-to-sales-order flow.

Use Case

Zylker runs a product campaign and receives a large number of leads. These leads are initially assigned to the campaign manager for review. After the review is complete, the campaign manager uses the Mass Change Owner API to transfer ownership of all campaign leads in the custom view to the sales representative responsible for handling the campaign. Since this is an asynchronous operation, the Zylker stores the returned job ID and uses the Mass Change Owner Status API to monitor the progress until the ownership change is complete.

The sales representatives follow up with the leads. Leads that meet Zylker's qualification criteria are collected and converted in batches using the Mass Convert Lead API. Depending on the conversion options, the API creates the required Account, Contact, and optionally a Deal. Zylker tracks the conversion progress using the Mass Convert Lead Status API.

As the sales process continues, Quotes are created for interested customers. At the end of the day, approved Quotes are converted into Sales Orders using the Mass Convert Inventory Records API. Zylker stores the returned job ID and uses the Mass Inventory Conversion Status API to monitor the conversion until all eligible Quotes are processed successfully.

Note:
  1. The Mass Change Owner API can bulk assign ownership for records in a custom view or territory and supports up to 50,000 records in a custom view and it schedules a background job and returns a job ID for status tracking. 
  2. The Mass Convert Lead API converts up to 50 leads in one call.
  3. The Mass Convert Inventory Records API converts up to 50 inventory records per call, such as Quotes to Sales Orders or Invoices.

Step 1: Assign campaign leads to regional sales representatives

Zylker’s campaign manager first reviews leads in a custom view, for example:

Custom view: North Region Campaign Leads
Module: Leads
Owner: Campaign Manager
Criteria: Region = North

Once the manager finalizes the set of records, he uses the Mass Change Owner API to assign all records in that custom view to the relevant regional sales representative.

Sample Request:

Request URL: {api-domain}/crm/v8/Leads/actions/mass_change_owner
(For this use case, the module is Leads)

Request Method: POST
Input JSON:

{
  "cvid": "5725767000000087501",
  "owner": {
    "id": "5725767000000583032"
  },
  "criteria": {
    "field": {
      "api_name": "Region"
    },
    "comparator": "equal",
    "value": "North"
  }
}



Keys Explanation:
  1. cvid: The ID of the custom view whose records must be reassigned.
  2. owner.id: The user ID of the regional sales representative.
  3. criteria: Optional additional filter to narrow down records inside the custom view.
  4. field.api_name: API name of the field used in the condition.
  5. field.comparator: Comparison operator, such as equal.
  6. field.value: Value to match in the selected field.

Sample Response:


{
    "data": [
        {
            "code": "SCHEDULED",
            "details": {
                "job_id": "5725767000011072001"
            },
            "message": "change owner is successfully scheduled",
            "status": "success"
        }
    ]
}


The success response only indicates that the owner change has been scheduled. Since this is an asynchronous API, use the returned job ID with the Mass Change Owner Status API to track the operation until it completes.

Step 2: Check the owner change status

After scheduling the owner change, Zylker stores the returned job ID and uses the Mass Change Owner Status API to periodically check the status of the job until the operation is completed.

Sample Request:

Request URL: {api-domain}/crm/v8/Leads/actions/mass_change_owner?job_id=5725767000011072001
Request Method: GET

Sample Response:

{
    "data": [
        {
            "Status": "COMPLETED",
            "Failed_Count": 0,
            "Updated_Count": 349,
            "Not_Updated_Count": 0,
            "Total_Count": 349
        }
    ]
}

This ensures that the campaign manager knows whether all region-specific leads were reassigned successfully before sales follow-up begins.

Mass Change Owner Status API - failed case
Possible job statuses include COMPLETED, SCHEDULED, RUNNING, and FAILED. The response includes counts such as Total_Count, Updated_Count, Not_Updated_Count, and Failed_Count.

Step 3: Convert qualified leads in batches using the Mass Convert Lead API

After the sales representative follows up, leads that meet the required engagement and score criteria are moved into a qualified-leads view.
For example:

Custom view: Qualified Campaign Leads
Criteria:
  1. Lead Status = Qualified
  2. Score >= 80
  3. Email Opt Out = false
  4. Follow-up Completed = true

Zylker fetches the lead IDs from this view and converts them in batches of up to 50 records using the Mass Convert Lead API.

Use the COQL API to retrieve the record IDs that match the above criteria.

Sample Request:

Request URL: {api-domain}/crm/v8/coql
Request Method: POST

Query:
{
  "select_query": "select id, Last_Name, Lead_Status, Score, Email_Opt_Out from Leads#5725767000000087501 where (Lead_Status = 'Qualified' and Score >= 80) and (Email_Opt_Out = false and Follow_up_Completed = true) limit 0, 200"
}

//Leads#5725767000000087501 | {module_API_name#CVID} - Custom View ID in the Leads module.
The Mass Convert Lead API accepts a maximum of 50 lead record IDs in the ids JSON array. If Deal creation is required, the Deals JSON object must include mandatory Deal fields such as Deal_Name, Amount, Stage, Closing_Date, and Pipeline when pipeline is enabled. 

Sample Request:

Request URL:{api-domain}/crm/v8/Leads/actions/mass_convert
Request Method: POST

Convert leads without creating Deals:

{
  "ids": [
    "5725767000010892005",
    "5725767000008883007",
    "554023000001111003"
     ...//you can give 50 lead IDs per API call.
  ],
  "assign_to": {
    "id": "554023000000987654"
  },
  "carry_over_tags": [
    {
      "api_name": "Contacts",
      "id": "5540230000000002179"
    }
  ],
  "move_attachments_to": {
    "api_name": "Contacts",
    "id": "5540230000000002179"
  }
}



Convert leads and create Deals:

{
  "ids": [
    "554023000001111001",
    "554023000001111002",
    "554023000001111003"
     ...
 ],
  "Deals": {
    "Deal_Name": "Product Campaign Deal",
    "Stage": "Qualification",
    "Closing_Date": "2026-08-31",
    "Pipeline": "Standard",
    "Amount": 25000
  },
  "assign_to": {
    "id": "554023000000987654"
  },
  "carry_over_tags": [
    {
      "api_name": "Contacts",
      "id": "5540230000000002179"
    },
    {
      "api_name": "Accounts",
      "id": "5540230000000002177"
    },
    {
      "api_name": "Deals",
      "id": "5540230000000002181"
    }
  ],
  "move_attachments_to": {
    "api_name": "Contacts",
    "id": "5540230000000002179"
  }
}


Keys Explanation:
  1. id: Contains the Lead record IDs that must be converted. Get these IDs by fetching records from the Qualified Campaign Leads custom view using the COQL API with CVID. Use the id value from each record in the response. Pass a maximum of 50 Lead IDs in one Mass Convert Lead API request.
  1. Deals: Contains the details of the Deal to be created during lead conversion. Include this object only if you want to create a Deal along with the Account and Contact. If you omit this object, the lead is converted without creating a Deal. Use the Fields Metadata API to get the Deal field API names, and the Get Records API to retrieve the corresponding field values.
  1. assign_to.id: Specify the CRM user ID who will own the converted Account, Contact, and Deal. Get this value using the Users API. In this use case, specify the ID of the regional sales representative who should own the converted records.
  1. carry_over_tags: Specify whether the Lead tags should be copied to the converted records. Include this object only if you want to carry over the Lead tags during conversion.
  1. carry_over_tags.api_name: Specify the API name of the target module where the Lead tags should be copied. Possible values are Contacts, Accounts, and Deals.
  1. carry_over_tags.id: Specify the ID of the target module where the Lead tags should be copied. Get this value using the Modules Metadata API.
  1. move_attachments_to: Specify the module to which the Lead attachments should be moved after conversion. Include this object only if you want to transfer the Lead attachments to one of the converted records.
  1. move_attachments_to.api_name: Specify the API name of the target module where the Lead attachments should be moved. Possible values are Contacts, Accounts, and Deals.
  1. move_attachments_to.id: Specify the ID of the target module where the Lead attachments should be moved. Get this value using the Modules Metadata API.
Sample Response:

{
    "code": "SCHEDULED",
    "details": {
        "job_id": "5725767000011068004"
    },
    "message": "Mass Convert scheduled successfully",
    "status": "success"
}

Zylker stores this job_id and tracks the conversion status.

Step 4: Check the mass lead conversion status using the Mass Convert Lead Status API

The Mass Convert Lead Status API returns the status of a scheduled mass lead conversion job. Its response includes the job status and counts such as total, converted, not converted, and failed records.

Sample Request:

Request URL: {api-domain}/crm/v8/Leads/actions/mass_convert?job_id=5725767000011068004
Request Method: GET

Response:

{
    "data": [
        {
            "Status": "COMPLETED",
            "Failed_Count": 0,
            "Not_Converted_Count": 0,
            "Total_Count": 3,
            "Converted_Count": 3
        }
    ]
}


Mass Convert Lead Status API - failed case
The Mass Convert Lead Status API returns status values such as completed, scheduled, in progress, and failed, along with Total_Count, Converted_Count, Not_Converted_Count, and Failed_Count.

Step 5: Convert approved Quotes into Sales Orders using the Mass Inventory Convert Records API

Once a lead becomes a customer opportunity, sales representatives create Quotes for the customer’s requirements. At the end of each day, Zylker identifies Quotes that meet the following conditions:


Module: Quotes
Criteria:
  1. Quote Stage = Confirmed
  2. Converted to Sales Order = false


Zylker fetches these Quote IDs and converts them into Sales Orders using the Mass Convert Inventory Records API.

Use the COQL API to retrieve the record IDs that match the above criteria.

Sample Request:

Request URL: {api-domain}/crm/v8/coql
Request Method: POST

Query:

{
  "select_query": "select id, Subject, Quote_Stage from Quotes where Quote_Stage = 'Confirmed' limit 0, 200"
}

The Mass Convert Inventory Records API supports conversions from Quotes to Sales Orders or Invoices, and from Sales Orders to Invoices. It is asynchronous, returns a job ID, and supports up to 50 records in a single API call from one parent inventory module at a time. 

Sample Request:

Request URL: {api-domain}/crm/v8/Quotes/actions/mass_convert

Request Method: POST

Input JSON


{
  "ids": [
    "554023000003111001",
    "554023000003111002",
    "554023000003111003",
     ...//You can convert up to 50 Quotes/Sales Orders IDs in a single API call.
  ],
  "convert_to": [
    {
      "module": {
        "api_name": "Sales_Orders",
        "id": "5540230000000002215"
      }
    }
  ],
  "carry_over_tags": true,
  "assign_to": {
    "id": "554023000000987654"
  },
  "related_modules": [
    {
      "api_name": "Tasks",
      "id": "5540230000000002193"
    },
    {
      "api_name": "Calls",
      "id": "5540230000000002197"
    }
  ]
}



Keys Explanation:
  1. ids: Contains the Quote record IDs to be converted into Sales Orders. Pass a maximum of 50 Quote IDs in one Mass Convert Inventory Records API request.
  1. convert_to: Specify the target module for inventory conversion. 
  1. convert_to.module.api_name: Specify the API name of the target module. In this use case, use Sales_Orders to convert Quotes into Sales Orders. 
  1. convert_to.module.id: Specify the ID of the target module. Get this value using the Modules Metadata API for the Sales_Orders module. 
  1. carry_over_tags: Specify whether the tags associated with the Quote should be copied to the converted Sales Order. It is a Boolean key. Set this to true if you want to retain the Quote tags in the Sales Order. 
  1. assign_to.id: Specify the CRM user ID who will own the converted Sales Orders. Get this value using the Users API. In this use case, this can be the sales representative who owns the Quote.
  1. related_modules: Specifies the related modules whose records should be associated with the converted Sales Order. Use this when Zylker wants related records, such as Tasks, Calls, or Meetings linked to the Quote, to be carried over or associated with the converted Sales Order. Use the Modules Metadata API to get the IDs of the modules.
Sample Response:

{
    "code": "SCHEDULED",
    "details": {
        "job_id": "5725767000011082001"
    },
    "message": "Mass Convert scheduled successfully",
    "status": "success"
}



Step 6: Check the inventory conversion status using the Get Mass Inventory Conversion Status

After scheduling the Quote-to-Sales Order conversion, the Zylker checks the mass inventory conversion job status with the job ID received previously in the response of  Mass Convert Inventory Records API.

Sample Request:

Request URL: {api-domain}/crm/v8/Quotes/actions/mass_convert?job_id=5725767000011082001
Request Method: GET

Response:

{
    "data": [
        {
            "total_count": 3,
            "not_converted_count": 0,
            "failed_count": 3,
            "converted_count": 0,
            "status": "COMPLETED"
        }
    ]
}


The Mass Convert Inventory Records Status API is used to monitor bulk inventory conversion jobs, such as Quote conversion jobs.

The Mass Inventory Conversion Status API returns the status of the inventory conversion job, such as SCHEDULED, IN PROGRESS, COMPLETED, or FAILED, along with count details such as total_count, converted_count, not_converted_count, and failed_count. 

Conclusion:

Mass Actions APIs help Zylker handle large CRM operations asynchronously and reliably. Leads are reassigned to the right sales representatives, qualified leads are converted in batches, and approved Quotes are converted into Sales Orders.
By storing each job_id, tracking the status APIs, and reviewing failed records separately, Zylker keeps the entire flow scalable, traceable, and error-safe from campaign leads to completed Sales Orders.
We trust that this post meets your needs and is helpful. Let us know your thoughts in the comment section or reach out to us at support@zohocrm.com.
Stay tuned for more insights in our upcoming Kaizen posts!

Cheers!!!