---
openapi: "3.0.0"
info:
  version: 1.0.4
  title: "Redact API"
  description: Nexmo provides [Redact API](https://developer.nexmo.com/redact/overview) to help organisations meet their privacy compliance obligations. Redact API allows you to redact private information on demand, allowing you to meet your own compliance needs.
  contact:
    name: Nexmo DevRel
    email: devrel@nexmo.com
    url: "https://developer.nexmo.com/"
servers:
  - url: https://api.nexmo.com/v1/redact
paths:
  /transaction:
    post:
      summary: Redact a specific message
      operationId: redact-message
      description: ""
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RedactTransaction"
      responses:
        "204":
          description: "Success"
        "401":
          description: "Authentication failure"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorUnauthorized"
        "403":
          description: "Authorisation denied"
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ErrorPrematureRedaction"
                  - $ref: "#/components/schemas/ErrorUnprovisioned"
        "404":
          description: "No such record"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInvalidId"
        "422":
          description: "Invalid JSON body"
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ErrorInvalidJson"
                  - $ref: "#/components/schemas/ErrorUnsupportedProduct"
        "429":
          description: "Rate Limited"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorThrottled"

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
  schemas:
    ErrorUnsupportedProduct:
      description: Unsupported Product
      type: object
      required:
        - type
        - title
        - detail
        - instance
      properties:
        type:
          type: string
          description: Link to error / remediation options
          example: https://developer.nexmo.com/api-errors/redact#invalid-product
        title:
          type: string
          description: Generic error message
          example: Invalid Product
        detail:
          type: string
          description: Additional information about the error
          example: No product corresponding to supplied string sms2!
        instance:
          type: string
          description: Internal Trace ID
          example: bf0ca0bf927b3b52e3cb03217e1a1ddf

    ErrorPrematureRedaction:
      description: Premature Redaction
      type: object
      required:
        - type
        - title
        - detail
        - instance
      properties:
        type:
          type: string
          description: Link to error / remediation options
          example: https://developer.nexmo.com/api-errors/redact#premature-redaction
        title:
          type: string
          description: Generic error message
          example: Premature Redaction
        detail:
          type: string
          description: Additional information about the error
          example: You must wait 60 minutes before redacting ID '0A000000B0C9A1234'
        instance:
          type: string
          description: Internal Trace ID
          example: bf0ca0bf927b3b52e3cb03217e1a1ddf

    ErrorUnprovisioned:
      description: Unprovisioned
      type: object
      required:
        - type
        - title
        - detail
        - instance
      properties:
        type:
          type: string
          description: Link to error / remediation options
          example: https://developer.nexmo.com/api-errors#unprovisioned
        title:
          type: string
          description: Generic error message
          example: Authorisation error
        detail:
          type: string
          description: Additional information about the error
          example: User=ABC123 is not provisioned to redact product=SMS
        instance:
          type: string
          description: Internal Trace ID
          example: bf0ca0bf927b3b52e3cb03217e1a1ddf

    ErrorUnauthorized:
      type: object
      required:
        - type
        - error_title
      properties:
        type:
          type: string
          description: Machine readable error type
          example: UNAUTHORIZED
        error_title:
          type: string
          description: Error title
          example: Unauthorized

    ErrorInvalidJson:
      description: Invalid JSON
      type: object
      required:
        - type
        - title
        - detail
        - instance
      properties:
        type:
          type: string
          description: Link to error / remediation options
          example: https://developer.nexmo.com/api-errors#invalid-json
        title:
          type: string
          description: Generic error message
          example: Invalid JSON
        detail:
          type: string
          description: Additional information about the error
          example: 'Unexpected character (''"'' (code 34)): was expecting comma to separate Object entries'
        instance:
          type: string
          description: Internal Trace ID
          example: bf0ca0bf927b3b52e3cb03217e1a1ddf

    ErrorInvalidId:
      type: object
      required:
        - type
        - title
        - detail
        - instance
      properties:
        type:
          type: string
          description: Link to error / remediation options
          example: https://developer.nexmo.com/api-errors#invalid-id
        title:
          type: string
          description: Generic error message
          example: Invalid ID
        detail:
          type: string
          description: Additional information about the error
          example: ID '0A000000B0C9A1234' could not be found (type=MT)
        instance:
          type: string
          description: Internal Trace ID
          example: bf0ca0bf927b3b52e3cb03217e1a1ddf

    ErrorThrottled:
      type: object
      required:
        - type
        - title
        - detail
        - instance
      properties:
        type:
          type: string
          description: Link to error / remediation options
          example: https://developer.nexmo.com/api-errors/redact#rate-limit
        title:
          type: string
          description: Generic error message
          example: Rate Limit Hit
        detail:
          type: string
          description: Additional information about the error
          example: Please wait, then retry your request
        instance:
          type: string
          description: Internal Trace ID
          example: bf0ca0bf927b3b52e3cb03217e1a1ddf

    RedactTransaction:
      type: object
      required:
        - id
        - product
        - type
      properties:
        id:
          type: string
          description: The transaction ID to redact
        product:
          type: string
          example: sms
          description: Product name that the ID provided relates to
          enum:
            - sms
            - voice
            - number-insight
            - verify
            - verify-sdk
            - messages
        type:
          type: string
          enum:
            - inbound
            - outbound
          example: outbound
          default: outbound
          description: Required if redacting SMS data

x-errors:
  invalid-product:
    description: The provided product is invalid
    resolution: Modify your request to provide a valid product
    link:
      text: View API reference
      url: /api/redact#transaction

  premature-redaction:
    description: There is a 1 hour time period before data can be redacted to allow for all data to propagate through the Nexmo system
    resolution: Wait until the data becomes valid for redaction

  rate-limit:
    description: The request was rate limited
    resolution: The Redact API supports 170 requests per second. Slow down your request rate
