Zoho Bigin

Access the Zoho Bigin API with managed OAuth authentication. Manage contacts, companies, pipelines, and products with full CRUD operations.

Quick Start

# List contacts
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-bigin/bigin/v2/Contacts?fields=First_Name,Last_Name,Email')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Base URL

https://gateway.maton.ai/zoho-bigin/bigin/v2/{endpoint}

The gateway proxies requests to www.zohoapis.com/bigin/v2 and automatically injects your OAuth token.

Authentication

All requests require the Maton API key in the Authorization header:

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key

Connection Management

Manage your Zoho Bigin OAuth connections at https://ctrl.maton.ai.

List Connections

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=zoho-bigin&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Connection

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'zoho-bigin'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "zoho-bigin",
    "metadata": {}
  }
}

Open the returned url in a browser to complete OAuth authorization.

Delete Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Specifying Connection

If you have multiple Zoho Bigin connections, specify which one to use with the Maton-Connection header:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-bigin/bigin/v2/Contacts?fields=First_Name,Last_Name,Email')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If omitted, the gateway uses the default (oldest) active connection.

API Reference

Modules

Zoho Bigin organizes data into modules. Available modules include:

List Records

GET /zoho-bigin/bigin/v2/{module_api_name}?fields={field1},{field2}

Query Parameters:

Example - List Contacts:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-bigin/bigin/v2/Contacts?fields=First_Name,Last_Name,Email,Phone')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "data": [
    {
      "First_Name": "Ted",
      "Email": "support@bigin.com",
      "Last_Name": "Watson",
      "id": "7255024000000596045"
    }
  ],
  "info": {
    "per_page": 200,
    "count": 1,
    "page": 1,
    "more_records": false
  }
}

Example - List Companies (Accounts):

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-bigin/bigin/v2/Accounts?fields=Account_Name,Website')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Record

GET /zoho-bigin/bigin/v2/{module_api_name}/{record_id}

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-bigin/bigin/v2/Contacts/7255024000000596045')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Records

POST /zoho-bigin/bigin/v2/{module_api_name}
Content-Type: application/json

{
  "data": [
    {
      "field_api_name": "value"
    }
  ]
}

Mandatory Fields by Module:

Example - Create Contact:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "data": [{
        "Last_Name": "Smith",
        "First_Name": "John",
        "Email": "john.smith@example.com",
        "Phone": "+1-555-0123"
    }]
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/zoho-bigin/bigin/v2/Contacts', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "data": [
    {
      "code": "SUCCESS",
      "details": {
        "Modified_Time": "2026-02-06T00:28:53-08:00",
        "Modified_By": {
          "name": "User Name",
          "id": "7255024000000590001"
        },
        "Created_Time": "2026-02-06T00:28:53-08:00",
        "id": "7255024000000605002",
        "Created_By": {
          "name": "User Name",
          "id": "7255024000000590001"
        }
      },
      "message": "record added",
      "status": "success"
    }
  ]
}

Example - Create Company (Account):

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "data": [{
        "Account_Name": "Acme Corporation",
        "Website": "https://acme.com"
    }]
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/zoho-bigin/bigin/v2/Accounts', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Update Records

PUT /zoho-bigin/bigin/v2/{module_api_name}
Content-Type: application/json

{
  "data": [
    {
      "id": "record_id",
      "field_api_name": "updated_value"
    }
  ]
}

Example:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "data": [{
        "id": "7255024000000605002",
        "Phone": "+1-555-9999"
    }]
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/zoho-bigin/bigin/v2/Contacts', data=data, method='PUT')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "data": [
    {
      "code": "SUCCESS",
      "details": {
        "Modified_Time": "2026-02-06T00:29:07-08:00",
        "id": "7255024000000605002"
      },
      "message": "record updated",
      "status": "success"
    }
  ]
}

Delete Records

DELETE /zoho-bigin/bigin/v2/{module_api_name}?ids={record_id1},{record_id2}

Query Parameters:

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-bigin/bigin/v2/Contacts?ids=7255024000000605002', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "data": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "7255024000000605002"
      },
      "message": "record deleted",
      "status": "success"
    }
  ]
}

Search Records

GET /zoho-bigin/bigin/v2/{module_api_name}/search

Query Parameters:

Criteria Format: ((field_api_name:operator:value)and/or(...))

Operators: equals, starts_with

Example - Search by email:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-bigin/bigin/v2/Contacts/search?email=support@bigin.com')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Example - Search by criteria:

python <<'EOF'
import urllib.request, os, json
import urllib.parse
criteria = urllib.parse.quote('(Last_Name:equals:Watson)')
req = urllib.request.Request(f'https://gateway.maton.ai/zoho-bigin/bigin/v2/Contacts/search?criteria={criteria}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Metadata APIs

Get Modules

GET /zoho-bigin/bigin/v2/settings/modules

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-bigin/bigin/v2/settings/modules')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Users

GET /zoho-bigin/bigin/v2/users

Query Parameters:

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-bigin/bigin/v2/users?type=ActiveUsers')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Pagination

Zoho Bigin uses page-based pagination with page and per_page parameters:

GET /zoho-bigin/bigin/v2/{module_api_name}?fields=First_Name,Last_Name&page=1&per_page=50

Response includes pagination info:

{
  "data": [...],
  "info": {
    "per_page": 50,
    "count": 50,
    "page": 1,
    "more_records": true
  }
}

Continue fetching while more_records is true, incrementing page each time.

Code Examples

JavaScript

const response = await fetch(
  'https://gateway.maton.ai/zoho-bigin/bigin/v2/Contacts?fields=First_Name,Last_Name,Email',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const data = await response.json();

Python

import os
import requests

response = requests.get(
    'https://gateway.maton.ai/zoho-bigin/bigin/v2/Contacts',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    params={'fields': 'First_Name,Last_Name,Email'}
)
data = response.json()

Notes

• The fields parameter is required for list operations
• Module API names are case-sensitive (e.g., Contacts, not contacts)
• Companies are accessed via the Accounts module API name
• Sales opportunities are accessed via the Pipelines module (not Deals)
• Maximum 100 records per create/update request
• Maximum 100 records per delete request
• Maximum 200 records returned per GET request
• Use field API names (not display names) in requests
• Some modules (Tasks, Events, Calls, Notes) require additional OAuth scopes. If you receive a scope error, contact Maton support at support@maton.ai with the specific operations/APIs you need and your use-case
• IMPORTANT: When using curl commands, use curl -g when URLs contain brackets to disable glob parsing
• IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments

Error Handling

Common Error Codes

Troubleshooting: Invalid API Key

When you receive a "Invalid API key" error, ALWAYS follow these steps before concluding there is an issue:

1. Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

1. Verify the API key is valid by listing connections:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Resources

• Bigin API Overview
• Bigin REST API Documentation
• Modules API