SOURCE_ID: import_from_zoho NAME: Import Zoho CRM Records CATEGORY: CRM Pull records of any Zoho CRM module (Leads, Contacts, Accounts, Deals, custom modules, …) into Floqer — either as a one-time import or as an ongoing source that re-pulls on a schedule. Imported records become available to your Floqer workflows for enrichment, scoring, outreach, and the like. 1. ENDPOINTS Source identifier (used in every endpoint path): `import_from_zoho`. POST /api/v1/sources/import_from_zoho/preview Scope: sources:read Returns up to 10 sample records that WOULD be imported for the given body, without creating anything, plus `metadata.total_results`: the full count of matching records in Zoho CRM. Use this to validate the module, fields, and filters before committing. POST /api/v1/sources/import_from_zoho Scope: sources:write Creates the source (pull modes: §3). Returns `source_instance_id` (the new source's UUID). POST /api/v1/sources/import_from_zoho/options/ Scope: sources:read Resolves `module` and `properties` (§6). GET /api/v1/sources//data Scope: sources:read Rows imported into the created source (`` = the UUID returned by Create). Paging: concepts.txt §10. POST /api/v1/sources//sync Scope: sources:write Connects the created source to a workflow and (by default) backfills it with the source's current rows. Body and `field_mapping`: concepts.txt §10 — the source fields are the Zoho field API names you imported. PATCH /api/v1/sources//status Scope: sources:write Pause or resume an active source. Body: {"status": "active" | "paused"}. Source-agnostic. Every endpoint for this source first verifies the API-key user has an active Zoho CRM connection. Missing connection → 424. 2. MODULE + FIELDS A Zoho CRM source selects ONE module and a set of fields on it: module required. The Zoho CRM module API name — "Leads", "Contacts", "Accounts", "Deals", or a custom module's API name. Letters, digits, and underscores only. Resolve the catalogue via the `module` dynamic option (§6). properties required, non-empty. The field API names to return on each row — e.g. ["First_Name", "Last_Name", "Email", "Company", "Lead_Status"]. Resolve the field catalogue for the chosen module via the `properties` dynamic option (§6). Field names are validated against the module; any field that doesn't exist is rejected with a 400 listing the offending names. At most 50 fields per source, counting the record `id` (always included). Dot paths into a lookup field are accepted in `properties` and skip the existence check. 3. PULL MODE (ONE-TIME VS ONGOING) `pull_mode` is required on the create endpoint (not on preview). Values (same as every CRM source): "static" One-time import. Imports matching records once (when `pull_existing`) and stops — no recurring schedule. "active" Ongoing source. Imports matching records initially (when `pull_existing`) AND, on the cadence in `schedule` (a cron string), imports matching records created or modified since the last run, continuing until `expiration_date`. `schedule` is required when `pull_mode: active`. Otherwise it's ignored. 4. BODY SHAPE (PREVIEW + CREATE) Preview accepts (all snake_case): module required (§2) properties required, non-empty (§2) filters optional: filter expression (see below + §5). Omit to pull every record of the module. properties_metadata optional: array<{name, label}> setting each cell's human label — one per field, the `value` and `label` from the `properties` option. Every cell comes back as {label, value} regardless; without metadata the label is the field's API name. max_count optional: positive integer | numeric string; preview ignores it Create accepts all the preview fields plus: name required: display name for the new source pull_mode required: "static" | "active" (§3) schedule cron string (5-field); required when pull_mode is "active", ignored otherwise expiration_date ISO date (YYYY-MM-DD); optional (active source only). Defaults to 10 years from creation. pull_existing boolean; optional, defaults to true max_count caps the initial import at N rows. Omit to import every matching record (up to the source-wide ceiling of 50,000). N MUST NOT exceed the Preview's `metadata.total_results`: set it equal to that, never a generic "safe" value like 100. Unknown top-level keys are rejected with 400 — the schema is strict. Each returned row also carries a `uid` field — the record's Zoho CRM `id`, surfaced as a plain string (not wrapped as `{label, value}`). Use it as the stable per-row identifier; it appears in both Preview and Get Source Data rows. Filter expression shape: filters: { operator?: "AND" | "OR", // combinator between groups (default AND) conditions: [ // array of GROUPS { operator?: "AND" | "OR", // joins this group to the previous one conditions: [ // array of LEAVES { variable: "", condition: "", variable_type: "", values: [, ...], operator?: "AND" | "OR" // joins this leaf to the previous one } ] } ] } - A leaf's `condition` is the comparison operator; the valid set depends on `variable_type` (§5). - A leaf's `operator` ("AND"/"OR") joins it to the PREVIOUS leaf in the same group (the first leaf's `operator` is ignored). Group `operator` works the same way between groups. - Leaves and groups combine strictly left to right: leaves [A, B, C(OR)] mean (A AND B) OR C. For A AND (B OR C), put A in one group and B, C(OR) in the next. - `values` is always an array. Single-value operators read `values[0]`; `is between` reads `values[0]` (low) and `values[1]` (high). - At most 25 leaves per source, across all groups. Example (open leads from the web): { "module": "Leads", "properties": ["First_Name", "Last_Name", "Email", "Company", "Lead_Status"], "filters": { "conditions": [ { "conditions": [ { "variable": "Lead_Source", "condition": "is", "variable_type": "picklist", "values": ["Web Download"] }, { "variable": "Email", "condition": "is not empty", "variable_type": "email", "values": [], "operator": "AND" } ]} ] } } 5. FILTER OPERATORS BY FIELD TYPE `condition` is interpreted according to the leaf's `variable_type`. Send the field's `extras.type` from the `properties` option (§6) as `variable_type`. Before filtering: ⚠ Conditions on multi-select picklist (`multiselectpicklist`) and lookup (`lookup`, `userlookup`, `ownerlookup`) fields are ignored — they match every record. Filter on another field instead. ⚠ For number, date, boolean, and picklist types, a `condition` not listed below is ignored (matches every record). ──────────────────────────────────────────────────────────────────── variable_type: text, textarea, email, phone, website, url ──────────────────────────────────────────────────────────────────── is / equals field = value (multiple values → any of them) is not field != value (multiple values → none of them) contains field contains value (any of the values) does not contain field contains none of the values starts with field starts with value ends with field ends with value does not start with field starts with none of the values does not end with field ends with none of the values is empty / is not empty ──────────────────────────────────────────────────────────────────── variable_type: integer, double, bigint, currency, percent ──────────────────────────────────────────────────────────────────── is / equals field = value is not field != value greater than field > value less than field < value greater than or equal to field >= value less than or equal to field <= value is between values[0] <= field <= values[1] is empty / is not empty ──────────────────────────────────────────────────────────────────── variable_type: date / datetime ──────────────────────────────────────────────────────────────────── is field = is not field != is after field > is before field < is between between values[0] and values[1] is empty / is not empty For `date` send "YYYY-MM-DD"; for `datetime` send an ISO timestamp (compared in UTC). ──────────────────────────────────────────────────────────────────── variable_type: boolean ──────────────────────────────────────────────────────────────────── is / equals field = value (value: true | false) is not field != value is empty / is not empty ──────────────────────────────────────────────────────────────────── variable_type: picklist ──────────────────────────────────────────────────────────────────── is / equals field = value (multiple values → any of them) is not field != values[0] contains field contains values[0] is empty / is not empty Valid picklist values are in the field's `extras.picklistValues[].value` from the `properties` option. Any other `variable_type` behaves like `text` for is, is not, contains, does not contain, starts with, ends with, and is empty / is not empty. 6. DYNAMIC OPTIONS (MANDATORY PRE-CALLS) Two dynamic-options field names are available for this source. Both are POSTs to /api/v1/sources/import_from_zoho/options/ with body `{ "context"?: {...} }`. module Context: none. Returns: {value: , label: , extras: {...}} Use the returned `value` directly as the source body's `module`. properties Context: { "module": "" } — REQUIRED. Returns: {value: , label: , extras: } `value` and `label` feed `properties` and `properties_metadata` (§4); `extras.type` is the field's `variable_type` (§5) and `extras.picklistValues` lists picklist values. 7. HOW TO CONFIGURE END-TO-END Step 1 — Pick the module POST /api/v1/sources/import_from_zoho/options/module Body: {} Choose the module's `.value` (e.g. "Leads"). Step 2 — Resolve the field catalogue for that module POST /api/v1/sources/import_from_zoho/options/properties Body: {"context": {"module": "Leads"}} Pick a subset of `.value`s as `properties`. Step 3 — Preview before committing POST /api/v1/sources/import_from_zoho/preview Body: as §4 (see its example). Check the returned `data[]` and `metadata.total_results`. Iterate until happy. Step 4 — Create the source POST /api/v1/sources/import_from_zoho Body: the Step 3 body + the create-only fields (§4), e.g. "name": "Web Leads", "pull_mode": "static", "max_count": Response: { "status": 201, "data": { "source_instance_id": "", "name", "created_at" }} Step 4b — (Optional) Poll imported rows while the import runs GET /api/v1/sources//data?page_no=1&page_size=20 Step 5 — Sync the source into a workflow (so its records flow downstream) POST /api/v1/sources//sync Body: { "workflow_id": "", "field_mapping": { "input.email": "Email", "input.company": "Company" } } Building `field_mapping`, the optional `push_existing`, and whether rows run on arrival: concepts.txt §10. 8. KEY NOTES - Zoho CRM connection is mandatory. Every endpoint checks the API-key user's connection first; without one it returns 424 ("User is not connected to 'zohoCRM'."). Surface this as a "connect Zoho CRM first" CTA. - Errors: unknown fields on the module, more than 50 fields, or more than 25 filter leaves → 400 with a message naming the problem. - Credits are consumed when the source is created and matching records exist. If credit consumption fails (e.g. insufficient balance), the source is still created but its import can't start; the API returns 402 so you can top up and retry. A filter that matches nothing creates an empty source and consumes no credits. 9. WHEN TO USE - One-time import of a filtered set of Zoho CRM records for enrichment / outreach: `pull_mode: static` with a `filters` expression. - Keep a Zoho CRM segment (e.g. "Leads with status Not Contacted") in sync with a Floqer workflow on a schedule: `pull_mode: active`, `schedule: "0 12 * * *"`. - Pull an entire module (no `filters`) as a one-time snapshot, capped with `max_count`. When you instead want to push data OUT of Floqer INTO Zoho CRM, use the Zoho CRM action templates inside a workflow — see the action catalog in action-catalog.txt. Last updated: 2026-10-27. Reference: https://floqer.com/docs/reference