> ## 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.

# Add Users to File Segment

> This API adds a list of users from a CSV file to an existing file segment.

<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>


## OpenAPI

````yaml /api/custom-segments/custom-segments.yaml put /v2/custom-segments/file-segment/add-users
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 access the archived segments and utilize them to analyze and
      market campaigns without the need to recreate them from scratch.
    x-mint:
      content: |

        <Warning>
          Archived segments will not be shown beyond 180 days.
        </Warning>
  - 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/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
      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
components:
  schemas:
    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`.
    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.
    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
  responses:
    401_FileSegmentError:
      description: Unauthorized. Authentication or Authorization Failure.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorV2'
          example:
            title: Authentication required
            description: <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>
    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>
  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).

````