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: []