MoEngage File Segments API

openapi: 3.2.0
info:
  title: MoEngage Segments File 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

    '
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: Content-Type
        in: header
        description: Select the file content type.
        required: true
        schema:
          type: string
          default: text/csv
          enum:
          - text/csv
          - application/csv
          - application/vnd.ms-excel
          - text/plain
          - application/octet-stream
          - binary/octet-stream
      - name: Database
        in: header
        description: Set the database from which the data is available (MOE-DBNAME).
        required: false
        schema:
          type: string
      x-mint:
        content: "<Note>\n- If your file is private, you should whitelist [these IPs](/user-guide/settings/account/security/ip-whitelisting-in-moengage) to provide access only to MoEngage for the file.\n- This API endpoint does not currently support Team-level scoping. All segments generated using this call will be assigned to the Default Team automatically.\n</Note>\n\n\n#### Rate Limits\n\n| Rate Limit Name | Rate Limit |\n| :--- | :--- |\n| total active segment | The limit of the total number of active segments at a time for a client is 1000. |\n| file_segment ops per hour | The total number of file segment operations (create/add/remove) per hour per client allowed is 10. |\n| file_segment ops per day | The total number of file segment operations (create/add/remove) per day per client allowed is 100. |\n| file_segment users per day | The total number of users uploaded via the File segment is limited to 2 million per day. (This limit is customizable, contact the MoEngage Support team). |\n| file_size_limit | The size of the file from which the segment is created/updated. For each request, the file size limit is 150 MB. |\n\n <Note>\n  **Notes**\n  * Breaching the limits will reject the request.\n  * Per hour and per day limits will consider the calculation based on the last hour and last 24 hrs respectively.\n  * The limit of 1000 active segments is calculated across all types of 'active segments'. Most of our customers utilise only 30-40% of this limit at any given point.\n  </Note>\n \n  #### CSV File Requirements\n   * The attribute names should be separated by new lines.\n   * CSV should be a single column and less than 150MB.\n   * Values should not end with a comma (e.g., `abcd` not `abcd,`).\n   * Values should not have duplicates or special characters (e.g., `abcd` not `\"abcd\"` or `a#bc`).\n   * File should not have empty rows or columns.\n   * A user attribute value must uniquely identify a single user.\n   * [Sample File Link](https://app-cdn.moengage.com/assets/Sample_GAIDs.csv)\n\n  #### Segment Processing and Availability\n\n   As soon as the request is received at the MoEngage system, MoEngage creates a segment with zero users. After this, the file is downloaded, processed, and users are added to the segment. If the segment is queried during processing, it will show zero or partial user count.\n\n   There is no fixed processing timeout. If the initial file download fails, MoEngage automatically retries before reporting a failure via the callback.\n\n  #### Callback Payload\n\n  When file processing completes, MoEngage sends a `POST` request to your `callback_url`. Your server must return an HTTP `200` to acknowledge receipt.\n\n  The payload structure depends on the processing outcome.\n\n  **Success (status: 201)**\n\n  | Field | Type | Description |\n  | :--- | :--- | :--- |\n  | `db_name` | string | The MoEngage database name for your workspace. |\n  | `segment_name` | string | The name of the processed segment. |\n  | `request_id` | string | Unique identifier for this processing request. |\n  | `status` | integer | `201` on successful processing. |\n  | `values_found` | integer | Number of rows present in the uploaded file. |\n  | `values_processed` | integer | Number of values processed from `values_found`. Values with corrupted or empty data are skipped. |\n  | `user_count` | integer | Number of users found in MoEngage from the processed values and added to the segment. |\n\n  **Failure (status: 400 or 500)**\n\n  | Field | Type | Description |\n  | :--- | :--- | :--- |\n  | `db_name` | string | The MoEngage database name for your workspace. |\n  | `segment_name` | string | The name of the segment for which processing failed. |\n  | `request_id` | string | Unique identifier for this processing request. |\n  | `status` | integer | `400` for client errors (for example, file too large, download failed), `500` for server errors. |\n  | `error_message` | string | Description of what caused the processing to fail. |\n"
      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:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              example: No example response body available for this status code.
        '202':
          description: Request accepted for processing.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ApiResponseSuccessV2'
                - $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:
                oneOf:
                - $ref: '#/components/schemas/ApiErrorV2'
                - $ref: '#/components/schemas/CallbackV2'
              examples:
                api_invalid_request:
                  summary: API Response - Invalid Request
                  description: Immediate response from the API when the request is invalid.
                  value:
                    title: Invalid Request
                    description: <message>
                callback_file_size:
                  summary: Callback - Failure (File Size)
                  description: Callback sent to your callback_url when 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.
                callback_download_failed:
                  summary: Callback - Failure (Download Failed)
                  description: Callback sent to your callback_url when 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.
        '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:
                oneOf:
                - $ref: '#/components/schemas/ApiErrorV2'
                - $ref: '#/components/schemas/CallbackV2'
              examples:
                api_internal_error:
                  summary: API Response - Internal Server Error
                  description: Immediate response from the API when an internal server error occurs.
                  value:
                    title: Internal Server Error
                callback_internal_error:
                  summary: Callback - Failure (Internal Server Error)
                  description: Callback sent to your callback_url 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.
        '502':
          description: Bad Gateway. Something went wrong on MoEngage.
          content:
            application/json:
              example: No example response body available for this status code.
        '503':
          description: Service Unavailable. Something went wrong on MoEngage.
          content:
            application/json:
              example: No example response body available for this status code.
        '504':
          description: Gateway Timeout. Something went wrong on MoEngage.
          content:
            application/json:
              example: No example response body available for this status code.
      callbacks:
        segmentCreationCallback:
          $ref: '#/components/callbacks/segmentProcessingCallback'
  /v2/custom-segments/file-segment/add-users:
    put:
      tags:
      - File Segments
      summary: Add Users to File Segment
      description: This API adds a list of users from a CSV file to an existing file segment.
      operationId: addUsersToFileSegment
      parameters:
      - name: Content-Type
        in: header
        description: Select the file content type.
        required: true
        schema:
          type: string
          default: text/csv
          enum:
          - text/csv
          - application/csv
          - application/vnd.ms-excel
          - text/plain
          - application/octet-stream
          - binary/octet-stream
      - name: Database
        in: header
        description: Set the database from which the data is available (MOE-DBNAME).
        required: false
        schema:
          type: string
      x-mint:
        content: '<Note>

          This API endpoint does not currently support Team-level scoping. All segments generated using this call will be assigned to the Default Team automatically.

          </Note>

          '
      requestBody:
        description: Details of the segment to update and the file URL of users to add.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSegmentRequestV2'
            example:
              name: custom_segment_unique_name
              cs_id: <unique cs id>
              attribute_name: unique_identifier
              attribute_type: string
              file_url: https://s3.amazonaws.com/Sample_GAIDs_add.csv
              callback_url: http://example.com/moengage-callback
              emails:
              - user1@example.com
      responses:
        '202':
          description: Request accepted for processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseSuccessV2'
              example:
                message: File-segment user-add request accepted
                success: true
                cs_name: custom_segment_unique_name
                cs_id: <unique cs id>
        '400':
          description: Bad Request. Invalid payload format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorV2'
              example:
                title: Invalid Request
                description: <message>
        '401':
          $ref: '#/components/responses/401_FileSegmentError'
        '404':
          $ref: '#/components/responses/404_FileSegmentNotFound'
        '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
  /v2/custom-segments/file-segment/remove-users:
    put:
      tags:
      - File Segments
      summary: Remove Users from File Segment
      description: This API removes a list of users from a CSV file from an existing file segment.
      operationId: removeUsersFromFileSegment
      parameters:
      - name: Content-Type
        in: header
        description: Select the file content type.
        required: true
        schema:
          type: string
          default: text/csv
          enum:
          - text/csv
          - application/csv
          - application/vnd.ms-excel
          - text/plain
          - application/octet-stream
          - binary/octet-stream
      - name: Database
        in: header
        description: Set the database from which the data is available (MOE-DBNAME).
        required: false
        schema:
          type: string
      x-mint:
        content: '<Note>

          This API endpoint does not currently support Team-level scoping. All segments generated using this call will be assigned to the Default Team automatically.

          </Note>

          '
      requestBody:
        description: Details of the segment to update and the file URL of users to remove.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSegmentRequestV2'
            example:
              name: custom_segment_unique_name
              cs_id: <unique cs id>
              attribute_name: unique_identifier
              attribute_type: string
              file_url: https://s3.amazonaws.com/Sample_GAIDs_remove.csv
              callback_url: http://example.com/moengage-callback
              emails:
              - user1@example.com
      responses:
        '202':
          description: Request accepted for processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseSuccessV2'
              example:
                message: File-segment user-remove request accepted
                success: true
                cs_name: custom_segment_unique_name
                cs_id: <unique cs id>
        '400':
          description: Bad Request. Invalid payload format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorV2'
              example:
                title: Invalid Request
                description: <message>
        '401':
          $ref: '#/components/responses/401_FileSegmentError'
        '404':
          $ref: '#/components/responses/404_FileSegmentNotFound'
        '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
  /v2/custom-segments/file-segment/replace:
    put:
      tags:
      - File Segments
      summary: Replace Users from File Segment
      description: This API replaces all users in an existing file segment with a new list of users from a CSV file.
      operationId: replaceUsersInFileSegment
      parameters:
      - name: Content-Type
        in: header
        description: Select the file content type.
        required: true
        schema:
          type: string
          default: text/csv
          enum:
          - text/csv
          - application/csv
          - application/vnd.ms-excel
          - text/plain
          - application/octet-stream
          - binary/octet-stream
      - name: Database
        in: header
        description: Set the database from which the data is available (MOE-DBNAME).
        required: false
        schema:
          type: string
      x-mint:
        content: "<Note>\n**Notes:**\n\n  * This API drops all existing users from the segment and adds the new users provided in the File URL.\n  * Only the newly added users are counted towards the daily file segment user limit.\n  * This API does not currently support Team-level scoping. All segments generated using this call will be assigned to the Default Team automatically.\n</Note>\n"
      requestBody:
        description: Details of the segment to update and the file URL of users to replace with.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSegmentRequestV2'
            example:
              name: custom_segment_unique_name
              attribute_name: unique_identifier
              cs_id: <unique cs id>
              attribute_type: string
              file_url: https://s3.amazonaws.com/Sample_GAIDs_replace.csv
              callback_url: http://example.com/moengage-callback
              emails:
              - user1@example.com
      responses:
        '202':
          description: Request accepted for processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseSuccessV2'
              example:
                message: File-segment user-replace request accepted
                success: true
                cs_name: custom_segment_unique_name
                cs_id: <unique cs id>
        '400':
          description: Bad Request. Invalid payload format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorV2'
              example:
                title: Invalid Request
                description: <message>
        '401':
          $ref: '#/components/responses/401_FileSegmentError'
        '404':
          $ref: '#/components/responses/404_FileSegmentNotFound'
        '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
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
    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.
        cs_id:
          type: string
          description: The unique identifier of the segment.
    UpdateSegmentRequestV2:
      description: Schema for updating an existing file segment (add, remove, replace users).
      allOf:
      - $ref: '#/components/schemas/BaseSegmentRequestV2'
      - type: object
        properties:
          cs_id:
            type: string
            description: 'Unique identifier corresponding to the target segment. When both `cs_id` and `name` are populated, the system prioritizes `cs_id`.

              '
    CallbackV2:
      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.
      required:
      - db_name
      - segment_name
      - request_id
      - status
    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
    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.
  responses:
    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: <appropriate message>
    404_FileSegmentNotFound:
      description: Entity Not Found. The segment name does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorV2'
          example:
            title: Entity Not Found
            description: 'Segment not found with the given name: <custom_segment_unique_name>'
    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 : <segment_name>'
    401_FileSegmentError:
      description: Unauthorized. Authentication or Authorization Failure.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorV2'
          example:
            title: Authentication required
            description: <message>
  callbacks:
    segmentProcessingCallback:
      '{$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'
          responses:
            '200':
              description: OK. Acknowledges receipt of the callback. Your endpoint should return this.
  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).'