Get User

This API facilitates the retrieval of information of users by specifying the user ids.

API Endpoint

https://api-0X.moengage.com/v1/users/export/<APP_ID>?app_id=<APP_ID>

The 'X' 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 (value of X) and replace the value of 'X' in the URL by referring to the DC and API endpoint mapping.

Authentication

The API request will be authenticated through Basic Authentication.

To generate the Basic Authentication header:

Navigate to Settings > APIs >General Settings > DATA API Settings
Copy the DATA API ID and DATA API KEY
Generate the Authentication Header String
Basic Authentication encodes a 'username:password' using base64 and prepends it with the string 'Basic '. To generate the Auth header:

- Add a colon after the user name (DATA API ID) and concatenate it with the password (DATA API KEY).
- Encode the concatenated string using base64 encoding.
- Pass the encoded string in the HTTP authorization header as follows: {"Authorization":" Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U=="}

Request Parameters

Key	Required	Data Type	Description
app_id	Yes	String	This is your MoEngage account's APP ID that has to be passed along with the request. You can find your MoEngage APP ID in the MoEngage Dashboard API Settings. Navigation: Settings -> API -> General Settings -> DATA API section. For more information, refer to Authentication.

Request Headers

Key	Required	Sample Values	Description
X-Forwarded-For	Yes	Header Value Format: <IP Address>	The 'X-Forwarded-For' header is used to specify the IP address of the client that made the request. This header may be added by proxy servers or load balancers. The header value must contain the IP address of the original client that initiated the request. Multiple IP addresses may be specified in the header value, separated by commas.
Content-Type	Yes	application/json	Set the Content-Type header to application/json.
Authorization	Yes	{"Authorization": "Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U=="}	This is the authentication parameter for access control and needs to be passed along with the request. The APP KEY (DATA API ID) and API SECRET (DATA API KEY) need to be picked up from the DATA API Settings in the MoEngage Dashboard, and a Basic Authorization header needs to be created and set in the header. Navigation: Settings -> API -> General Settings -> DATA API section. For more information, refer to Authentication.

Request Body

Key

Required

Data Type

Description

Identifiers

Yes

Array of JSON Objects

This field is used to specify the identifiers for the users for whom the data needs to be fetched.

Structure:

"identifiers": [

{

"identifier_type": "customer_id",

"identifier": "<customer_id>"

{

"identifier_type": "id",

"identifier":"<MoEngageID>"

...{}

]

identifier_type - This field specifies the identifier type. Identifier types can either be customer_id (ID field in the User Profile) or id (the MoEngageID of the user in the User Profile). It is a String.
identifier - This field specifies the unique identifier that identifies the user. It is a String.

user_fields_to_export

Yes

Array of Strings

This field is used to specify the fields that need to be fetched for the user specified in Identifiers. Tracked standard user attributes and custom attributes can be fetched using this API. For the list of tracked standard attributes in MoEngage, refer to User Attributes.

Response

Key	Data Type	Description
status	String	This field contains the status of the request and specifies whether the request was successful. Supported Values: success, failure Example: "status": "success"
type	String	This field denotes the fetch type. Supported Values: export_users Example: "type": "export_users"
data	JSON Object	This field contains the list of users who were not found in MoEngage and returns the data specified for the list of users who were found in MoEngage. Structure: { "users_not_found": [ { "identifier_type": "customer_id", "identifier": "<customer_id>" } ], "users": [ { "user_attributes": { <list of user attributes> } } ] } users_not_found - an array of JSON Objects that contains the list of users who were not found in MoEngage. users - contains the user_attributes specified in the request for each user in specified in the request.
error	JSON Object	This field is present in the response only in the case of an error and contains the error details. Structure: { "attribute": "<attribute causing the error >", "message": "<error message>", "type": "<error type>", "request_id": "<request_id>" } attribute - This field contains the name of the request attribute causing the error. For example, "attribute": "identifiers" implies that the identifiers request attribute is causing the error. message - This field contains the error message. type - This field contains the error type. For example, "type": "Malformed JSON" implies that the JSON in the request is incorrectly formed. request_id - This field denotes the request-id for which the error response is being returned.

Response Codes

Status Code	Request State	Description
200	Success	This response is returned when the request is processed successfully.
400	Bad Request	This response is returned when the required parameters APP KEY, user_id, and so on are missing from the request or when the provided params are invalid.
401	Authorization Failure	This response is returned when the authorization fails due to incorrect values for the APP KEY/ HTTP Auth Header.
403	Account Suspended/Blocked Temporarily	This response is returned when the user account has been suspended temporarily or blocked.
413	Payload Limit Exceeded	This response is returned when the payload size has exceeded the limit set.
415	Unsupported media type	This response is returned when the header “Content-Type” is not provided/is not supported.
429	Rate Limit Breach	This response is returned when the number of requests per minute has exceeded the rate limit.
5xx	Internal Server Error	This response is returned when the system runs into an unexpected error.

Rate Limit

The rate limit is 20 users per payload and 1000 users per minute.

Sample cURL Request

curl --location 'https://api-{{0X}}.moengage.com/v1/users/export/{{APP_ID}}?app_id={{APP_ID}}' \
--header 'X-Forwarded-For: 34.249.175.81' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic e3tEQVRBIEFQSSBJRH19Ont7REFUQSBBUEkgS0VZfX0=' \
--data '{
    "data": {
        "identifiers": [
            {
                "identifier_type": "customer_id",
                "identifier": "{{user_id_that_you_want_to_fetch_details_of}}"
            },
            {
                "identifier_type": "id",
                "identifier": "{{moengage_user_id_that_you_want_to_fetch_details_of}}"
            }
        ]
    }
}'

Sample Response

Success Response
{
    "status": "success",
    "type": "export_users",
    "data": {
        "users_not_found": [
            {
                "identifier_type": "customer_id",
                "identifier": "john_doe"
            }
        ],
        "users": [
            {
                "user_attributes": {
                    "last_name": "Doe",
                    "customer_id": "john_doe",
                    "name": "John",
                    "custom_user_attr": 12345,
                    "id": "62e79fb15ada55x123g987bu"
                }
            }
        ]
    }
}

Sample response for when idenitifers are missing in the request
{
    "status": "fail",
    "error": {
        "attribute": "identifiers",
        "message": "identifiers is not found in the payload",
        "type": "MissingAttributeError",
        "request_id": "UkBwaUmU"
    }
}

Sample response for when data is missing in the request
{
    "status": "fail",
    "error": {
        "attribute": "data",
        "message": "data is not found in the payload",
        "type": "MissingAttributeError",
        "request_id": "zAsmTigV"
    }
}

Sample response for when the JSON is incorrect in the request
{
    "status": "fail",
    "error": {
        "message": "Could not decode the request body. The JSON was incorrect or not encoded as UTF-8.",
        "type": "Malformed JSON",
        "request_id": "NphDCzWk"
    }
}

Sample response for when the number of users exceeds the allowed limit in the request
{
    "status": "fail",
    "error": {
        "attribute": "payload.users",
        "message": "max limit allowed is 20",
        "type": "LimitBreached",
        "request_id": "IYQXyWTP"
    }
}

Sample response for authorization errors
{
    "status": "fail",
    "error": {
        "message": "App Secret key mismatch. Please login to the dashboard to verify key",
        "type": "Authentication required",
        "request_id": "PVUDFisO"
    }
}

Sample response for missing authentication header
{
    "status": "fail",
    "error": {
        "message": "Authentication Header Required",
        "type": "Authentication required",
        "request_id": "PiSPjGQQ"
    }
}

Sample response for when your account is blocked
{
    "status": "fail",
    "error": {
        "message": "Your account is suspended. Please contact MoEngage team.",
        "type": "BlockedClient",
        "request_id": "ofHUEaEQ"
    }
}


Sample response for when your account is suspended
{
    "status": "fail",
    "error": {
        "message": "Your account is suspended. Please contact MoEngage team.",
        "type": "Account Suspended",
        "request_id": "gqJvCNYu"
    }
}


Sample response for when your account is temporarily suspended
{
    "status": "fail",
    "error": {
        "message": "Your account is temporarily suspended. Please contact MoEngage team.",
        "type": "Account Temporarily Suspended",
        "request_id": "ssSJjoyD"
    }
}

Sample response for payloads exceeding the size limit
{
    "status": "fail",
    "error": {
        "message": "Payload can not exceed 128KB",
        "type": "Payload too large",
        "request_id": "VFzDwhwt"
    }
}

Sample response for unsupported media type
{
    "status": "fail",
    "error": {
        "message": "Content type is not supported",
        "type": "Unsupported media type",
        "request_id": "SgBQfKJh"
    }
}

Sample response for rate limit breach
{
    "status": "fail",
    "error": {
        "message": "Rate limits for customers exceeded. Please Try After Some Time",
        "type": "Rate Limits Exceeded",
        "request_id": "onqucLYL"
    }
}

Sample response for unknown errors
{
    "status": "fail",
    "error": {
        "message": "An unexpected error was encountered while processing this request. Please contact MoEngage Team",
        "type": "Server Error",
        "request_id": "KovrwJiF"
    }
}

Postman Collections

We have made it easy for you to test the APIs. Click here to view it in Postman.

FAQs

How do I know which users are available to export and which users are not available in MoEngage to export?
All available users will be found in the users key, and users not available will be found in the users_not_found key. Please refer to the sample response in this doc.
What if I want to get all the user data available based on the user ids without specifying the fields?
If the user_fields_to_export is not passed, then all the custom attributes and exportable standard attributes will be passed. For specific fields, user_fields_to_export needs to be passed along with the required fields.