Skip to main content
Third-party Integration

API synchronization

API synchronization enables enterprises to synchronize user and organizational structure data by integrating with their own user data API.
Applicable editiondedicated edition

Creating users outside the synchronization scope

Enterprise administrators can configure and manage API synchronization in enterprise management > third-party integration. Ensure that your API adheres to the specifications in this document. Qoder CN synchronizes your enterprise's organizational structure and users based on the configured URL. You can select the Support built-in users, and allow creating users outside the synchronization scope option.

Configure API synchronization

Step 1: Configure the data request URL

Enter the URL for your API endpoint, which supports HTTP and HTTPS requests. Ensure the URL is correct and reachable. After the connectivity check passes, click Next.
  1. The request endpoint supports only GET requests over HTTP and HTTPS.
  2. API authentication is not configured separately. You must include any required authentication parameters directly in the URL.
  3. To support pagination, include the first-page parameters in the URL to ensure complete data retrieval. For example: https://xxxxxx?page_number=0&page_size=10, where page_number is the page number and page_size is the number of users per page.

API response data

Structure your API response as follows: The departments array must contain data for all departments associated with the users in the users list. If you use pagination, paginate based on the number of users and ensure that any parent department is returned before its child departments.

Parameter

Type

Required

Description

User fields

user_id

string

Yes

A globally unique identifier for the user.

name

string

Yes

The user's full name.

user_name

string

Yes

A globally unique login name for the user.

nick_name

string

No

The user's nickname.

staff_id

string

No

A globally unique staff ID.

email

string

Yes

A globally unique email address.

status

string

No

The user's status. If the status is leave, the system deletes the user from Qoder CN.

department_ids

array

Yes

An array of department IDs that the user belongs to.

Department fields

department_id

string

Yes

A unique identifier for the department.

name

string

Yes

The department name.

parent_id

string

Yes

The unique identifier of the parent department, used to build the organizational structure.

Pagination fields

next_page_number

int

No

If pagination is used, set this to -1 in the response for the last page to indicate that it is the last page.
Example response: 
{
  "users": [
    {
      "user_id": "yx12346xxx",
      "name": "Zhou X",
      "user_name": "zhouxxx",
      "nick_name": "X Wai",
      "staff_id": "004xx5",
      "email": "zhouxxx@example.com",
      "department_ids": [
        "16xxx2"
      ]
    }
  ],
  "departments": [
    {
      "department_id": "009xxx",
      "name": "Dept-XXX-Group-XXX-Unit-XXX",
      "parent_id": "19xxx5"
    }
  ],
  "next_page_number": 1
}

Step 2: Configure account binding and field mapping

Four account binding methods are available:
  • Automatically bind accounts with the same email: Binds Qoder CN accounts to upstream accounts that have the same email address.
  • Automatically bind accounts with the same login name: Binds Qoder CN accounts to upstream accounts that have the same login name.
  • Automatically bind accounts with the same mobile number: Binds Qoder CN accounts to upstream accounts that have the same mobile number.
  • Automatically bind accounts with the same staff ID: Binds Qoder CN accounts to upstream accounts that have the same staff ID.
Regardless of the account identification and binding method you choose, you must ensure that the corresponding attribute field is unique and exists. This is because Qoder CN performs one-to-one account matching based on the selected method. The binding process for the Automatically bind accounts with the same login name option is as follows: Qoder CN automatically synchronizes corporate user information with user information in Qoder CN based on the field mapping shown in the figure below and the synchronization policy. You cannot modify the field mapping at this time. After you confirm the mapping, click Next. The field mapping is as follows: Name maps to name, Login Name maps to user_name, Email maps to email, Mobile maps to phone_number, Department maps to department_ids, Staff ID maps to staff_id, and Nickname maps to nick_name. After you configure and confirm the settings, click Next.

Step 3: Enable user and organization synchronization

If no other third-party user and organizational synchronization is enabled in Qoder CN, you can enable this feature. You can configure the synchronization schedule and rules for user and organizational discrepancy handling.
  • Synchronization schedule: Defaults to manual synchronization. You can switch between manual and scheduled synchronization:
    • Manual synchronization: An administrator initiates a sync by clicking the Run manual sync button on the API synchronization integration details page after data changes.
Tip: Wait at least one hour between manual synchronization operations.
  • Scheduled synchronization: Configure the schedule to sync daily (at a specific time), weekly (on a specific day and time), monthly (on a specific day and time), or at a set interval. If you set up a scheduled synchronization, we recommend running one manual synchronization after saving the configuration to ensure data is immediately synchronized to Qoder CN.
  • User discrepancy handling: By default, extra accounts in Qoder CN are ignored, and new Qoder CN accounts are created and bound to upstream accounts within the synchronization scope. You can modify these rules based on your requirements:
    • Existing Qoder CN account not matched with an upstream account - Ignore: If an existing Qoder CN account does not match an upstream account, the extra account in Qoder CN is not deleted.
    • Existing Qoder CN account not matched with an upstream account - Delete Qoder CN account: If an existing Qoder CN account does not match an upstream account, the account is deleted from Qoder CN.
    • Existing upstream account not matched to a Qoder CN account - Ignore: If an existing upstream account does not have a matching Qoder CN account, a new account is not created in Qoder CN.
    • Existing upstream account not matched to a Qoder CN account - Create a new Qoder CN account and bind: If an existing upstream account does not match a Qoder CN account, a new account is created in Qoder CN and bound to it, following the account binding and field mapping rules.
  • Organizational discrepancy handling: By default, extra department nodes in Qoder CN are ignored, and Qoder CN departments are created and bound to upstream department nodes that are within the synchronization scope. You can modify this behavior as needed:
    • Existing Qoder CN department not matched to an upstream department - Ignore: If an existing Qoder CN department does not match an upstream department, the department node in Qoder CN is not deleted.
    • Existing Qoder CN department not matched to an upstream department - Delete Qoder CN department: If an existing Qoder CN department does not match an upstream department, the department node in Qoder CN is deleted.
    • Existing upstream department not matched to a Qoder CN department - Ignore: If an existing upstream department does not match a Qoder CN department, a new department node is not created in Qoder CN.
    • Existing upstream department not matched to a Qoder CN department - Create Qoder CN department and bind: When an existing upstream department does not match a Qoder CN department, a new department node is created in Qoder CN and bound to the upstream department node.
If you save the API synchronization integration configuration without enabling user and organizational synchronization, you can enable it later from the integration details page. On the API synchronization integration details page, the Configuration Information section displays the data request endpoint URL and the account binding method, which defaults to Automatically bind accounts with the same email. After you have configured all settings, click the Save configuration button to complete the API synchronization setup.

View user and organization synchronization results

When user and organizational synchronization is enabled, open the API synchronization integration details page to view the latest synchronization status: Not yet executed, Successful, Failed, or Partially successful.

Disable user and organization synchronization

On the API synchronization integration details page, if user and organizational synchronization is enabled, you can click Modify service configuration. In the configuration drawer that opens, you can disable user and organizational synchronization. When disabled:
  • The binding between Qoder CN accounts and upstream accounts is not removed.
  • User and organizational synchronization from the upstream system no longer runs.

Remove the API synchronization integration

On the API synchronization integration details page, you can click the Remove integration button. After you confirm, the integration is removed. After removal:
  • The binding between Qoder CN accounts and upstream accounts is removed.
  • Previously synchronized users and organizational structures are not affected.
Overview
Guides
Tutorials
  • Coding with Qoder CN
Support
Developer Reference