openapi: 3.0.3
info:
  title: MoEngage GDPR / CCPA API
  description: |
    API to create or update user rights for **GDPR** (General Data Protection Regulation) or **CCPA** (California Consumer Privacy Act) compliance, including the right to erase personal data.
  version: '1.0'
servers:
  # Updated server configuration based on best practice for API playground enablement.
  - url: 'https://api-{dc}.moengage.com/v1'
    description: MoEngage API Server
    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: GDPR
    description: Manage user data requests for GDPR and CCPA compliance.
security:
  - basicAuth: []
paths:
  /opengdpr_requests/{appId}:
    post:
      tags:
        - GDPR
      summary: Submit a GDPR / CCPA Data Request
      description: |
        GDPR or CCPA API ensures all the rights of users are created or updated for GDPR or CCPA compliance. You can erase the personal data of specific users as defined under GDPR using the Erase API.
        
        For more details on compliance with MoEngage, refer to [GDPR-Implementation](/user-guide/data/privacy/gdpr) and [CCPA-Implementation](/user-guide/data/privacy/ccpa).
        

      operationId: submitGdprRequest
      x-mint:
        # Request Limitations (moved from previous response, still relevant here)
        content: |
          <Warning>
          **Warning:** Multiple users **cannot** be deleted using this API in a single payload. If an email ID associated with multiple users is passed for an erasure request, **all** associated users will be deleted.
          </Warning>
          #### Rate Limit
          
          The maximum limit per request is **100 KB**. The maximum payload size is **128 KB**.
          
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            type: string
          description: |
            This is your MoEngage account's Workspace ID that must be included in the request. You can find your Workspace ID in the following navigation on the dashboard: Revamped UI: **Settings** > **Account** > **APIs** > **Workspace ID**
          example: 'YOUR_WORKSPACE_ID_XXXX'
      requestBody:
        description: |
          The GDPR/CCPA request payload, containing the type of request and the user identities.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GdprRequest'
            examples:
              GDPR Erasure Request:
                summary: GDPR Erasure Request
                value:
                  request_type: "erasure"
                  submitted_time: "2018-10-05T15:00:00Z"
                  identities:
                    - identity_type: "email"
                      identity_value: "johndoe@example.com"
                  api_version: "1.0"
      responses:
        '200':
          description: Success. This response is returned when the request is processed successfully. 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GdprSuccessResponse'
              example:
                status: success
                message: Your request has been accepted and will be processed soon.
                request_id: 'a7551968-d5d6-44b2-9831-815ac9017798'
        '400':
          description: Bad Request. This response is returned when the required parameters are missing from the request, attributes are not found, or incorrect values are passed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GdprError400Response'
              examples:
                MissingRequestType:
                  summary: Missing request_type
                  value:
                    status: fail
                    error:
                      attribute: request_type
                      message: request_type is not found in the payload
                      type: MissingAttributeError
                      request_id: zuMJjxAS
                MissingIdentities:
                  summary: Missing identities
                  value:
                    status: fail
                    error:
                      attribute: identities
                      message: identities is not found in the payload
                      type: MissingAttributeError
                      request_id: OzqWFuri
        '401':
          description: Unauthorized. This response is returned when the request does not have valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GdprError401Response'
        '403':
          description: Account Blocked. This response is returned when your MoEngage account is suspended or blocked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GdprError403Response'
              examples:
                BlockedClient:
                  summary: Account Blocked
                  value:
                    status: fail
                    error:
                      message: Your account is suspended. Please contact MoEngage team.
                      type: BlockedClient
                      request_id: ofHUEaEQ
                AccountSuspended:
                  summary: Account Suspended
                  value:
                    status: fail
                    error:
                      message: Your account is suspended. Please contact MoEngage team.
                      type: Account Suspended
                      request_id: gqJvCNYu
                AccountTemporarilySuspended:
                  summary: Account Temporarily Suspended
                  value:
                    status: fail
                    error:
                      message: Your account is temporarily suspended. Please contact MoEngage team.
                      type: Account Temporarily Suspended
                      request_id: ssSJjoyD
        '413':
          description: Payload Size Exceeded. This response is returned when the payload size exceeds 128 KB.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GdprError413Response'
        '415':
          description: Unsupported Media Type. This response is returned when the content type is not supported.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GdprError415Response'
        '429':
          description: Rate Limit Breach. This response is returned when the number of requests has exceeded the rate limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GdprError429Response'
        '500':
          description: Internal Server Error. This response is returned when the system runs into an unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GdprError500Response'
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 **Data** tile.

        For more information on authentication and getting your credentials, refer [here](https://www.moengage.com/docs/api/introduction#getting-your-credentials).
  schemas:
    GdprRequest:
      type: object
      required:
        - request_type
        - submitted_time
        - identities
        - api_version
      description: The main object representing a GDPR or CCPA compliance request.
      properties:
        request_type:
          type: string
          description: This is used to request for GDPR details or request to erase the GDPR details
          example: erasure
        submitted_time:
          type: string
          format: date-time
          description: This identifies the time when the request was sent.
          example: '2018-10-05T15:00:00Z'
        identities:
          type: array
          description: This provides the details of the user, such as email address, phone number, and so on.
          items:
            $ref: '#/components/schemas/UserIdentity'
        api_version:
          type: string
          description: This identifies the API version used to send the GDPR request.
          example: '1.0'
    UserIdentity:
      type: object
      description: An object representing a user's identity detail.
      properties:
        identity_type:
          type: string
          description: 'This field denotes the key based on which the user has to be deleted.'
          enum:
            - ID
            - user_secondary_id
            - email
            - mobile
            - google_advertising_id
            - advertising_identifier
          example: email
        identity_value:
          type: string
          description: This field denotes the value of the identity_type.
          example: johndoe@example.com
    GdprSuccessResponse:
      type: object
      description: Standard successful response object for a submitted GDPR request.
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          description: A human-readable message confirming the request was accepted.
          example: Your request has been accepted and will be processed soon.
        request_id:
          type: string
          format: uuid
          description: A unique ID generated for the submitted request.
          example: 'a7551968-d5d6-44b2-9831-815ac9017798'
    GdprError400Response:
      type: object
      description: This response is returned when the required parameters are missing from the request, attributes are not found, or incorrect values are passed.
      properties:
        status:
          type: string
          example: fail
        error:
          type: object
          description: Contains the error details.
          properties:
            attribute:
              type: string
              example: request type
            message:
              type: string
              description: A human-readable message confirming the request was not accepted.
              example: request_type is not found in the payload. 
            type:
              type: string
              example: MissingAttributeError
            request_id: 
              type: string
              example: zuMJjxAS
    GdprError401Response:
      type: object
      description: This response is returned when the request does not have valid authentication credentials.
      properties:
        status:
          type: string
          example: fail
        error:
          type: object
          description: Contains the error details.
          properties:
            message:
              type: string
              description: A human-readable message confirming the request was not accepted.
              example: No identity information found. 
            type:
              type: string
              example: Authentication required
            request_id: 
              type: string
              example: IzbhlLyG
    GdprError403Response:
      type: object
      description: This response is returned when your MoEngage account is suspended or blocked.
      properties:
        status:
          type: string
          example: fail
        error:
          type: object
          description: Contains the error details.
          properties:
            message:
              type: string
              description: A human-readable message confirming the request was not accepted.
              example: Your account is suspended. Please contact MoEngage team. 
            type:
              type: string
              example: BlockedClient
            request_id: 
              type: string
              example: ofHUEaEQ
    GdprError413Response:
      type: object
      description: This response is returned when the payload size exceeds 128 KB.
      properties:
        status:
          type: string
          example: fail
        error:
          type: object
          description: Contains the error details.
          properties:
            message:
              type: string
              description: A human-readable message confirming the request was not accepted.
              example: Payload can not exceed 128KB. 
            type:
              type: string
              example: Payload too large
            request_id: 
              type: string
              example: VFzDwhwt
    GdprError415Response:
      type: object
      description: This response is returned when the content type is not supported.
      properties:
        status:
          type: string
          example: fail
        error:
          type: object
          description: Contains the error details.
          properties:
            message:
              type: string
              description: A human-readable message confirming the request was not accepted.
              example: Content type is not supported 
            type:
              type: string
              example: Unsupported media type
            request_id: 
              type: string
              example: SgBQfKJh
    GdprError429Response:
      type: object
      description: This response is returned when the number of requests has exceeded the rate limit.
      properties:
        status:
          type: string
          example: fail
        error:
          type: object
          description: Contains the error details.
          properties:
            message:
              type: string
              description: A human-readable message confirming the request was not accepted.
              example: Rate limits for customers exceeded. Please Try After Some Time 
            type:
              type: string
              example: Rate Limits Exceeded
            request_id: 
              type: string
              example: onqucLYL
    GdprError500Response:
      type: object
      description: This response is returned when the system runs into an unexpected error.
      properties:
        status:
          type: string
          example: fail
        error:
          type: object
          description: Contains the error details.
          properties:
            message:
              type: string
              description: A human-readable message confirming the request was not accepted.
              example: An unexpected error was encountered while processing this request. Please contact MoEngage Team 
            type:
              type: string
              example: Server Error
            request_id: 
              type: string
              example: KovrwJiF
# --- Start of Content Added to the End of the Document (as Accordion) ---
x-mint-global-content: |
  # FAQs
  <Accordion>
    <Accordion.Item title="Can multiple users be deleted using this API?">
      Multiple users cannot be deleted using this API in a single payload.
    </Accordion.Item>
    <Accordion.Item title="What is the maximum size of the request payload?">
      The maximum payload size is **128 KB**. If this limit is exceeded, a 413 error response will be sent.
    </Accordion.Item>
    <Accordion.Item title="What happens when an email ID that is associated with multiple users is passed for deletion using this API?">
      If multiple users have the same email ID and that email ID is passed in the payload for an erasure request, **all** the users associated with the email ID will be deleted.
    </Accordion.Item>
  </Accordion>
# --- End of Content Added to the End of the Document ---