MoEngage Cards API

openapi: 3.2.0
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'
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.
security:
- basicAuth: []
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:
  schemas:
    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.
    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.
    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.
    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).
    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'.\n\n#### Generating unique_id\n  The `unique_id` refers to the device identifier and is platform-specific. \n  * [Android](https://moengage.github.io/android-api-reference/core/com.moengage.core/[android-jvm]-mo-e-core-helper/get-mo-engage-device-id.html)\n  * **iOS**: `MoEngageSDKCore.getMoEngageDeviceId(completionHandler: @escaping UserInfoHandler)`\n"
    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.
    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).

            '
    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).

        '
    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'
        ios:
          $ref: '#/components/schemas/DeleteCardsPlatformResult'
        web:
          $ref: '#/components/schemas/DeleteCardsPlatformResult'
    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.
        error:
          type:
          - string
          - 'null'
          description: Error message if status is false.
        title:
          type:
          - string
          - 'null'
          description: Error title if status is false.
        description:
          type:
          - string
          - 'null'
          description: Error description if status is false.
        code:
          type:
          - string
          - 'null'
          description: Error code if status is false.
    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
          - 'null'
          description: This field is an Integer and indicates the maximum number of times the card can be shown to a user.
        expire_at:
          type:
          - integer
          - 'null'
          format: int64
          description: Epoch timestamp when the card expires (alternative field for expiry time).
        expire_after_delivered:
          type:
          - integer
          - 'null'
          format: int64
          description: This field is an Integer and contains the timestamp of card expiry.
        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.
    ErrorResponse:
      type: object
      properties:
        status:
          type: boolean
          example: false
        error:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        code:
          type:
          - string
          - 'null'
        request_id:
          type:
          - string
          - 'null'
    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.
    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. \nAllowed Values: ANDROID, IOS, WEB.\n"
        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'.\n\n#### Generating unique_id\n  The `unique_id` refers to the device identifier and is platform-specific. \n  * [Android](https://moengage.github.io/android-api-reference/core/com.moengage.core/[android-jvm]-mo-e-core-helper/get-mo-engage-device-id.html)\n  * **iOS**: `MoEngageSDKCore.getMoEngageDeviceId(completionHandler: @escaping UserInfoHandler)`\n"
    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.
        title:
          type:
          - string
          - 'null'
          description: This field is present in the response body only when the request is unsuccessful and contains the error type.
        description:
          type:
          - string
          - 'null'
          description: This field is present in the response body only when the request is unsuccessful and contains the error description.
        code:
          type:
          - string
          - 'null'
          description: This field is present in the response body only when the request is unsuccessful and contains the error code.
        error:
          type:
          - string
          - 'null'
          description: Error message if status is false.
  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
    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
    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
  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).

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

    ```

    '