Authoritative Tutorial: Query Do1QQ User API Field Reference

What Problem This API Solves

The Do1QQ "Query Users" API pulls user lists from an enterprise organization structure. Typical use cases include account linkage between CRM and collaboration platforms, organization comparison, directory synchronization, and filtering personnel by department. Across multiple customer projects integrating Xiaoman OKKICRM with Do1QQ, this API is the first stop for user master data sync and is configured as a query-only strategy.

API Capability Overview

• Endpoint: /plus/cgi-bin/open/users (Query user list)
• Authentication: Enterprise OpenAPI credentials, typically via access_token or app-level signature issued by the Do1QQ open platform
• Method: HTTP GET (POST supported in some scenarios)
• Key Request Parameters:
  • departmentId: Root department IDs, comma-separated, scopes the query
  • page: Page number, default 1
  • pageSize: Items per page, default 100
• Response: JSON array, each element is a user object (see field table below)
• Pagination: Traditional page + pageSize; incremental sync is typically done client-side using an updateTime cursor
• Rate Limiting: The open platform enforces call frequency limits; batch pulls require throttling

Typical Field Mapping

How to Configure on Qeasy Cloud

On the Qeasy Data Integration Platform, this kind of query API is usually wrapped as a "Query Adapter":

• Adapter Selection: Pick "Do1QQ / User Query" adapter, fill in app credentials and the department scope (departmentId accepts comma-separated values)
• Pagination Setup: In Qeasy Cloud's pagination panel, set pageSize to 100 (the platform's allowed maximum) to minimize request count
• Field Mapper: Qeasy Cloud's field mapper automatically normalizes id, account, name into generic concepts (user_id, user_account, user_name); extend can be expanded and read by JSONPath
• Target Side: Target is configured as "Empty Write", marking this as a query-only strategy whose result is consumed by downstream user matching or caching
• Scheduling: Combine with updateTime cursor; Qeasy Cloud's "Incremental Pull" switch helps avoid redundant full loads

Cross-Project Practical Points

1. Prefer id over account as the join key: Across multiple customer projects, account (mobile/email) carries recycling risk while id stays stable within a tenant.
2. Pass a few departmentIds, not all: Passing 1–3 core root departments is usually enough; too many slows responses and triggers rate limits.
3. Do not hard-code extend fields: Extension structure varies wildly across tenants; the safe approach is "pass-through to target, then parse on demand".
4. Incremental sync must use updateTime, not id: id is not guaranteed monotonic, so id-based incremental will miss records.
5. Mask telephone and wxUserId together: Before writing into CRM, apply masking or hashing per the customer's compliance policy.
6. Validate consistency after paging finishes: The last page is often partial; configure id-based deduplication in Qeasy Cloud's "Tail Dedup" switch to prevent boundary data loss.

Pitfall Recap

1. Empty departmentId returns everyone: Omitting departmentId entirely causes some API versions to return all users in the org, leading to data explosion. Always pass values explicitly, even if only one root department.
2. pageSize overflow silently truncates: Do1QQ caps items per response; exceeding the limit silently truncates instead of erroring, which can mislead callers into thinking the load is complete. Confirm the documented cap; Qeasy Cloud's default 100 is usually safe.
3. extend strict-typing failures: JSON parsers with strict typing reject null or array values in object fields, failing the whole batch. Declare extend as weakly typed or pass it as a string in Qeasy Cloud.
4. updateTime timezone drift: API timestamps without timezone cause duplicates or gaps across regions. Parse as UTC at the integration layer; localize at the presentation layer.
5. Missing backoff causes task interruption: High-frequency full loads easily hit rate limits. Enable "Retry + Exponential Backoff" in Qeasy Cloud and stagger schedules.

When to Use This API

Suitable for scenarios that need to pull users from Do1QQ's org structure for sync, matching, or permission mapping—especially as a foundational data source in CRM, HR, and WeCom integrated stacks. Not suitable when real-time latency under 1 minute is required, or when user changes must be written back to Do1QQ; for those cases, use the "User Change Webhook" or dedicated write APIs instead.