openapi: 3.0.2
info:
  title: GDPR API
  description: The following retrieval and deletion API is made for GDPR and CCPA compliance.
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  contact:
    url: https://mixpanel.com/get-support
  version: 3.0.0
servers:
- url: https://{regionAndDomain}.com/api/app
  description: Mixpanel's application API server.
  variables:
    regionAndDomain:
      default: mixpanel
      enum:
      - mixpanel
      - eu.mixpanel
      - in.mixpanel
      description: "The server location to be used:\n  * `mixpanel` - The default (US) servers used for most projects\n  *\
        \ `eu.mixpanel` - EU servers if you are enrolled in EU Data Residency\n  * `in.mixpanel` - India servers if you are\
        \ enrolled in India Data Residency\n"
security:
- OAuthToken: []
tags:
- name: Cancel a Deletion
  description: Cancels an existing deletion task
- name: Check Status of Deletion
  description: Checks the status of an existing deletion task
- name: Check Status of Retrieval
  description: Checks the status of a data retrieval job
- name: Create a Deletion
  description: Creates a task that specifies a list of users in a particular project to delete
- name: Create a Retrieval
  description: Creates a data retrieval job
paths:
  /data-retrievals/v3.0:
    post:
      parameters:
      - $ref: '#/components/parameters/ProjectToken'
      operationId: create-retrieval
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                distinct_ids:
                  $ref: '#/components/schemas/DistinctIds'
                compliance_type:
                  $ref: '#/components/schemas/ComplianceType'
                disclosure_type:
                  $ref: '#/components/schemas/DisclosureType'
      tags:
      - Create a Retrieval
      summary: Create a Retrieval
      description: Creates a data retrieval job.
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobCreated'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
  /data-retrievals/v3.0/{tracking_id}:
    parameters:
    - $ref: '#/components/parameters/TrackingId'
    - $ref: '#/components/parameters/ProjectToken'
    get:
      operationId: get-retrieval
      tags:
      - Check Status of Retrieval
      summary: Check Status of Retrieval
      description: Checks the status of a data retrieval job
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckRetrievalResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
  /data-deletions/v3.0:
    post:
      parameters:
      - $ref: '#/components/parameters/ProjectToken'
      operationId: create-deletion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                distinct_ids:
                  $ref: '#/components/schemas/DistinctIds'
                compliance_type:
                  $ref: '#/components/schemas/ComplianceType'
      tags:
      - Create a Deletion
      summary: Create a Deletion
      description: Creates a task that specifies a list of users in a project to delete
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobCreated'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
  /data-deletions/v3.0/{tracking_id}:
    parameters:
    - $ref: '#/components/parameters/TrackingId'
    - $ref: '#/components/parameters/ProjectToken'
    get:
      operationId: get-deletion
      tags:
      - Check Status of Deletion
      summary: Check Status of Deletion
      description: Checks the status of an existing deletion task
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckDeletionResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
    delete:
      operationId: delete-deletion
      tags:
      - Cancel a Deletion
      summary: Cancel a Deletion
      description: Cancel a deletion task that is still in progress
      responses:
        '204':
          description: Success
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error that occurred
                  status:
                    type: string
                    enum:
                    - error
components:
  securitySchemes:
    ServiceAccount:
      type: http
      scheme: basic
      description: Service Account
    ProjectSecret:
      type: http
      scheme: basic
      description: Project Secret
    OAuthToken:
      type: http
      scheme: bearer
      description: OAuth Token
  schemas:
    JobCreated:
      title: JobCreated
      description: A JSON response object containing the task_id of the retrieval/deletion job.
      type: object
      additionalProperties: false
      required:
      - status
      - results
      properties:
        status:
          $ref: '#/components/schemas/ResponseStatus'
        results:
          type: object
          properties:
            task_id:
              type: string
              description: The task_id of the retrieval/deletion job.
              example: job-tracking-id
    CheckRetrievalResponse:
      title: CheckRetrievalResponse
      description: A JSON response object containing data about a retrieval job
      type: object
      additionalProperties: false
      required:
      - status
      - results
      properties:
        status:
          $ref: '#/components/schemas/ResponseStatus'
        results:
          type: object
          properties:
            status:
              type: string
              description: The status of the job.
              enum:
              - PENDING
              - STAGING
              - STARTED
              - SUCCESS
              - FAILURE
              - REVOKED
              - NOT_FOUND
              - UNKNOWN
              example: SUCCESS
            results:
              type: string
              description: Link to the export if retrieval job is completed. Will be an empty string if job is incomplete
              example: linktoexportfile.com/9871287366712
            distinct_ids:
              $ref: '#/components/schemas/DistinctIds'
    CheckDeletionResponse:
      title: CheckDeletionResponse
      description: A JSON response object containing data about a data deletion job
      type: object
      additionalProperties: false
      required:
      - status
      - results
      properties:
        status:
          $ref: '#/components/schemas/ResponseStatus'
        results:
          $ref: '#/components/schemas/DeletionJobResult'
    DeletionJobResult:
      title: DeletionJobResult
      description: Details about a deletion job
      type: object
      additionalProperties: false
      required:
      - tracking_id
      - status
      - requesting_user
      - compliance_type
      - project_id
      - date_requested
      - distinct_ids
      properties:
        tracking_id:
          type: string
          description: The tracking id of the deletion job
        status:
          type: string
          description: The status of the job.
          enum:
          - PENDING
          - STAGING
          - STARTED
          - SUCCESS
          - FAILURE
          - REVOKED
          - NOT_FOUND
          - UNKNOWN
          example: SUCCESS
        requesting_user:
          type: string
          description: The user that created the deletion job request
        compliance_type:
          type: string
          description: GDPR or CCPA
        project_id:
          type: number
          description: The id of the project this job is for
        date_requested:
          type: string
          description: The timestamp when the deletion job was requested
        distinct_ids:
          $ref: '#/components/schemas/DistinctIds'
      example:
        tracking_id: job tracking_id
        status: SUCCESS
        requesting_user: user@mail.com
        compliance_type: GDPR
        project_id: 12345
        date_requested: YYYY-MM-DDTHH:MM:SS
        distinct_ids:
        - distinct_id_1
        - distinct_id_2
    ResponseStatus:
      type: string
      description: The status of the response
      example: ok
    DistinctIds:
      type: array
      items:
        type: string
        description: Distinct IDs involved in the request
      example:
      - distinct_id_1
      - distinct_id_2
      - distinct_id_3
    ComplianceType:
      type: string
      description: Select CCPA or GDPR. Default is GDPR.
    DisclosureType:
      type: string
      description: Only required if compliance_type = CCPA. Can be Data, Categories, or Sources. Default is Data.
  parameters:
    ProjectToken:
      name: token
      in: query
      schema:
        type: string
      description: Your project token
      required: true
    TrackingId:
      name: tracking_id
      in: path
      schema:
        type: string
      description: The task ID shown in the response
      required: true