Osano Dsar API

openapi: 3.2.0
info:
  title: Osano API Reference Dsar API
  version: 1.0.0
  description: '# Introduction

    This is the Osano API. Use of this API is subject to the Osano API Terms of Service.


    # Authentication

    The Osano API uses API keys to authenticate requests that are generated on a per-user basis. All calls require a valid, unexpired API key.


    API keys may be generated within the [Osano settings -> API Keys](https://my.osano.com/api-keys) page. You must be an admin or have the correct privileges to generate an API key.


    Once generated, the API key should be included in the `x-osano-api-key` header of all requests.  For example:


    ```

    curl --header ''x-osano-api-key: <API_KEY>'' https://api.osano.com/v1/<API_PATH>

    ```

    # Pagination, Limits, and Sorting

    Except where noted, all "list" resources will be sorted in descending order by creation time, and this may not be changed.  The number of results returned may be controlled via the limit param, but may not exceed 500.


    Within the response of each "list" API call, there will be a "next" field, which represents the pagination token.  This token may be added as a query parameter, i.e. ?next=<...> to retrieve subsequent pages of the same resource.

    '
  x-logo:
    url: https://www.osano.com/hubfs/Imported%20images/Logo.svg
    altText: Osano
servers:
- url: https://api.osano.com
  description: Production API
security:
- ApiKeyAuth: []
tags:
- name: dsar
  x-displayName: Subject Rights
  description: Manage subject rights requests and data subject access requests
paths:
  /v1/subject-rights/request-types:
    get:
      summary: List Subject Rights Request Types
      description: List standard Subject Rights Request Types and their applicable privacy laws.
      tags:
      - dsar
      operationId: getRequestTypes
      parameters:
      - name: country
        required: false
        in: query
        description: ISO 3166-1 alpha-2 country code.
        schema:
          type: string
          minLength: 2
          maxLength: 2
          pattern: ^[A-Za-z]{2}$
      - name: privacyLawName
        required: false
        in: query
        description: Case-insensitive privacy law name filter.
        schema:
          type: string
          maxLength: 255
      - name: requestType
        required: false
        in: query
        description: Case-insensitive request type filter.
        schema:
          type: string
          maxLength: 255
      - name: category
        required: false
        in: query
        description: Case-insensitive request type category filter.
        schema:
          type: string
          maxLength: 255
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestTypeList'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/subject-rights/requests:
    get:
      summary: List Subject Rights Requests
      description: Query for Subject Rights Requests.  Results are sorted in descending order by creation time.  The number of results returned may be controlled via the limit param, but may not exceed 500.  The "next" object in the response may be used to retrieve subsequent pages of the same resource.
      tags:
      - dsar
      operationId: getDsars
      parameters:
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/nextTokenParam'
      - $ref: '#/components/parameters/afterParam'
      - $ref: '#/components/parameters/dsarSourceParam'
      - $ref: '#/components/parameters/dsarStatusParam'
      - $ref: '#/components/parameters/dsarRequestTypeParam'
      - $ref: '#/components/parameters/formIdParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DsarResponseList'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      summary: Create New Subject Rights Request(s)
      description: Create one or more Subject Rights Requests.  The maximum number of requests that may be created in a single call is 100.  Requests created through this API never send verification emails, regardless of initial status.  If the request is successful, the response will contain a list of the created requests.
      tags:
      - dsar
      operationId: createDsars
      requestBody:
        description: The Subject Rights Request(s) to be created.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DsarList'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DsarResponseList'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/subject-rights/requests/{dsarId}:
    get:
      summary: Return Detailed Subject Rights Request
      description: Get a detailed Subject Rights Request by ID.
      tags:
      - dsar
      operationId: getDsar
      parameters:
      - name: dsarId
        required: true
        in: path
        description: The identifier of the Subject Rights Request to return.
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DsarResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      summary: Update Subject Rights Request
      description: Update metadata about a Subject Rights Request as specified.  A partial update may be performed.
      tags:
      - dsar
      operationId: updateDsar
      parameters:
      - name: dsarId
        required: true
        in: path
        description: The identifier of the Subject Rights Request to be updated.
        schema:
          type: string
      requestBody:
        description: Object containing the fields to be updated.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DsarUpdate'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DsarResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/subject-rights/requests/{dsarId}/identification:
    post:
      summary: Update Identification Photo
      description: Updates the file used for Identity Verification within the Osano platform.  It should be an image.
      tags:
      - dsar
      operationId: updateIdentityFile
      parameters:
      - name: dsarId
        required: true
        in: path
        description: The identifier of the Subject Rights Request to be updated.
        schema:
          type: string
      requestBody:
        content:
          image/webp:
            schema:
              type: string
              format: binary
          image/jpeg:
            schema:
              type: string
              format: binary
          image/png:
            schema:
              type: string
              format: binary
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '204':
          description: Success
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/subject-rights/requests/{requestId}/summaries:
    get:
      summary: Get Request Summaries
      description: Query what summaries are available for this DSAR request before they are packaged and sent.
      tags:
      - dsar
      operationId: getRequestSummaries
      parameters:
      - name: requestId
        required: true
        in: path
        description: The identifier of the Subject Rights Request
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  requestId:
                    type: string
                  summaries:
                    type: array
                    items:
                      type: object
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/subject-rights/requests/{requestId}/summary-notification:
    get:
      summary: Get Summary Notification
      description: 'Retrieve information about a summary notification by request ID, including the archive status and metadata.


        This endpoint returns metadata about the notification package (PDF/ZIP archive) that was sent to the requestor, including:

        - The write status of the archive (NONE, WRITTEN, WRITE_ERROR)

        - The archive file name and type

        - When the summary was created

        - List of summary entries included in the archive

        '
      tags:
      - dsar
      operationId: getSummaryNotification
      parameters:
      - name: requestId
        required: true
        in: path
        description: The identifier of the Subject Rights Request
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - dsarSummaryId
                - requestId
                - writeStatus
                - summaryCreated
                - summaryEntries
                properties:
                  dsarSummaryId:
                    type: string
                    description: The unique identifier for this summary notification
                  requestId:
                    type: string
                    description: The identifier of the Subject Rights Request
                  writeStatus:
                    type: string
                    enum:
                    - NONE
                    - WRITTEN
                    - WRITE_ERROR
                    description: The status of the archive write operation
                  archiveFileName:
                    type:
                    - string
                    - 'null'
                    description: The name of the archive file if it has been written
                  archiveFileType:
                    type:
                    - string
                    - 'null'
                    description: The MIME type of the archive file
                  summaryCreated:
                    type: string
                    format: date-time
                    description: When the summary notification was created
                  summaryEntries:
                    type: array
                    description: List of all summary entries included in this notification archive
                    items:
                      type: object
                      required:
                      - dsarSummaryEntryId
                      - fileName
                      - fileType
                      - manual
                      - created
                      properties:
                        dsarSummaryEntryId:
                          type: number
                          description: The unique identifier for this summary entry
                        fileName:
                          type: string
                          description: The name of the summary file
                        fileType:
                          type: string
                          description: The MIME type of the summary file
                        manual:
                          type: boolean
                          description: Whether this summary was manually uploaded (true) or automatically generated (false)
                        created:
                          type: string
                          format: date-time
                          description: When this summary entry was created
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      summary: Send Summary Notification
      description: 'Package and send all summaries for this DSAR request. This also generates a PDF summary containing automated data discovery results formatted as tables (by data store) and manually uploaded files, in addition to a ZIP archive containing all summary files plus the PDF.

        Subsequent POST requests to this endpoint for the DSAR request will do nothing, as the summaries have already been packaged and sent.

        '
      tags:
      - dsar
      operationId: sendSummaryNotification
      parameters:
      - name: requestId
        required: true
        in: path
        description: The identifier of the Subject Rights Request
        schema:
          type: string
      responses:
        '200':
          description: "Success - The summary notification has been packaged and sent. \n\nA ZIP archive containing a PDF summary and all associated files has been generated and delivered to the requestor.\n"
          content:
            application/json:
              schema:
                type: object
                required:
                - dsarSummaryId
                - requestId
                - writeStatus
                - summaryCreated
                - summaryEntries
                properties:
                  dsarSummaryId:
                    type: string
                    description: The unique identifier for this summary notification
                  requestId:
                    type: string
                    description: The identifier of the Subject Rights Request
                  writeStatus:
                    type: string
                    enum:
                    - NONE
                    - WRITTEN
                    - WRITE_ERROR
                    description: The status of the archive write operation
                  archiveFileName:
                    type:
                    - string
                    - 'null'
                    description: The name of the archive file if it has been written
                  archiveFileType:
                    type:
                    - string
                    - 'null'
                    description: The MIME type of the archive file
                  summaryCreated:
                    type: string
                    format: date-time
                    description: When the summary notification was created
                  summaryEntries:
                    type: array
                    description: List of all summary entries included in this notification archive
                    items:
                      type: object
                      required:
                      - dsarSummaryEntryId
                      - fileName
                      - fileType
                      - manual
                      - created
                      properties:
                        dsarSummaryEntryId:
                          type: number
                          description: The unique identifier for this summary entry
                        fileName:
                          type: string
                          description: The name of the summary file
                        fileType:
                          type: string
                          description: The MIME type of the summary file
                        manual:
                          type: boolean
                          description: Whether this summary was manually uploaded (true) or automatically generated (false)
                        created:
                          type: string
                          format: date-time
                          description: When this summary entry was created
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                noSummaries:
                  value:
                    message: No summaries found for this request
                  summary: No summaries available to package
        '404':
          description: Not Found - The specified Subject Rights Request does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFound:
                  value:
                    message: Subject Rights Request not found
                  summary: Request ID does not exist
        '409':
          description: Conflict - The summary notification has already been sent for this request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                alreadySent:
                  value:
                    message: Summary notification has already been sent
                  summary: Notification already sent
  /v1/subject-rights/requests/{requestId}/activity-log:
    post:
      summary: Create Activity Log Entry
      description: Create an offline activity log entry for a specific Subject Rights request
      tags:
      - dsar
      operationId: postRequestActivityLog
      parameters:
      - name: requestId
        required: true
        in: path
        description: The identifier of the Subject Rights request
        schema:
          type: string
      requestBody:
        description: The activity log entry to create
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivityLogEntry'
      responses:
        '204':
          description: Success
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ApplicableLaw:
      type: object
      additionalProperties: false
      required:
      - name
      - abbreviation
      - effectiveDate
      - jurisdictions
      properties:
        name:
          type: string
        abbreviation:
          type:
          - string
          - 'null'
        effectiveDate:
          type: string
          format: date-time
        jurisdictions:
          type: array
          items:
            $ref: '#/components/schemas/Jurisdiction'
    RequestType:
      type: object
      additionalProperties: false
      required:
      - requestType
      - requestTypeCategory
      - applicableLaws
      properties:
        requestType:
          type: string
        requestTypeCategory:
          type: string
        applicableLaws:
          type: array
          items:
            $ref: '#/components/schemas/ApplicableLaw'
    Jurisdiction:
      type: object
      additionalProperties: false
      required:
      - country
      properties:
        country:
          type: string
        territory:
          type: string
    DsarUpdate:
      type: object
      additionalProperties: true
      properties:
        status:
          type: string
          enum:
          - PENDING_EMAIL_VERIFICATION
          - PENDING_IDENTITY_VERIFICATION
          - IN_PROGRESS
          - PENDING_APPEAL
          - COMPLETED
          - REJECTED
          - REJECTED_AUTO
          - IN_REVIEW
        notes:
          type: string
          maxLength: 500
        notify:
          type: boolean
          default: true
          description: When set to true and status is COMPLETED or REJECTED, an email notification will be sent to the requestor. Defaults to true when status is COMPLETED or REJECTED, otherwise defaults to false.
        content:
          type:
          - string
          - 'null'
          maxLength: 10000
          description: Optional completion or rejection message to be emailed to the requestor. When status is COMPLETED or REJECTED, this message will be used as the completionMessage or rejectionReason in the notification. If omitted, the email notification handler will use a configured template. This message will be added to the portal conversation.
        rejectionReasonCode:
          type: string
          description: Optional rejection reason code. Only applicable when status is REJECTED. Used to select a specific rejection template for the notification email.
          enum:
          - TECHNICALLY_INFEASIBLE
          - REJECTED_APPEAL
          - UNCOVERED_GEO
          - DUPLICATE
          - UNFOUNDED
          - OTHER
          - IDENTITY_NOT_VERIFIED
    RequestTypeList:
      type: object
      additionalProperties: false
      required:
      - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/RequestType'
    ActivityLogEntry:
      type: object
      additionalProperties: false
      required:
      - note
      properties:
        note:
          type: string
          description: The note or description of the activity
        user:
          type: string
          description: The user who performed the action (defaults to API user if not provided)
        timestamp:
          type: string
          format: date-time
          description: When the action occurred (defaults to current timestamp if not provided)
    DsarList:
      type: array
      maxItems: 100
      items:
        $ref: '#/components/schemas/Dsar'
    ErrorResponse:
      type: object
      additionalProperties: true
      properties:
        message:
          type: string
    DsarResponse:
      type: object
      additionalProperties: false
      required:
      - dsarId
      - status
      - requestType
      - requestSource
      - due
      - created
      properties:
        dsarId:
          type: string
        status:
          type: string
        requestType:
          type: string
        requestSource:
          type: string
        notes:
          type: string
        dsarDetails:
          type: object
        due:
          type: string
          format: date-time
        created:
          type: string
          format: date-time
        form:
          type: object
          properties:
            formId:
              type: integer
            formName:
              type: string
    Dsar:
      type: object
      additionalProperties: false
      required:
      - formId
      - requestType
      - status
      - dsarDetails
      properties:
        formId:
          type: integer
        requestType:
          type: string
        status:
          type: string
        due:
          type: string
          format: date-time
        lastUpdated:
          type: string
          format: date-time
        lastUpdatedBy:
          type: string
          format: email
          minLength: 5
          maxLength: 100
        notes:
          type: string
          maxLength: 500
        notifyEmail:
          type: boolean
          default: false
          description: When set to true, an email notification will be sent to the requestor for the appropriate lifecycle event based on the initial status. Defaults to false.
        rejectionReasonCode:
          type: string
          enum:
          - TECHNICALLY_INFEASIBLE
          - REJECTED_APPEAL
          - UNCOVERED_GEO
          - DUPLICATE
          - UNFOUNDED
          - OTHER
          - IDENTITY_NOT_VERIFIED
          description: The reason code for the rejection. Only valid when status is REJECTED.
        dsarDetails:
          type: object
          additionalProperties: true
          required:
          - email
          properties:
            email:
              type: string
              format: email
              minLength: 5
              maxLength: 100
            given-name:
              type: string
            family-name:
              type: string
    DsarResponseList:
      type: object
      additionalProperties: false
      required:
      - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/DsarResponse'
        next:
          type: string
          description: A token which may be appended to subsequent requests to retrieve the next page of results, i.e. ?next=...
  parameters:
    nextTokenParam:
      name: next
      required: false
      in: query
      description: The pagination token from the previous request.
      schema:
        type: string
    afterParam:
      name: after
      required: false
      in: query
      description: Specify UTC date and time in ISO-8601 format (e.g. 2021-01-01T00:00:00Z) to filter items created after this date.
      schema:
        type: string
    dsarSourceParam:
      name: source
      required: false
      in: query
      description: Source filter for the request. Must be one of ADMIN, AGENT_WEB, API, CMP, CSV, EMAIL_INTAKE, or WEB.
      schema:
        type: string
        enum:
        - ADMIN
        - AGENT_WEB
        - API
        - CMP
        - CSV
        - EMAIL_INTAKE
        - WEB
    dsarStatusParam:
      name: status
      required: false
      in: query
      description: Status filter for the request. Must be one of PENDING_EMAIL_VERIFICATION, PENDING_IDENTITY_VERIFICATION, IN_PROGRESS, IN_REVIEW, PENDING_APPEAL, COMPLETED, REJECTED, or REJECTED_AUTO.
      schema:
        type: string
        enum:
        - PENDING_EMAIL_VERIFICATION
        - PENDING_IDENTITY_VERIFICATION
        - IN_PROGRESS
        - IN_REVIEW
        - PENDING_APPEAL
        - COMPLETED
        - REJECTED
        - REJECTED_AUTO
    dsarRequestTypeParam:
      name: requestType
      required: false
      in: query
      description: Request type filter for the request. Must be one of DELETE, CORRECT, SUMMARIZE, DO_NOT_SELL, OPT_OUT, LIMIT_USE, OTHER, PORTABILITY, or CUSTOM_[1-5]
      schema:
        type: string
        enum:
        - DELETE
        - CORRECT
        - SUMMARIZE
        - DO_NOT_SELL
        - OPT_OUT
        - LIMIT_USE
        - OTHER
        - PORTABILITY
        - CUSTOM_1
        - CUSTOM_2
        - CUSTOM_3
        - CUSTOM_4
        - CUSTOM_5
    formIdParam:
      name: formId
      required: false
      in: query
      description: Form identifier through which the Subject Rights Request was made.
      schema:
        type: integer
        format: int32
    limitParam:
      name: limit
      required: false
      in: query
      description: The number of items to return.
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 500
        default: 100
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-osano-api-key
x-tagGroups:
- name: General
  tags:
  - cmp
  - cmpRules
  - connectors
  - dsar
  - dataDiscovery
  - dsarActionItems
  - subjectRightsPortal
  - customerInsights