openapi: 3.0.3
info:
title: MoEngage Cards API
description: |
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.
version: '1.0'
x-mint:
content: |
# 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.
### 1. Android
The platform-specific device ID (or Unique ID) can typically be retrieved from the SDK's core functionality after initialization. [Android Documentation](https://moengage.github.io/android-api-reference/core/com.moengage.core/[android-jvm]-mo-e-core-helper/get-mo-engage-device-id.html)
### 2. iOS
The device ID can be retrieved using the following method:
```swift
MoEngageSDKCore.getMoEngageDeviceId(completionHandler: @escaping UserInfoHandler)
```
servers:
- url: 'https://api-{dc}.moengage.com/v1'
variables:
dc:
default: '01'
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."
tags:
- name: Cards
description: Operations related to fetching and deleting user cards.
paths:
/cards/fetch:
post:
tags:
- Cards
summary: Fetch Cards for User
operationId: fetchCards
description: |
This API retrieves all active and updated cards for a specific user from the MoEngage Cards database. You can filter the search results based on the platform and card category and check if any card was updated for the user since the previous sync.
x-mint:
content: |
#### Rate Limit
The rate limit is **50K RPM** (Requests Per Minute) and is applicable at the workspace (App) level.
parameters:
- $ref: '#/components/parameters/PageQuery'
- $ref: '#/components/parameters/LimitQuery'
- $ref: '#/components/parameters/AppKeyHeader'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FetchCardsRequest'
example:
uid: "user@example.com"
platforms: ["ANDROID", "WEB"]
last_updated_time: 1695987441
prev_sync_card_ids: ["6516b30d2712560fdfae50c3_F_T_CA_AB_0_P_0_L_0_web"]
card_category: "Announcements"
responses:
'200':
description: This response is returned when the request is processed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/FetchCardsResponse'
'400':
description: This response is returned when the required parameters are missing from the request or when the provided parameters are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
user_not_found:
summary: User Not Found
value:
status: false
error: "User not found for this uid/ unique_id"
request_id: "64f6a59ed1e36d0d57a790c1"
'401':
description: This response is returned when the authorization parameters are missing in the HTTP Auth Header.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalid_secret:
summary: Invalid Secret Key
value:
title: "Authentication Failure"
description: "Invalid APP_SECRET_KEY is provided"
code: "OjueJWoh"
invalid_app_id:
summary: Invalid App ID
value:
title: "Authentication Failure"
description: "Invalid APP_ID is provided"
code: "HEmxyvgs"
'429':
description: This response is returned when the number of requests per minute has exceeded the rate limit.
headers:
x-ratelimit-limit:
schema: { type: integer }
x-ratelimit-remaining:
schema: { type: integer }
x-ratelimit-reset:
schema: { type: integer }
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
title: "Request limit reached"
description: "This API call has exceeded the rate limit"
code: "KMxkunyz"
'500':
description: This response is returned when the system runs into an unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
title: "Internal Server Error"
message: "An unexpected error was encountered while processing this request. Please contact MoEngage Team"
/cards/delete:
delete:
tags:
- Cards
summary: Delete Cards for User
operationId: deleteCards
description: |
This API deletes cards for a specified user from the MoEngage Cards database.
x-mint:
content: |
#### Rate Limit
The rate limit is **50K RPM** (Requests Per Minute) and is applicable at the workspace (App) level.
parameters:
- $ref: '#/components/parameters/AppKeyHeader'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteCardsRequest'
example:
uid: "user@example.com"
campaign_ids: ["campaign_id1", "campaign_id2"]
platforms: ["android", "ios"]
responses:
'200':
description: This response is returned when the request is processed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteCardsResponse'
'400':
description: This response is returned when the required parameters are missing from the request or when the provided parameters are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missing_uid:
summary: Missing ID
value:
status: false
error: "Required field missing. Please include either 'uid' or 'unique_id'"
request_id: "64f6a59ed1e36d0d57a790c1"
invalid_campaigns:
summary: Invalid Campaign IDs
value:
status: false
error: "Invalid or missing 'campaign_ids' field"
request_id: "64f6a59ed1e36d0d57a790c1"
user_not_found:
summary: User Not Found
value:
status: false
error: "User not found for this uid/ unique_id"
request_id: "64f6a59ed1e36d0d57a790c1"
'401':
description: This response is returned when the authorization parameters are missing in the HTTP Auth Header.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
auth_required:
summary: Auth Required
value:
title: "Authentication required"
description: "APP_ID and APP_SECRET_KEY is missing in Authorization Header."
code: "KMxkunyz"
'429':
description: This response is returned when the number of requests per minute has exceeded the rate limit.
headers:
x-ratelimit-limit:
schema: { type: integer }
x-ratelimit-remaining:
schema: { type: integer }
x-ratelimit-reset:
schema: { type: integer }
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
title: "Request limit reached"
description: "This API call has exceeded the rate limit"
code: "KMxkunyz"
'500':
description: This response is returned when the system runs into an unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
title: "Internal Server Error"
message: "An unexpected error was encountered while processing this request. Please contact MoEngage Team"
components:
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 **Campaign report/Business events/Custom templates/Catalog API/Inform Report** tile.
For more information on authentication and getting your credentials, refer [here](https://www.moengage.com/docs/api/introduction#getting-your-credentials).
parameters:
AppKeyHeader:
name: MOE-APPKEY
in: header
required: true
description: This is the Workspace ID of your MoEngage account that must be passed with the request. You can find it in the MoEngage dashboard at **Settings** > **Account** > **APIs** > **Workspace ID (earlier app id)**.
schema:
type: string
PageQuery:
name: page
in: query
required: false
description: |
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.
schema:
type: integer
minimum: 1
default: 1
LimitQuery:
name: limit
in: query
required: false
description: |
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.
schema:
type: integer
minimum: 1
schemas:
# --- Request Schemas ---
FetchCardsRequest:
type: object
x-mint:
content: |
<Note>You must provide either `uid` or `unique_id` in the request body.</Note>
properties:
uid:
type: string
description: |
The `uid` is the unique **MoEngage Standard ID** (Email ID Standard or Mobile Number Standard) that identifies the user. You can get the `uid` from the **User Profile** page of your dashboard.
This field is used to filter the cards based on the `unique_id` or `uid` specified in the request.
unique_id:
type: string
description: |
The `unique_id` is the platform-specific device identifier (e.g., IDFA/AAID) that uniquely identifies the user. Refer to [Generating unique_id](/api/cards/fetch-cards-for-user#generating-unique_id) for details.
platforms:
type: array
items:
type: string
enum: [ANDROID, IOS, WEB]
description: |
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.
card_category:
type: string
description: |
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](/user-guide/campaigns-and-channels/cards/create/create-a-card-campaign).
prev_sync_card_ids:
type: array
items:
type: string
description: |
This field is used to filter the cards based on the ID of the cards that were 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`.
last_updated_time:
type: integer
format: int64
description: |
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` to identify if there has been any update to the cards since the last sync. (Unix epoch time).
description: |
You must provide either 'uid' or 'unique_id'.
#### Generating unique_id
The `unique_id` refers to the device identifier and is platform-specific.
* [Android](https://moengage.github.io/android-api-reference/core/com.moengage.core/[android-jvm]-mo-e-core-helper/get-mo-engage-device-id.html)
* **iOS**: `MoEngageSDKCore.getMoEngageDeviceId(completionHandler: @escaping UserInfoHandler)`
DeleteCardsRequest:
type: object
required:
- campaign_ids
x-mint:
content: |
<Note>You must provide either `uid` or `unique_id` in the request body.</Note>
properties:
uid:
type: string
description: |
The `uid` is the unique **MoEngage Standard ID** (Email ID Standard or Mobile Number Standard) that identifies the user.
unique_id:
type: string
description: |
The `unique_id` is the platform-specific device identifier. Refer to [Generating unique_id](/api/cards/fetch-cards-for-user#generating-unique_id) for details.
campaign_ids:
type: array
items:
type: string
description: |
List of campaign IDs whose cards should be deleted for the user.
In the case of a periodic campaign, if the campaign ID of the parent campaign is specified, the cards will get deleted for the child campaigns as well.
platforms:
type: array
items:
type: string
enum: [ANDROID, IOS, WEB, android, ios, web]
description: |
Specify platforms to delete cards from. If omitted, the cards specified for deletion will be deleted from all the platforms they are associated with.
Allowed Values: ANDROID, IOS, WEB
description: |
You must provide either 'uid' or 'unique_id'.
#### Generating unique_id
The `unique_id` refers to the device identifier and is platform-specific.
* [Android](https://moengage.github.io/android-api-reference/core/com.moengage.core/[android-jvm]-mo-e-core-helper/get-mo-engage-device-id.html)
* **iOS**: `MoEngageSDKCore.getMoEngageDeviceId(completionHandler: @escaping UserInfoHandler)`
# --- Response & Component Schemas ---
CardAction:
type: object
properties:
type:
type: string
enum: [screenName, deepLink, richLanding]
description: |
This field contains information about the different action types returned within the `cards` object. Supported Values: `screenName`, `deepLink`, and `richLanding`.
name:
type: string
enum: [navigate]
description: This field contains the name assigned to the action.
value:
type: string
description: |
This field contains the URL or screen to which the user would be redirected upon tapping the card.
kvPairs:
type: object
additionalProperties: true
description: This field contains the parameters for the URL to which the user would be redirected.
description: |
Actions define what happens when the user taps on the card. For more information, refer to [Card Actions](/user-guide/campaigns-and-channels/cards/create/create-a-card-campaign).
CardWidget:
type: object
description: Widgets refer to the UI properties defined for self-handled cards. For more information, refer to [Widgets](/hc/en-us/articles/18920335915284#h_01H9JD2ZKP6ESH6DGV7Y71GX8B).
properties:
id:
type: integer
description: This field refers to the unique identifier for the widget within its container.
type:
type: string
enum: [text, image, button]
description: This field refers to the content type (such as `text`, `image`, and `button`).
content:
type: string
description: This field refers to the content that would be displayed in the widget.
CardContainer:
type: object
description: Containers contain information about the individual UI elements and their properties for self-handled cards.
properties:
id:
type: integer
description: This field refers to the unique identifier for the container.
type:
type: string
enum: [basic, illustration]
description: This field refers to the card type.
style:
type: object
properties:
bgColor:
type: string
description: Background color hex code (e.g., "#4e3db0").
additionalProperties: true
description: This field contains information about the formatting and font styles used for the card containers, such as `bgColor`.
widgets:
type: array
items:
$ref: '#/components/schemas/CardWidget'
description: This field contains information about the widgets used in the card.
actions:
type: array
items:
$ref: '#/components/schemas/CardAction'
description: This field contains information about what should happen when the card is tapped (for the container itself).
CardTemplateData:
type: object
description: This field contains information about the Card Template. For more information, refer to [Template Data](/hc/en-us/articles/18920335915284#h_01H9JCXGM63ZVSPWDZZDPY9MV4).
properties:
type:
type: string
enum: [basic, illustration]
description: This field refers to the template type.
containers:
type: array
items:
$ref: '#/components/schemas/CardContainer'
description: This field contains information about individual UI elements used in the Card.
CardMetaData:
type: object
description: 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](/hc/en-us/articles/18920335915284#h_01H9HSZYQB4T7P812D93BJQE8K).
properties:
cid:
type: string
description: This field contains the unique identifier that denotes the Card.
moe_card_id:
type: string
description: This field is a combination of the `cid` and the `platform`.
moe_campaign_name:
type: string
description: This field contains the name of the Card campaign.
moe_delivery_type:
type: string
enum: ["One Time", "Event Triggered"]
description: This field contains the campaign's delivery type.
moe_campaign_id:
type: string
description: This field contains the unique identifier that denotes the campaign associated with the Card.
CardUserActivity:
type: object
properties:
is_clicked:
type: boolean
description: This field contains a Boolean value and indicates whether the card was clicked.
first_seen:
type: integer
format: int64
description: 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:
type: integer
format: int64
description: This field contains an Integer and indicates when the first card was delivered (time is represented as Epoch timestamp in seconds).
show_count:
type: object
additionalProperties:
type: integer
description: |
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.
description: This field contains information about the user's interaction with the card.
CardDisplayControls:
type: object
description: This field contains information about the display controls set in the card campaign. For more information, refer to [Display Controls](/user-guide/campaigns-and-channels/cards/create/create-a-card-campaign).
properties:
max_times_to_show:
type: integer
description: This field is an Integer and indicates the maximum number of times the card can be shown to a user.
nullable: true
expire_at:
type: integer
format: int64
description: Epoch timestamp when the card expires (alternative field for expiry time).
nullable: true
expire_after_delivered:
type: integer
format: int64
description: This field is an Integer and contains the timestamp of card expiry.
nullable: true
is_pin:
type: boolean
description: This field contains a Boolean value and indicates whether the card has been configured to be pinned at the top.
Card:
type: object
properties:
id:
type: string
description: This field contains information about the Card ID and the platform.
platform:
type: string
enum: [android, ios, web]
description: This field contains the platforms on which the Card is supported.
created_at:
type: integer
format: int64
description: This field contains the Unix epoch that represents when the Card campaign was created.
updated_at:
type: integer
format: int64
description: This field contains the Unix epoch that represents when the Card campaign was updated last.
meta_data:
$ref: '#/components/schemas/CardMetaData'
description: This field contains identifiers for the card campaign, such as the campaign id, card id, and so on.
template_data:
$ref: '#/components/schemas/CardTemplateData'
description: This field contains information about the Card Template.
user_activity:
$ref: '#/components/schemas/CardUserActivity'
description: This field contains information about whether the user has clicked on the card.
display_controls:
$ref: '#/components/schemas/CardDisplayControls'
description: This field contains information about the display controls set in the card campaign.
category:
type: string
description: |
This field contains information about the card category. For more information, refer to [Card Categories](/user-guide/campaigns-and-channels/cards/create/create-a-card-campaign).
FetchCardsResponseData:
type: object
properties:
deleted_card_ids:
type: array
items:
type: string
description: List of card IDs that have been deleted for this user since the last sync.
cards:
type: array
items:
$ref: '#/components/schemas/Card'
description: List of active and updated cards matching the criteria.
FetchCardsResponse:
type: object
properties:
status:
type: boolean
description: Indicates if the request was successful (`true`) or unsuccessful (`false`).
request_id:
type: string
description: Unique identifier for this API request.
data:
$ref: '#/components/schemas/FetchCardsResponseData'
description: This field contains the list of cards that satisfy the search criteria.
nullable: true
error:
type: string
description: Error message if status is false.
nullable: true
title:
type: string
description: Error title if status is false.
nullable: true
description:
type: string
description: Error description if status is false.
nullable: true
code:
type: string
description: Error code if status is false.
nullable: true
DeleteCardsPlatformResult:
type: object
properties:
success:
type: array
items:
type: string
description: List of campaign IDs successfully deleted for this platform.
failed:
type: array
items:
type: string
description: List of campaign IDs that failed to delete for this platform.
invalid:
type: array
items:
type: string
description: List of campaign IDs that do not exist for this platform for the user.
DeleteCardsResponseData:
type: object
properties:
android:
$ref: '#/components/schemas/DeleteCardsPlatformResult'
nullable: true
ios:
$ref: '#/components/schemas/DeleteCardsPlatformResult'
nullable: true
web:
$ref: '#/components/schemas/DeleteCardsPlatformResult'
nullable: true
DeleteCardsResponse:
type: object
properties:
status:
type: boolean
description: This field represents whether the request was successful and contains `true` when the request was successful and `false` otherwise.
request_id:
type: string
description: Unique identifier that denotes the request.
data:
$ref: '#/components/schemas/DeleteCardsResponseData'
description: This field contains the platform-specific results of the delete operation.
nullable: true
title:
type: string
description: This field is present in the response body only when the request is unsuccessful and contains the error type.
nullable: true
description:
type: string
description: This field is present in the response body only when the request is unsuccessful and contains the error description.
nullable: true
code:
type: string
description: This field is present in the response body only when the request is unsuccessful and contains the error code.
nullable: true
error:
type: string
description: Error message if status is false.
nullable: true
ErrorResponse:
type: object
properties:
status:
type: boolean
example: false
error:
type: string
nullable: true
title:
type: string
nullable: true
description:
type: string
nullable: true
code:
type: string
nullable: true
request_id:
type: string
nullable: true
responses:
TooManyRequests:
description: |
Rate Limit Breach. This response is returned when the number of requests per minute has exceeded the rate limit.
headers:
x-ratelimit-limit:
schema: { type: integer }
x-ratelimit-remaining:
schema: { type: integer }
x-ratelimit-reset:
schema: { type: integer }
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
title: "Request limit reached"
description: "This API call has exceeded the rate limit"
code: "KMxkunyz"
InternalServerError:
description: |
Internal Server Error. This response is returned when the system runs into an unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
title: "Internal Server Error"
message: "An unexpected error was encountered while processing this request. Please contact MoEngage Team"
security:
- basicAuth: []