Custom Segment API


This API is deprecated.

  1. Custom Segment API is deprecated.
  2. Use Custom File Segment API to create file segments, add users to file segments, remove users from the file segment, archive, and unarchive the file segments. Link -

This API allows to create a custom segment from CSV via an API call.
Unsure of the content of file? Download a sample

API Endpoint

API call is a POST method, and the URL is mentioned below.

API Information

Response format


Requires authentication


Request Headers


Request Body

  • appId (mandatory) : MoEngage provided APP ID. Can be found at Settings -> App Settings.

  • attribute (mandatory) : Name of the user attribute on which segment is being created.
    For registered users, use user attribute ID and for Anonymous (not registered) users use email, mobile number or any other identifier as the anonymous user identifier.

  • attributeType (mandatory) : Data Type of the user attribute on which segment is being created.
    Should be one of the following string, numeric, geo_point, date.

  • segName (mandatory) : Name of custom segment.

  • csvUrl (mandatory) : Url where CSV is hosted.
    CSV should be downloadable without authorization

  • callback (mandatory) : Callback url to receive result of segment creation.

  • signature (mandatory): Signature generated from a hash of App Id, Segment Name and API Secret. You can find API Id (or App Id) & API Secret in your MoEngage Dashboard under Settings->Transaction Push Settings.

  • emails (optional) : List of email ids to receive segment creation response.

from hashlib import sha256

app_id = "MAZW51234N1IMMSH5HKBHB_DEBUG" #(Please refer to required parameters section)
seg_name = "TEST"
api_secret = "S3pVzjBF9use" # This is the sample key. Each app has a different secret key
signature = sha256(app_id+'|'+ seg_name+'|'+ api_secret).hexdigest()

HTTP status code summary

Status Code


200 - OK

Everything worked as expected.

201 - Create

Status returned in callback if segment is successfully created

400 - Bad Request

The request was unacceptable, often due to missing a required parameter.
Reason is passed in error_message param

401 - Unauthorized

Signature not valid.

409 - Conflict

The request conflicts with another request.

500, 502, 503, 504 - Server Errors

Something went wrong on MoEngage's end.


Rate Limit Name

Rate Limit

file_segment ops per hour

The total number of file segment operations(which are create-segment/add-users/remove-users) per hour per client allowed is 10.

file_segment ops per day

The total number of file segment operations(which are create-segment/add-users/remove-users) per day per client allowed is 100.

file_segment users per day

The total number of users that can be uploaded via file-segment is limited to 2 million per day.


The size of the file from which the segment is created/updated. For each request, the file size limit is 150 MB.

Sample Request

curl -H "Content-Type: application/json" -X POST 
-d '{"segName": "TEST",
"callback": "http://localhost:12345",
"csvUrl": "",
"attribute": "email",
"attributeType": "string"}'
import requests

request_params = dict(appId='MAZW51234N1IMMSH5HKBHB_DEBUG',
r ='', json=request_params)

API Sample Response

  "status": 200,
 "request_id": "d5a263c4ef1198ae3d8496c0460f570f", 
  "segment_name": "TEST"
  "status": 409,
  "request_id": "d5a263c4ef1198ae3d8496c0460f570f", 
  "error_message": "duplicate request", 
  "segment_name": "TEST"
  "status": 400, 
  "error_message": "Bad Value for appId"
  "status": 401, 
  "error_message": "Unauthorized"
  "status": 500, 
  "error_message": "Internal Server Error. Contact MoEngage Team",
  "segment_name": "TEST"

Callback Sample Body

  "status": 201, 
  "values_found": 16, 
  "values_processed": 16, 
  "request_id": "d5a263c4ef1198ae3d8496c0460f570f", 
  "user_count": 40, 
  "segment_name": "TEST"
  "status": 409,
  "request_id": "d5a263c4ef1198ae3d8496c0460f570f", 
  "error_message": "duplicate request", 
  "segment_name": "TEST"
  "status": 400, 
  "segment_name": "TEST", 
  "error_message": "File download failed.", 
  "request_id": "c8e065d1851dfe114395bc9dab629284"
  "status": 500, 
  "error_message": "Internal Server Error. Contact MoEngage Team",
  "segment_name": "TEST"



This API does not support update or delete operations on a segment.
If the segment name already exists in the MoEngage system, the request should be rejected.

Import APIs in to Postman

We have made it easy for you to test the apis, If you are using Postman, click on the following button to export our Data APIs in to your Postman collections.


Segment Processing & Availability

As soon as the request is received at the MoEngage system, MoEngage creates a custom segment with zero users. After this, the file is processed and users are added to the custom segment. If the created custom segment is queried in between the file processing, it will show zero or partial user count.