zohobigin

# Zoho Bigin Access the Zoho Bigin API with managed OAuth authentication. Manage contacts, companies, pipelines, and products with full CRUD operations. ## Quick Start ```bash # 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`: ```bash export MATON_API_KEY="YOUR_API_KEY" ``` ### Getting Your API Key 1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://maton.ai/settings) 3. Copy your API key ## Connection Management Manage your Zoho Bigin OAuth connections at `https://ctrl.maton.ai`. ### List Connections ```bash 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 ```bash 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 ```bash 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:** ```json { "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 ```bash 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: ```bash 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: | Module | API Name | Description | |--------|----------|-------------| | Contacts | `Contacts` | Individual people | | Companies | `Accounts` | Organizations/businesses | | Pipelines | `Pipelines` | Sales opportunities/deals | | Products | `Products` | Items you sell | | Tasks | `Tasks` | To-do items (requires additional OAuth scope) | | Events | `Events` | Calendar appointments (requires additional OAuth scope) | | Calls | `Calls` | Phone call logs (requires additional OAuth scope) | | Notes | `Notes` | Notes attached to records (requires additional OAuth scope) | ### List Records ```bash GET /zoho-bigin/bigin/v2/{module_api_name}?fields={field1},{field2} ``` **Query Parameters:** | Parameter | Type | Description | |-----------|------|-------------| | `fields` | string | **Required.** Comma-separated field API names to retrieve | | `sort_order` | string | `asc` or `desc` | | `sort_by` | string | Field API name to sort by | | `page` | integer | Page number (default: 1) | | `per_page` | integer | Records per page (default: 200, max: 200) | | `cvid` | string | Custom view ID for filtered results | **Example - List Contacts:** ```bash 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:** ```json { "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):** ```bash 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 ```bash GET /zoho-bigin/bigin/v2/{module_api_name}/{record_id} ``` **Example:** ```bash 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 ```bash POST /zoho-bigin/bigin/v2/{module_api_name} Content-Type: application/json { "data": [ { "field_api_name": "value" } ] } ``` **Mandatory Fields by Module:** | Module | Required Fields | |--------|-----------------| | Contacts | `Last_Name` | | Accounts | `Account_Name` | | Pipelines | `Pipeline_Name`, `Stage` | | Products | `Product_Name` | **Example - Create Contact:** ```bash 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:** ```json { "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):** ```bash 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 ```bash PUT /zoho-bigin/bigin/v2/{module_api_name} Content-Type: application/json { "data": [ {