How to Create and Update CRM Records Using the Bigin API

What Will You Learn in This Guide?

Manual data entry slows small teams down and invites mistakes. The Bigin API lets your website, billing tool, or custom script write directly to your CRM. This guide shows you how to create and update CRM records using the Bigin API for Bigin by Zoho CRM, from the first request to safe, repeatable automation.

You will learn which modules you can write to, which fields each module requires, and how to send single and batch requests. You will also learn how updates and upserts work, how duplicate checks behave, and how to fix common errors.

Here is what the article covers:

• Which modules and scopes you need
• How to create contacts, companies, and deals
• Which fields are mandatory
• How to update existing records
• How to use upsert to avoid duplicates
• Error handling and best practices

---

What Do You Need Before You Create or Update Records?

You need an OAuth client, an access token, and the right scope. If you have not set these up yet, review Bigin’s authorization documentation first.

Which Scopes Does Each Request Require?

Scopes limit what your token can do. The Add records endpoint accepts a token with the ZohoBigin.modules.ALL scope, a module-specific ALL scope, or a WRITE or CREATE scope for the target module. The Update records endpoint uses the module’s UPDATE scope. Request only the scopes your integration needs.

Which Domain Should You Call?

Bigin APIs run on eight domains, and you must choose the one that matches your data center: US, EU, AU, IN, CN, JP, SA, or CA. The US example uses www.zohoapis.com. Calling the wrong domain makes requests fail, so confirm your region first.

How Do You Authenticate Each Request?

You pass the access token in an Authorization header, in the form Zoho-oauthtoken followed by your token. Keep tokens out of source code and logs. Refresh them automatically when they expire.

---

Which Bigin Modules Can You Write To?

Bigin groups data into modules. Each module has an API name that you place in the request URL.

What Are the Module API Names?

Module in Bigin	API Name
Contacts	Contacts
Pipelines (deals)	Pipelines
Companies	Accounts
Products	Products
Tasks	Tasks
Events	Events
Calls	Calls

This table matches Bigin’s documentation, which lists Companies under the API name Accounts. Remember that quirk, because many developers expect “Companies.”

How Do You Find Field API Names?

Use only field API names in your input, and look up each field’s api_name value through the Fields metadata API. Display labels in the Bigin interface may differ from API names, so check the metadata before you build your payload.

---

How Do You Create a Record With the Bigin API?

Creation uses a POST request to the module endpoint. You send a JSON body with a “data” array.

What Does a Basic Create Request Look Like?

Here is a simple example that creates a contact in a US-based account:

POST https://www.zohoapis.com/bigin/v2/Contacts
Authorization: Zoho-oauthtoken <ACCESS_TOKEN>
Content-Type: application/json

{
  "data": [
    {
      "First_Name": "Sarah",
      "Last_Name": "Johnson",
      "Email": "sarah.johnson@example.com",
      "Title": "HR Director"
    }
  ]
}

A successful call returns the new record IDs. Store those IDs, because you need them to update the records later.

Which Fields Are Mandatory?

Each module has system-defined mandatory fields. Contacts require Last_Name, and Companies require Account_Name. Pipelines require Deal_Name, Sub_Pipeline, and Stage. Products require Product_Name, Tasks require Subject, and Events require Event_Title, Start_DateTime, and End_DateTime. You must also supply any user-defined mandatory fields that your account sets.

How Many Records Can You Create at Once?

You can insert a maximum of 100 records per API call. Batch your records whenever possible. Batching also saves API credits, since insert and update calls deduct 1 credit for every 10 records.

---

How Do You Create a Deal in the Pipelines Module?

Deals need more structure than contacts, because they belong to a sub-pipeline and a stage.

Which Fields Does a Pipeline Record Use?

Field	Required	Purpose
Deal_Name	Yes	The name of the deal
Sub_Pipeline	Yes	The sub-pipeline the deal belongs to
Stage	Yes	The current stage within that sub-pipeline
Amount	No	The deal value
Closing_Date	No	The expected or actual closing date
Contact_Name	No	The ID of the related contact
Account_Name	No	The ID of the related company
Owner	No	The ID of the owning user

How Do You Link a Deal to a Contact and Company?

Provide the related record IDs as JSON objects. You can get the company and contact IDs from the Get records API, and the owner ID from the Get users data API. Create the company and contact first, save their IDs, and then create the deal that references them.

What Does a Deal Payload Look Like?

{
  "data": [
    {
      "Deal_Name": "Website Redesign",
      "Sub_Pipeline": "Sales Pipeline Standard",
      "Stage": "Needs Analysis",
      "Amount": 4000,
      "Closing_Date": "2026-12-15",
      "Contact_Name": { "id": "<CONTACT_ID>" },
      "Account_Name": { "id": "<COMPANY_ID>" }
    }
  ]
}

Replace the placeholders with real IDs and with the sub-pipeline and stage names in your own account.

---

How Do You Format Field Values Correctly?

Bigin validates data types strictly. Bad formats cause errors, so check each field type.

Which Formats Do Common Field Types Require?

Field Type	Accepted Format
Single line text	Up to 255 characters
Date	yyyy-MM-dd format
Date/Time	yyyy-MM-ddTHH:mm:ss±HH:mm in ISO 8601 format
Checkbox	Boolean values only, true or false
Currency and decimal	Numeric values only
Multi-select picklist	A JSON array

What Happens When a Value Is Too Long?

If a field value exceeds its maximum length, the API returns an error. Validate data on your side before you send it. For example, trim long descriptions and normalize phone numbers.

---

How Do You Update an Existing Record With the Bigin API?

Updates use a PUT request. You need the record’s ID, which you receive when you create it or fetch it with the Get records API.

What Does an Update Request Look Like?

The Update records endpoint changes existing records or one specific record, and you can get the record ID from the Get records API. A typical request to move a deal to a new stage looks like this:

PUT https://www.zohoapis.com/bigin/v2/Pipelines
Authorization: Zoho-oauthtoken <ACCESS_TOKEN>
Content-Type: application/json

{
  "data": [
    {
      "id": "<PIPELINE_RECORD_ID>",
      "Stage": "Negotiation/Review"
    }
  ]
}

Send only the fields you want to change, plus the record ID. Stage names must match the stages in your sub-pipeline.

How Many Records Can You Update at Once?

You can update a maximum of 100 records per API call. Group related updates into batches, such as nightly stage syncs from another system.

Can You Update Records Without the ID?

Sometimes. Zoho’s community announcement explains that you can update records using unique custom fields if the Prevent Duplicate Values option is enabled for those fields. This approach helps when your external system stores its own identifiers.

---

How Does Upsert Work in the Bigin API?

Upsert combines update and insert. It saves a lookup step because one call either updates an existing record or creates a new one.

What Does the Upsert Endpoint Do?

The Upsert records API inserts or updates a record in a single request, and it uses system-defined or user-defined unique fields to decide whether the record already exists. The endpoint follows the pattern /bigin/v2/{module_api_name}/upsert. You can upsert a maximum of 100 records per call.

How Do You Control Duplicate Checks?

Include a duplicate_check_fields array in the request body to define the order of the duplicate checks. If you omit it, the API checks system-defined unique fields first, and then user-defined unique fields. For example, you can check by Email for contacts, so a form submission updates an existing person instead of creating a duplicate.

When Should You Use Upsert Instead of Create?

Situation	Best Choice
You know the record is new	Create (POST)
You know the record ID and want to change it	Update (PUT)
You do not know whether the record exists	Upsert
You sync data from another system on a schedule	Upsert

---

How Do Duplicate Checks and Workflows Affect Your Calls?

Two behaviors surprise many developers: duplicate protection and workflow triggers.

How Do Duplicate Checks Work?

The API performs duplicate checks on every add record call, based on unique fields. It also performs them on every update call. Therefore, provide unique values for designated fields, and expect errors when you submit a duplicate.

Do Workflows Run When You Use the API?

Yes, by default. If you do not specify a trigger value, the workflows associated with the API run. To prevent them, pass the trigger value as an empty array. Consider disabling workflows during bulk imports, so you do not send thousands of automated emails by accident.

---

How Do You Handle Errors When Creating or Updating Records?

Errors will happen. Plan for them from the start.

Which Errors Appear Most Often?

Error Code	Meaning	Typical Fix
INVALID_MODULE	The module name is invalid or lacks permission	Use a valid module API name
NO_PERMISSION	The user cannot create or edit that module	Review user permissions and scopes
MANDATORY_NOT_FOUND	A required field is missing	Add the field, such as Last_Name
INVALID_DATA	A value has the wrong data type	Correct the format using the field metadata

Bigin’s documentation lists these error codes, and it notes that some validation errors return HTTP status 202 in the response. Always inspect the per-record status in the response body, not just the HTTP status code.

How Should You Retry Failed Requests?

1. Read the error code and message for each record.
2. Fix data problems before you retry.
3. Retry network failures with a short delay.
4. Log failures with the record identifiers, not the full customer data.
5. Alert a person after repeated failures.

---

What Are the Best Practices for Writing Data With the Bigin API?

Good habits protect your data and your credit budget.

How Do You Keep Your CRM Clean?

• Use upsert for form and system syncs.
• Store Bigin record IDs in your own system.
• Validate and normalize data before sending it.
• Test with sample records first.
• Disable workflows during large imports.

How Do You Stay Within Limits?

Batch up to 100 records per call, and avoid parallel bursts. Bigin also applies concurrency limits, so large numbers of simultaneous calls can trigger errors. For very large imports, consider Bigin’s bulk write API instead. The bulk write job supports insert, update, and upsert operations from uploaded CSV files.

---

What Should You Remember About Creating and Updating Records With the Bigin API?

Creating records uses POST, updating uses PUT, and upsert handles both with one call. Each module has mandatory fields, strict data formats, and a 100-record limit per call. Check the response for each record, and design for duplicates and errors from the beginning.

Bigin by Zoho CRM gives small teams a well-documented API for this work. As a result, you can connect forms, billing tools, and internal systems to your CRM without manual copying.

How Can You Start This Week?

First, list the data you want to push into Bigin. Next, fetch your field metadata and note the API names. Then, create one test contact and one test deal. Finally, update the deal’s stage and try an upsert with a duplicate check on email.

---

What Are the Most Frequently Asked Questions About Creating and Updating Records With the Bigin API?

---