Skip to main content

Feishu Data Source

The Feishu connector enables you to ingest data from Feishu's enterprise collaboration platform — including Bitable (multi-dimensional spreadsheets), messaging, contacts, documents, Drive file statistics, and approval workflows. Follow the instructions below to create a new data flow that ingests data from a Feishu source in Nexla.
feishu_api.png

Feishu

Create a New Data Flow​

  1. To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Then, select the desired flow type from the list, and click the Create button.

  2. Select the Feishu connector tile from the list of available connectors. Then, select the credential that will be used to connect to the Feishu instance, and click Next; or, create a new Feishu credential for use in this flow.

  3. In Nexla, Feishu data sources can be created using pre-built endpoint templates, which expedite source setup for common Feishu endpoints. Each template is designed specifically for the corresponding Feishu API endpoint, making source configuration easy and efficient.
    • To configure this source using a template, follow the instructions in Configure Using a Template.

    Feishu sources can also be configured manually, allowing you to ingest data from Feishu endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
    • To configure this source manually, follow the instructions in Configure Manually.

Configure Using a Template​

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Feishu endpoints. Each template is designed specifically for the corresponding Feishu API endpoint, making data source setup easy and efficient.

Endpoint Settings​

  • Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.

Search Bitable Records

Searches and lists records in a Feishu Bitable table using the POST /records/search API. This endpoint replaces the deprecated GET /records endpoint and supports filtering, sorting, field selection, and view scoping. It returns up to 500 records per page using cursor-based pagination. Use this endpoint to extract structured data from any Bitable (multi-dimensional spreadsheet) table for analytics, reporting, or downstream processing.

  • Enter the App Token that identifies the Bitable application. The app token is the unique identifier for the Base (multi-dimensional table) application and can be found in the URL when viewing the Bitable in your browser — it appears after /base/ in the URL (for example, bascnxxxxxxxxxxxxxxxxxx). This field is required.

  • Enter the Table ID of the specific table within the Bitable application. The table ID identifies which sheet or table within the Base to query. It appears in the URL after the app token when a table is selected, or you can retrieve it using the Feishu API. This field is required.

  • Optionally, enter a View ID to scope the search to a specific view within the table. Views in Bitable are saved filter/sort configurations. Leave blank to search across all records regardless of view. The view ID can be found in the URL when a specific view is selected in the Bitable UI.

  • Optionally, enter a Field Names (JSON array) value to limit the fields (columns) returned. Enter a JSON array of field names to return — for example, ["Name","Status","Due Date"]. Use an empty array [] to return all fields.

  • Optionally, enter a Filter (JSON object) to narrow results to records that match specific conditions. Enter a JSON filter object using Bitable filter syntax — for example:

    • {"conjunction":"and","conditions":[{"field_name":"Status","operator":"is","value":["Done"]}]} returns only records where the Status field equals "Done".
    • Use an empty object for no filtering.
    • Additional details on filter syntax are available in the Feishu Bitable search documentation.

  • Optionally, enter a Sort (JSON array) to specify the sort order for returned records. Enter a JSON array of sort objects — for example, [{"field_name":"Created","desc":true}] sorts records by the Created field in descending order. Use an empty array [] for no sorting.

  • Optionally, select a User ID Type to control how user identifiers appear in person-type fields. Options are:

    • open_id (default) — A user ID that is unique to this app. Recommended for most integrations.
    • union_id — A user ID that is consistent across all apps within the same vendor account.
    • user_id — The enterprise-assigned user ID. Requires the contact:user.employee_id:readonly scope.

This endpoint uses cursor-based pagination and fetches up to 500 records per page. Nexla handles pagination automatically. For very large tables, consider using filters or view IDs to limit the result set and improve performance.

List Bitable Fields

Returns all field (column) definitions for a Bitable table, including field names, types, and configuration. Use this endpoint to discover the schema of a Bitable table before building a data source, or to track schema changes over time.

  • Enter the App Token that identifies the Bitable application. This is the same token used in the Search Bitable Records endpoint — found in the URL after /base/ when viewing the Bitable in your browser. This field is required.

  • Enter the Table ID of the table whose fields you want to list. This field is required.

This endpoint returns up to 100 fields per page with cursor-based pagination. Nexla handles pagination automatically. The response includes each field's name, type, property configuration, and whether it is a primary field.

List Approval Instances

Retrieves a batch of approval instance codes for a specific approval workflow, sorted by creation time. Use this endpoint to extract approval workflow data — such as submitted requests, their statuses, and associated metadata — for reporting or downstream processing.

  • Enter the Approval Code that identifies the approval definition (workflow) to query. The approval code is a unique string that identifies a specific approval process in Feishu. You can find it in the Feishu Admin Console under the approval management section, or via the Feishu Approval API. This field is required.

  • Enter the Start Time (ms epoch) as the lower bound of the time window in milliseconds since Unix epoch. This field is required. The total window between start and end time must be no more than 10 hours.

  • Enter the End Time (ms epoch) as the upper bound of the time window in milliseconds since Unix epoch. This field is required. The total window between start and end time must be no more than 10 hours.

  • Optionally, enter a User ID to filter results to instances submitted by a specific user. When provided, only approval instances initiated by that user within the time window are returned.

This endpoint returns approval instance codes (not full instance details). To retrieve detailed information for a specific approval instance, use the Feishu Approval API's "Get Approval Instance" endpoint with each returned instance code. The time window is strictly limited to 10 hours per request; use incremental scheduling in Nexla to cover longer time periods.

Get User

Retrieves the full profile of a single Feishu/Lark user by their user ID, including name, department membership, email, mobile number, and account status. Use this endpoint to look up individual user records for directory synchronization, user provisioning, or access management workflows.

  • Enter the User ID of the user to retrieve. The format of this ID depends on the User ID Type selected below. This field is required.

  • Select the User ID Type that corresponds to the User ID value you provided:

    • open_id (default) — The app-specific user ID (begins with ou_).
    • union_id — The cross-app user ID consistent across all apps in the same vendor account.
    • user_id — The enterprise-assigned employee ID.

  • Select the Department ID Type to control how department IDs appear in the returned user profile:

    • open_department_id (default) — The app-specific department ID.
    • department_id — The enterprise-assigned department ID.

This endpoint returns a single user record (not a paginated list). To retrieve users across a department, use the List Users by Department endpoint instead. The response includes the user's name, departments, email, mobile, job title, status, and other profile fields.

List Users by Department

Lists all users who are direct members of a specified department, with cursor-based pagination. Use this endpoint for HR data exports, organizational directory synchronization, or when you need a complete roster of users in a specific department.

  • Enter the Department ID of the department whose direct members will be listed. This field is required. The format of the ID depends on the Department ID Type selected below. The root department can be queried using 0 as the department ID.

  • Select the User ID Type to control how user identifiers appear in the response:

    • open_id (default) — The app-specific user ID.
    • union_id — The cross-app user ID.
    • user_id — The enterprise-assigned employee ID.

  • Select the Department ID Type that matches the format of the Department ID you entered:

    • open_department_id (default) — The app-specific department ID.
    • department_id — The enterprise-assigned department ID.

This endpoint lists only direct members of the specified department — it does not include members of sub-departments. Nexla handles cursor-based pagination automatically, returning up to 50 users per page. To list users in sub-departments, issue separate requests for each sub-department's ID.

Get Message

Retrieves the content and metadata of a single Feishu message by its message ID. Use this endpoint to fetch specific messages for archival, compliance logging, or content analysis workflows.

  • Enter the Message ID of the message to retrieve. Message IDs in Feishu begin with om_ and can be obtained from Feishu message event webhooks, the List Chat Messages endpoint, or the Feishu IM API. This field is required.

The response includes the message body, sender information, creation timestamp, and message type. Rich message types (cards, files, images) include additional nested content fields. For listing multiple messages in a chat, use the List Chat Messages endpoint instead.

List Chat Messages

Lists messages in a Feishu group chat within an optional time range, using cursor-based pagination. Use this endpoint to export conversation history for archival, compliance, sentiment analysis, or business intelligence purposes.

  • Enter the Chat ID of the group chat whose messages will be listed. Chat IDs in Feishu begin with oc_ and can be found in the chat URL or via the Feishu IM API's list chats endpoint. This field is required.

  • Optionally, enter a Start Time (seconds epoch) to filter messages created at or after this timestamp. Enter a Unix timestamp in seconds (not milliseconds). Leave blank to retrieve messages from the beginning of the chat history.

  • Optionally, enter an End Time (seconds epoch) to filter messages created at or before this timestamp. Enter a Unix timestamp in seconds. Leave blank to retrieve messages up to the current time.

  • Select the Sort Type for the returned messages:

    • ByCreateTimeDesc (default) — Most recent messages are returned first.
    • ByCreateTimeAsc — Oldest messages are returned first. This is recommended for incremental exports where you want to process messages in chronological order.

This endpoint returns up to 50 messages per page using cursor-based pagination; Nexla handles pagination automatically. The bot (custom app) must be a member of the target chat to access its messages. If the app is not a chat member, the API returns an authorization error.

Get Document

Retrieves the metadata of a Feishu Docx document, including its title, current revision number, and owner information. Use this endpoint to track document inventory, monitor revisions, or build document management workflows.

  • Enter the Document ID of the Docx document to retrieve. The document ID can be found in the document's URL when it is open in the Feishu client — it appears as the last path segment before any query parameters (for example, doxcnxxxxxxxxxxxxxxxxxx). This field is required.

This endpoint returns document metadata only — it does not return the document's content or body text. To read document content, use the Feishu Docs API's block-level endpoints. The custom app must have the document shared with it or have the appropriate Drive permission scope to access the document.

Get Drive File Statistics

Retrieves view counts, comment counts, and other usage statistics for a file stored in Feishu Drive, identified by its file token. Use this endpoint to track document engagement, measure content popularity, or build content analytics dashboards.

  • Enter the File Token of the Drive file whose statistics you want to retrieve. The file token is a unique identifier for any file in Feishu Drive and can be found in the file's sharing URL or via the Feishu Drive API's file list endpoints. This field is required.

The response includes view count, comment count, and like count (where available). Statistics are aggregated and may not reflect real-time counts. The custom app must have at least read access to the file in Drive to retrieve its statistics.

Endpoint Testing​

Once the selected endpoint template has been configured, Nexla can retrieve a sample of the data that will be fetched according to the current settings. This allows users to verify that the source is configured correctly before saving.

  • To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

  • If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Configure Manually​

Feishu data sources can be manually configured to ingest data from any valid Feishu Open Platform API endpoint. Manual configuration provides maximum flexibility for accessing endpoints not covered by pre-built templates or when you need custom API configurations.

With manual configuration, you can also create more complex Feishu sources, such as sources that use chained API calls to fetch data from multiple endpoints or sources that require custom request parameters.

API Method​

  1. To manually configure this source, select the Advanced tab at the top of the configuration screen.

  2. Select the API method that will be used for calls to the Feishu API from the Method pulldown menu. The most common methods are:

    • GET: For retrieving data from the API (contacts, documents, Drive statistics, messages)
    • POST: For search and filter operations (Bitable record search, approval instance listing)

API Endpoint URL​

  1. Enter the URL of the Feishu API endpoint from which this source will fetch data in the Set API URL field. All Feishu Open Platform endpoints use the following base URL pattern:

    • China (Feishu): https://open.feishu.cn/open-apis/{service}/{version}/{resource}
    • International (Lark): https://open.larksuite.com/open-apis/{service}/{version}/{resource}

    For example, to list all Bitable tables in a Base app, the URL would be: https://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/tables

The complete Feishu server API reference is available at open.feishu.cn/document/server-docs/api-call-guide/server-api-list. Each API page includes the full endpoint URL, required parameters, and example responses.

Date/Time Macros (API URL)​

Optional

Optionally, the API URL can be customized using macros—all macros added to the API URL will be converted into values when Nexla executes the API call. Macros are dynamic placeholders that allow you to create flexible API endpoints that can adapt to different time periods or data requirements.

Date/time macros are particularly useful for Feishu APIs that accept timestamp parameters, such as the Approval Instances endpoint (which requires start_time and end_time in milliseconds epoch) or the List Chat Messages endpoint (which accepts start_time and end_time in seconds epoch).

  1. To add a macro, type { at the appropriate position in the API URL (within the Set API URL field), and select the desired macro from the dropdown list.

    • {now} – The current datetime
    • {now-1} – The datetime one time unit before the current datetime
    • {now+1} – The datetime one time unit after the current datetime
    • custom – Datetime macros can reference any number of time units before or after the current datetime—for example, enter (now-4) to indicate the datetime four time units before the current datetime

  2. Select the format that will be applied to datetime macros from the Date Format for Date/Time Macro pulldown menu. This format will be applied to the base datetime value of the macro—i.e., the value of {now} in {now-1}.

  3. Select the datetime unit that will be used to perform mathematical operations in the included macro(s) from the Time Unit for Operations pulldown menu—for example, for the macro {now-1}, when Day is selected, {now-1} will be converted to the datetime one day before the current datetime.

Lookup-Based Macros (API URL)​

Optional

Column values from existing lookups can also be included as macros in the API URL. Lookup-based macros allow you to reference data from previously configured data sources or lookups, enabling dynamic API endpoints that can adapt based on existing data.

Lookup-based macros are useful when, for example, you have a Nexla source that produces a list of Bitable app tokens or chat IDs, and you want to use those values to drive further API calls to Feishu dynamically.

  1. To include a lookup column value macro, select the relevant lookup from the Add Lookups to Supported Macros pulldown menu.

  2. Type { at the appropriate position in the API URL, and select the lookup column-based macro from the dropdown list. Lookup-based macros are automatically populated into the macro list when a lookup is selected in the Add Lookups to Supported Macros pulldown menu.

Path to Data​

Optional

If only a subset of the data returned by the Feishu API endpoint is needed, you can designate the part of the response that should be included in the Nexset(s) produced from this source by specifying the path to the relevant data within the response.

For example, most Feishu list endpoints wrap their results in a data.items array alongside pagination metadata. By specifying $.data.items[*] as the path to data, Nexla treats each element of the items array as an individual record.

Path to Data is essential when working with Feishu API responses, which consistently use a nested data wrapper object. Common paths include $.data.items[*] for list endpoints, $.data.records[*] for some Bitable endpoints, and $.data.user for single-user responses.

  • To specify which data should be treated as relevant in responses from this source, enter the path to the relevant data in the Set Path to Data in Response field.

    • For responses in JSON format (all Feishu API responses), enter the JSON path that points to the object or array that should be treated as relevant data. JSON paths use dot notation (e.g., $.data.items[*] to access an array of items within a data object).
    Path to Data Example:

    For the Feishu List Users by Department endpoint, the response wraps users in $.data.items[*]. For the Get User endpoint, the single user object is at $.data.user. Consult the relevant Feishu API documentation page for the exact response structure of each endpoint.

Autogenerate Path Suggestions​

Nexla can also autogenerate data path suggestions based on the response from the API endpoint. These suggested paths can be used as-is or modified to exactly suit your needs.

  • To use this feature, click the Test button next to the Set API URL field to fetch a sample response from the API endpoint. Suggested data paths generated based on the content & format of the response will be displayed in the Suggestions box below the Set Path to Data in Response field.

  • Click on a suggestion to automatically populate the Set Path to Data in Response field with the corresponding path. The populated path can be modified directly within the field if further customization is needed.

Metadata​

If metadata is included in the response but is located outside of the defined path to relevant data, you can configure Nexla to include this data as common metadata in each record.

For example, Feishu list API responses include a top-level data.page_token and data.has_more field alongside the data.items array. If you want to preserve the page context alongside each record, you can specify a metadata path to capture these fields.

Metadata paths are particularly useful for preserving Feishu API response context such as the total record count, page tokens, or request-level timestamps that apply to all records in the response.

  • To specify the location of metadata that should be included with each record, enter the path to the relevant metadata in the Path to Metadata in Response field.

    • For responses in JSON format, enter the JSON path to the object or array that contains the metadata.

Request Headers​

Optional

  • If Nexla should include any additional request headers in API calls to this source, enter the headers & corresponding values as comma-separated pairs in the Request Headers field (e.g., header1:value1,header2:value2). Additional headers may be required for specific Feishu APIs, such as user identity type headers.

    You do not need to include the Authorization header — Nexla automatically adds the Authorization: Bearer {tenant_access_token} header using the credentials configured for this connector.

Endpoint Testing​

After configuring all settings for the selected endpoint, Nexla can retrieve a sample of the data that will be fetched according to the current configuration. This allows users to verify that the source is configured correctly before saving.

  • To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

  • If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Save & Activate the Source​

  1. Once all of the relevant steps in the above sections have been completed, click the Create button in the upper right corner of the screen to save and create the new Feishu data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.