Fetch Cards API

The Fetch Cards API can be used to fetch cards for any user (using the unique_id or uid) from the MoEngage Cards database. You can filter the search results based on the platform and card category and see if any card was updated for the user since the previous sync.

API Endpoint

POST https://api-0X.moengage.com/v1/cards/fetch?page={page_number}&limit={limit}

Each customer is hosted on a different data center; you can find your data center number (value of X) by checking the data center and API endpoint mapping page.

Authentication

The API request will be authenticated through Basic Authentication. Basic Authentication sends a Base64-encoded string containing your username and password with every API request. It encodes a 'username:password' string in Base64 and appends the encoded string with 'Basic '. This string is included in the authorization header as shown below:

{"Authorization":"Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U="}

The username and password details can be obtained from the MoEngage Dashboard. We've revamped the settings UI in the Dashboard. If you're using the API for the first time, follow these steps for the revamped and old UIs:

Revamped UI

Navigate to Settings -> Account -> APIs.
Click the Copy icon in the Campaign report/Business events/Custom templates tile in the API Keys section to copy the API Key.
Use the App ID as the username and the Push API Key as the password to generate the authentication header.

Old UI

Navigate to Settings -> APIs -> TRANSACTION PUSH/REPORT Settings.
Click on the Click here to show APP Secret link to view the API SECRET.
Use the APP ID as the username and the API SECRET as the password to generate the authentication header.

Request Headers

Key	Required	Sample Values	Description
Content-Type	Required	{"Content-Type": "application/json"}	Set the Content-Type header to application/json.
Authorization	Required	{"Authorization": "Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U=="}	This authentication parameter, used for access control, must be passed along with the request. To generate the authentication header, refer to Authentication.

Request Parameters

Key	Required	Data Type	Description
page	Optional	Number	This field contains the index of the pages to be returned in the search result. When this value is not passed in the request, one page is returned in the search result. The value should be a number greater than zero.
limit	Optional	Number	This field contains the number of cards returned in the search result. When this value is not passed in the request, all the cards are fetched and returned in the search result. The value should be a number greater than zero.

Request Body

Key	Required	Data Type	Description
unique_id or uid	Required (Either the unique_id or the uid should be passed in the request)	String	This field is used to filter the cards based on the unique_id or uid specified in the request. The unique_id is the unique value that identifies the user to send the cards. The unique_id is the platform-specific device identifier; refer to Generating unique_id for details. The uid is the unique MoEngage Standard ID (Email ID Standard or the Mobile Number Standard) that identifies the user.
platforms	Optional	Array of String	This field is used to filter the cards according to the platform. Cards of all the platforms that are provided are returned in the search result. When this field is not specified in the request, cards of all platforms are returned. Allowed Values: ANDROID, IOS, WEB Example: "platforms": ["ANDROID", "WEB", "IOS"]
card_category	Optional	String	This field is used to filter the cards based on the card category. When this field is not specified in the request, cards of all categories are returned. For more information, refer to Card Categories. Example: "card_category": "{category}"
prev_sync_card_ids	Optional	Array of String	This field is used to filter the cards based on the ID of the cards that were sent fetched earlier using this API. This field will be used to filter cards that do not have any changes made to them since the last fetch. Thus, only those cards that have been updated for the specified user since the last fetch would be returned. This should be used along with last_updated_time (see the row below for details about last_updated-time). Example: "prev_sync_card_ids": ["{campaign_id}_F_T_CA_AB_0_P_0_L_0_android"]
last_updated_time	Optional	Number (Unix epoch time)	This field is used to filter the cards based on the last time the cards were synced. This should be used along with prev_sync_card_ids (see row above for details) to identify if there has been any update to the cards since the last sync. Example: "last_updated_time": 1684168142

Generating unique_id

The unique_id refers to the device identifier and is platform-specific. You can generate the unique id for Android and iOS using the methods listed below.

Android

iOS

MoEngageSDKCore.getMoEngageDeviceId(completionHandler: @escaping UserInfoHandler)

Response

Key	Data Type	Description
status	Boolean	This field represents whether the request was successful and contains true when the request was successful and false otherwise.
request_id	String	This field contains the unique identifier that denotes the request.
data	Array of JSON Objects	This field contains the list of cards that satisfy the search criteria. "data": { "deleted_card_ids": [list of deleted card ids], "cards": [{Card 1},{Card 2}, ... {Card n}] } For information about the template, refer to Cards and Meta Data.
title	String	This field is present in the response body only when the request is unsuccessful and contains the error type.
description	String	This field is present in the response body only when the request is unsuccessful and contains the error description.
code	String	This field is present in the response body only when the request is unsuccessful and contains the error code.

Cards

Key	Data Type	Description
id	String	This field contains information about the Card id and the platform. Example: "id": " 640g66767676hh56565656_F_T_CA_AB_0_P_0_L_0_android"
platform	String	This field contains the platforms on which the Card is supported. Supported Values: ANDROID, IOS, WEB
created_at	Integer	This field contains the Unix epoch that represents when the Card campaign was created.
updated_at	Integer	This field contains the Unix epoch that represents when the Card campaign was updated last.
meta_data	JSON Object	This field contains identifiers for the card campaign, such as the campaign id, card id, and so on. For more information, refer to Meta Data.
template_data	JSON Object	This field contains information about the Card Template. For more information, refer to Template Data.
user_activity	JSON Object	This field contains information about whether the user has clicked on the card. Structure: "user_activity": { "is_clicked": <true/false>, "first_seen": <Epoch timestamp>, "first_delivered": <Epoch timestamp>, "show_count": { <unique_id/uid>(String): count (Integer) } } is_clicked - This field contains a Boolean value and indicates whether the card was clicked. first_seen - This field contains an Integer and indicates the first time the card was seen by the user (time is represented as Epoch timestamp in seconds). first_delivered - This field contains an Integer and indicates when the first card was delivered (time is represented as Epoch timestamp in seconds). show_count - This field contains a JSON Object where the unique_id/uid (that is used when making the fetch call) is present as the key and the number of times the unique_id/uid has been used for the fetch is present as the value. Structure of show_count: "show_count": { <unique_id/uid>: <count> }
display_controls	JSON Object	This field contains information about the display controls set in the card campaign. Display controls contain information about the card's expiry, the number of times a card can be shown, and whether the card should be pinned to the top. For more information, refer to Display Controls. Structure: { "max_times_to_show": <Number of times the card can be shown to a user>, "expire_after_delivered": "Card expiry time", "is_pin": <true/false> } max_times_to_show - This field is an Integer and indicates the maximum number of times the card can be shown to a user. expire_after_delivered - This field is an Integer and contains the timestamp of card expiry. is_pin - This field contains a Boolean value and indicates whether the card has been configured to be pinned at the top.
category	String	This field contains information about the card category. For more information, refer to Card Categories. Example: "category": "Promotions"

Meta Data

Key	Values	Description
cid	String	This field contains the unique identifier that denotes the Card. Example: "cid": "63d8e8ed6e460651e5911273_F_T_CA_AB_0_P_0_L_0"
moe_card_id	String	This field is a combination of the cid and the platform. Example: "moe_card_id": " 640g66767676hh56565656_F_T_CA_AB_0_P_0_L_0_android"
moe_campaign_name	String	This field contains the name of the Card campaign.
moe_delivery_type	String	This field contains the campaign's delivery type. Supported Values: One Time, Event Triggered
moe_campaign_id	String	This field contains the unique identifier that denotes the campaign associated with the Card. Example: "moe_campaign_id": "640g66767676hh565656c4"

Template Data

Key

Values

Description

type

String

This field refers to the template type.

Supported Values: basic, illustration

Example: "type": "basic"

containers

Array of Objects

This field contains information about individual UI elements used in the Card. For more information, refer to Containers.

Containers

Containers contain information about the individual UI elements and their properties for self-handled cards.

Key	Values	Description
widgets	Array of Objects	This field contains information about the widgets used in the card. For more information, refer to Widgets.
style	Array of Objects	This field contains information about the formatting and font styles used for the card containers. For example, background color. Example: "style": {"bgColor": "#4e3db0"}
type	String	This field refers to the card type. Supported Values: basic, illustration Example: "type": "basic"
id	Integer	This field refers to the widget's id (the unique identifier for the widget).
actions	Array of Objects	This field contains information about what should happen when the card is tapped. For more information, refer to Actions.

Widgets

Widgets refer to the UI properties defined for self-handled cards.

Key	Values	Description
content	String	This field refers to the content that would be displayed in the widget.
type	String	This field refers to the content type (such as text, image, and so on).
id	Integer	This field refers to the unique identifier for the widget.

Actions

Actions define what happens when the user taps on the card. For more information, refer to Card Actions.

Key	Values	Description
type	String	This field contains information about the action type. Supported Values: screenName, deepLink, and richLanding
name	String	This field contains the name assigned to the action. Example: "name": "navigate"
value	String	This field contains the URL or screen to which the user would be redirected upon tapping the card. Example: "value": "https://www.examplehomepage.com"
kvPairs	JSON Object	This field contains the parameters for the URL to which the user would be redirected.

Rich Landing
    {
        "name": "navigate",
        "type": "richLanding",
        "value": "<value>",
        "kvPairs": {<KV Pairs>}
    }
    
Deep Linking
    {
        "name": "navigate",
        "type": "deepLink",
        "value": "<value>",
        "kvPairs": {<KV Pairs>}
    }
    
Navigate to Screen
    {
        "name": "navigate",
        "type": "screenName",
        "value": "<value>",
        "kvPairs": {<KV Pairs>}
    }

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 are missing from the request or when the provided parameters are invalid.
401	Authorization Failure	This response is returned when the authorization parameters are missing in the HTTP Auth Header.
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 50K RPM and is applicable at the DB(App) level.

Sample cURL Request

curl --location 'https://api-{{0X}}.moengage.com/v1/cards/fetch?page={page}&limit={limit}' \
--header 'MOE-APPKEY: {{DATA_APP_ID}}' \
--header 'AUTHORIZATION: Basic SFhaSDQ1WkZPN09BQzk4QlZRMTQ3NzNOOlhUTzRWVTU2VjdBWg==' \
--header 'Content-Type: application/json' \
--data '{
    "unique_id": "{{unique_id}}",
	    "platforms": ["ANDROID", "WEB","IOS"],
	    "limit": 4,
	    "last_updated_time": 1695987441, 
	    "prev_sync_card_ids": ["6516b30d2712560fdfae50c3_F_T_CA_AB_0_P_0_L_0_web"],
	    "card_category": "Announcements"
	
}'

Sample Response


Sample Response for a successful request
{
    "status": true,
    "request_id": "647f1cfd1f9a63c4e5326132",
    "data": {
        "deleted_card_ids": [
            "647db2a06dcaf6b88022ac5b_F_T_CA_AB_0_P_0_L_0_android",
            "647dac252dcca5fe2d6b302b_F_T_CA_AB_0_P_0_L_0_android"
        ],
        "cards": [
            {
                "id": "640g66767676hh56565656_F_T_CA_AB_0_P_0_L_0_android",
                "platform": "android",
                "created_at": 1686051528,
                "updated_at": 1686051528,
                "meta_data": {
                    "cid": "647f136f28cd97f6106b86c4_F_T_CA_AB_0_P_0_L_0",
                    "moe_card_id": "640g66767676hh56565656_F_T_CA_AB_0_P_0_L_0_android",
                    "moe_campaign_name": "Demo Card Campaign",
                    "moe_delivery_type": "Event Triggered",
                    "moe_campaign_id": "647f136f28cd97f6106b86c4"
                },
                "template_data": {
                    "type": "basic",
                    "containers": [
                        {
                            "widgets": [
                                {
                                    "content": "https://image.moengage.com/apiqasanityreactmoengage/20230606110034350340RKQN5HScreenshot2023060614443597f7c44fa5c96f29b225c53b361750eadajpgcompapiqasanityreactmoengage.jpg",
                                    "type": "image",
                                    "id": 0
                                },
                                {
                                    "content": "<div>john.doe@example.com</div>",
                                    "type": "text",
                                    "id": 1
                                },
                                {
                                    "content": "<div>Sample</div>",
                                    "type": "text",
                                    "id": 2
                                },
                                {
                                    "content": "<div>Click </div>",
                                    "type": "button",
                                    "id": 3,
                                    "actions": [
                                        {
                                            "type": "deepLink",
                                            "name": "navigate",
                                            "value": "https://www.moengage.com",
                                            "kvPairs": {}
                                        }
                                    ]
                                }
                            ],
                            "style": {
                                "bgColor": "#4e3db0"
                            },
                            "type": "basic",
                            "id": 0,
                            "actions": []
                        }
                    ]
                },
                "user_activity": {
                    "is_clicked": false
                },
                "display_controls": {
                    "is_pin": true,
                    "expire_after_delivered": 2592000
                },
                "category": "Promotions"
            }
        ]
    }
}


Sample Response for when the Unique ID is not found
{
    "status": false,
    "error": "User not found for this uid/ unique_id",
    "request_id": "64f6a59ed1e36d0d57a790c1"
}


Sample Response for when the APP_SECRET is invalid
{
    "title": "Authentication Failure",
    "description": "Invalid APP_SECRET_KEY is provided",
    "code": "OjueJWoh"
}
Sample Response for when the APP_ID is invalid
{
    "title": "Authentication Failure",
    "description": "Invalid APP_ID is provided",
    "code": "HEmxyvgs"
}


Sample Response for Rate Limit Breach
{
    "title": "Request limit reached",
    "description": "This API call has exceeded the rate limit",
    "code": "KMxkunyz"
}


Sample Response for server side errors
{ 
    "title": "Internal Server Error",
    "message": "An unexpected error was encountered while processing this request. Please contact MoEngage Team"
}

Postman Collections

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

FAQs

What is the difference between unique_id and uid?

The unique_id is the unique value that identifies the user to whom the cards need to be shown. It is a platform-specific device identifier that can be generated, as mentioned in the Generating unique_id section.

The uid is the unique MoEngage Standard ID (Email ID Standard or the Mobile Number Standard) that identifies the user.