> ## Documentation Index > Fetch the complete documentation index at: https://moengage.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create File Segment > This API creates a new file segment from a CSV file URL. ## OpenAPI ````yaml /api/custom-segments/custom-segments.yaml post /v2/custom-segments/file-segment openapi: 3.0.3 info: title: MoEngage Segments API description: > Use the MoEngage Segments API to create, update, and manage your file and filter segments. - **v2 API:** Manage File Segments and segment lifecycle (Archive/Unarchive). - **v3 API:** Create, read, update, and list filter-based Segments. version: '3.0' servers: - url: https://api-{dc}.moengage.com description: MoEngage API Endpoint variables: dc: description: >- The ‘dc’ in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage hosts each customer in a different DC. You can find your DC number and replace the value of ‘dc’ in the URL by referring to the DC and API endpoint mapping [here](/api/introduction#data-centers). Your MoEngage Data Center (DC) can be 01, 02, 03, 04, 05, 06, or 101. default: '01' security: - basicAuth: [] tags: - name: File Segments description: > If you need to create segments by importing a large number of users, we recommend utilising the File segment API. This API allows you to easily generate a file segment by initiating a call to the file segment API endpoint. To proceed, you will need to compile a CSV file containing the relevant users (ensuring that the users are already present in MoEngage). It is essential to provide the public path of the file, which allows for downloading and identification of users in order to successfully create the file segment. Use the File Segment API to: * Create a new file segment * Add users to an existing segment * Remove users from an existing segment * Replace users from an existing segment - name: Manage Segments description: > Archiving and unarchiving through APIs makes it easy to retrieve and reuse segments whenever required for purposes such as A/B testing, maintaining regulatory compliance, and improving system performance. You can unarchive an archived segment to reuse it in campaigns and analysis without recreating it from scratch. x-mint: content: | Archived segments will not be shown beyond 180 days. - name: Filter Segments description: > If you need to create a segment based on the events or actions performed by your users on your application or website, the recommended approach is to use the filter segment API. With this API, you can create a segment by specifying the desired filter conditions. The filter segment API supports various operations, including create, update, get, and list, allowing you to effectively manage your segments based on specific criteria. x-mint: content: > ## Authentication Authentication is performed using Basic Auth. You must also provide the `MOE-APPKEY` header. ## Request Headers | Key | Required | Description | | :--- | :--- | :--- | | `Content-Type` | Yes | Set to `application/json`. | | `Authorization` | Yes | Basic Auth. `{"Authorization": "Basic Base64_ENCODED_WORKSPACEID_APIKEY="}` | | `MOE-APPKEY` | Yes | Your MoEngage App ID. Found in Settings -> Account -> APIs -> App ID. | paths: /v2/custom-segments/file-segment: post: tags: - File Segments summary: Create File Segment description: This API creates a new file segment from a CSV file URL. operationId: createFileSegment parameters: - name: MOE-DBNAME in: header description: >- The MoEngage database name (`db_name`) from which the data is available. required: true schema: type: string requestBody: description: Configuration for the new file segment. required: true content: application/json: schema: $ref: '#/components/schemas/CreateSegmentRequestV2' example: name: custom_segment_unique_name attribute_name: unique_identifier attribute_type: string file_url: https://s3.amazonaws.com/Sample_GAIDs.csv callback_url: http://example.com/moengage-callback emails: - user1@example.com - user2@example.com expiry_time: 30 responses: '202': description: Request accepted for processing. content: application/json: schema: oneOf: - $ref: '#/components/schemas/FileSegmentAcceptedResponseV2' - $ref: '#/components/schemas/CallbackV2' examples: api_response: summary: API Response - Success description: >- Immediate response from the API when the request is accepted. value: message: File-segment creation request accepted success: true cs_name: custom_segment_unique_name cs_id: 6a1d8c3292d59351fe910b13 callback_success: summary: Callback - Success description: >- Callback sent to your callback_url when segment processing completes successfully. value: db_name: test_db segment_name: test_segment_name request_id: d5a263c4ef1198ae3d8496c0460f570f values_found: 80 values_processed: 70 user_count: 60 status: 201 '400': description: >- Bad Request. Request not accepted due to missing a required parameter. The reason is passed in the description field. content: application/json: schema: $ref: '#/components/schemas/ApiErrorV2' example: title: Invalid request description: 'expiry_time - Field is required but value is None : None' '401': $ref: '#/components/responses/401_FileSegmentError' '409': $ref: '#/components/responses/409_FileSegmentConflict' '429': $ref: '#/components/responses/429_FileSegmentRateLimit' '500': description: Server Errors. Something went wrong on MoEngage. content: application/json: schema: $ref: '#/components/schemas/ApiErrorV2' example: title: Internal Server Error callbacks: segmentCreationCallback: '{$request.body#/callback_url}': post: summary: Segment Processing Callback (v2) description: >- A webhook sent to your `callback_url` when a v2 file segment processing job is complete. requestBody: description: Result of the segment processing job. required: true content: application/json: schema: $ref: '#/components/schemas/CallbackV2' examples: success: summary: Success description: Sent when segment processing completes successfully. value: db_name: test_db segment_name: test_segment_name request_id: d5a263c4ef1198ae3d8496c0460f570f values_found: 80 values_processed: 70 user_count: 60 status: 201 file_size_failure: summary: Failure (File Size) description: Sent when the file size exceeds the limit. value: db_name: test_db segment_name: test_segment_name request_id: d5a263c4ef1198ae3d8496c0460f570f status: 400 error_message: >- File size cannot be greater than 150MB. Created custom_segment contains 0 users. download_failure: summary: Failure (Download Failed) description: Sent when the file download fails. value: db_name: test_db segment_name: test_segment_name request_id: d5a263c4ef1198ae3d8496c0460f570f status: 400 error_message: >- File download failed. Created custom_segment contains 0 users. internal_error: summary: Failure (Internal Server Error) description: >- Sent when segment processing encounters an internal error. value: db_name: test_db segment_name: test_segment_name request_id: d5a263c4ef1198ae3d8496c0460f570f status: 500 error_message: Internal Server Error. Contact MoEngage Team. responses: '200': description: >- OK. Acknowledges receipt of the callback. Your endpoint should return this. method: post type: path path: '{$request.body#/callback_url}' components: schemas: CreateSegmentRequestV2: description: Schema for creating a new file segment. allOf: - $ref: '#/components/schemas/BaseSegmentRequestV2' - type: object properties: expiry_time: type: integer format: int32 description: >- Segment expiry time in days. The segment is archived after this time. required: - expiry_time FileSegmentAcceptedResponseV2: title: API Response description: >- Response returned when a file segment request is accepted for processing. allOf: - $ref: '#/components/schemas/ApiResponseSuccessV2' - type: object properties: cs_id: type: string description: The unique identifier of the segment being processed. CallbackV2: title: Processing Callback type: object description: >- The payload sent to the callback URL. The structure depends on the processing status. properties: db_name: type: string description: The database name. example: test_db segment_name: type: string description: The name of the segment. example: test_segment_name request_id: type: string description: The unique ID of the request. example: d5a263c4ef1198ae3d8496c0460f570f status: type: integer description: >- The HTTP status code indicating the outcome (e.g., 201 for success, 400/500 for failure). example: 201 values_found: type: integer description: (Success only) Number of rows present in the uploaded file. values_processed: type: integer description: >- (Success only) Number of values processed from values_found. Values with corrupted or empty data are skipped. user_count: type: integer description: >- (Success only) Number of users found in MoEngage from the processed values and added to the segment. error_message: type: string description: (Failure only) A description of the error. ApiErrorV2: type: object properties: title: type: string description: A short title for the error. description: type: string description: A detailed, human-readable explanation of the error. BaseSegmentRequestV2: type: object properties: name: type: string description: Name of the segment. Must be unique for creation. attribute_name: type: string description: >- Name of the user attribute to use as an identifier (e.g., 'ID', 'email'). attribute_type: type: string description: The data type of the attribute_name. enum: - string - double file_url: type: string format: uri description: A public, downloadable URL to a single-column CSV file. callback_url: type: string format: uri description: Callback URL to receive the result of segment processing. emails: type: array items: type: string format: email description: List of email IDs to receive segment processing response. required: - name - attribute_name - attribute_type - file_url ApiResponseSuccessV2: type: object properties: message: type: string description: The status message of the request. success: type: boolean example: true description: Indicates if the request was accepted. cs_name: type: string description: The unique name of the segment being processed. responses: 401_FileSegmentError: description: Unauthorized. Authentication or Authorization Failure. content: application/json: schema: $ref: '#/components/schemas/ApiErrorV2' example: title: Authentication required description: >- APP_SECRET key mismatch. Please login to the dashboard to verify key 409_FileSegmentConflict: description: Conflict. File-segment creation attempt with duplicate name. content: application/json: schema: $ref: '#/components/schemas/ApiErrorV2' example: title: Resource not created description: 'Name already exists: custom_segment_unique_name' 429_FileSegmentRateLimit: description: >- Too Many Requests. The number or rate of requests exceeds the allowed limit. content: application/json: schema: $ref: '#/components/schemas/ApiErrorV2' example: title: Too Many Requests description: >- File segment operations limit breached. Please retry after some time. securitySchemes: basicAuth: type: http scheme: basic description: > Authentication is done via Basic Auth. This requires a base64-encoded string of your credentials in the format 'username:password'. - **Username**: Use your MoEngage workspace ID (also known as the App ID). You can find it in the MoEngage dashboard at **Settings** > **Account** > **APIs** > **Workspace ID (earlier app id)**. - **Password**: Use your API Key, which you can find within the **Data** tile. For more information on authentication and getting your credentials, refer [here](https://www.moengage.com/docs/api/introduction#getting-your-credentials). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.