Export segment users API
Prerequisites
To use the APIs, you need to have a token. Tokens can be generated by an admin at the setting section in Filum CX platform. Ensure you have the necessary permissions to access the admin settings for token generation.
APIs
Access the APIs via the endpoint: https://api.filum.ai/
POST /external/segments/{segment_id}/users/export
Summary
Export Users from a Segment
Limitations:
- Each export request is limited to a maximum of users defined by the system configuration.
- Users are processed in batches for optimal performance.
Path Parameters
| Name | Description | Required | Schema |
|---|---|---|---|
| segment_id | The unique identifier of the segment to export | Yes | UUID |
Query Parameters
| Name | Description | Required | Schema |
|---|---|---|---|
| custom_properties | List of custom properties to include in the export | No | [ string ] |
Examples for list-type parameters:
# Export users with custom properties 'Loyalty Points' and 'Last Purchase Date'
custom_properties=Loyalty Points&custom_properties=Last Purchase Date
Header Parameters
| Name | Description | Required | Schema |
|---|---|---|---|
| authorization | The authorization token to validate the request. The value must be in the format Bearer <your_api_token> | Yes | string |
| organization-id | The unique identifier of your organization | Yes | string |
| auth-type | The type of authorization used for the request. In this case, the value must be token | Yes | string |
| accept | The format of the exported file. Options are: text/csv, application/x-ndjson | Yes | string |
Responses
| Code | Description | Content type |
|---|---|---|
| 200 | Successful Response | text/csv; charset=utf-16le or application/x-ndjson; charset=utf-16le |
| 422 | Validation Error | application/json |
| 429 | Too Many Requests | application/json |
| 500 | Internal Server Error | application/json |
200 Successful Response
File Format Details:
- The output file will be provided in either CSV or JSON format
- The CSV file is encoded in UTF-16LE (Little Endian)
- The CSV file starts with a UTF-16LE BOM (Byte Order Mark)
- Fields in CSV format are tab-separated
- Values containing special characters are enclosed in double quotes
The output file will provide the following information:
Default columns:
- User ID
- Name
- Phone
Custom property columns (varies based on requested custom properties):
- Each custom property will have its own column with the property name as the column header
Sample columns for CSV format:
| User ID | Name | Phone | [Custom Property 1] | [Custom Property 2] | ... | |
|---|---|---|---|---|---|---|
Each row in the table will represent a unique user from the segment. The columns will contain the following information:
- User ID: The unique identifier for the user
- Name: The name of the user
- Phone: The phone number of the user
- Email: The email address of the user
- Custom Property 1: Additional custom property requested in the query parameters, with its respective value
- Custom Property 2: Additional custom property requested in the query parameters, with its respective value
- ...
Rate Limiting
The API endpoints are rate-limited to ensure fair usage and system stability. The default rate limits are:
- Per second: 5 requests
- Per minute: 50 requests
If you exceed these limits, you will receive a 429 Too Many Requests response. Please implement appropriate retry logic with exponential backoff in your integration.
Error Responses
429 Too Many Requests
{
"detail": "Rate limit exceeded"
}