{
  "openapi": "3.0.3",
  "info": {
    "title": "SecuMailer DLP API",
    "version": "0.2"
  },
  "servers": [
    {
      "url": "https://test-public-api.secumail.nl",
      "description": "Acceptance environment"
    },
    {
      "url": "https://public-api.secumail.nl",
      "description": "Production environment"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/dlp": {
      "get": {
        "summary": "Retrieve DLP analysis results",
        "description": "Returns the DLP analysis results for a previously submitted document. The `reference` UUID and `sender`\naddress must match the values used in the original POST request.\n\nPoll this endpoint after uploading the document. Results are available once DLP processing is complete.",
        "operationId": "getDlpResults",
        "parameters": [
          {
            "name": "reference",
            "in": "query",
            "description": "The UUID returned by the POST endpoint.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "c894fda1-61ee-4096-a7c4-cd4b2c364787"
          },
          {
            "name": "sender",
            "in": "query",
            "description": "The sender e-mail address used in the original POST request.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "email"
            },
            "example": "mailbox@domain.com"
          }
        ],
        "responses": {
          "200": {
            "description": "DLP results retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetResponse"
                },
                "examples": {
                  "noViolations": {
                    "summary": "No DLP violations found",
                    "value": {
                      "reference": "c894fda1-61ee-4096-a7c4-cd4b2c364787",
                      "sender": "mailbox@domain.com",
                      "timestamp": 1778045254,
                      "violations": 0,
                      "action": "allow",
                      "documents": {
                        "c894fda1-61ee-4096-a7c4-cd4b2c364787": {
                          "type": "pdf",
                          "violations": 0,
                          "results": {
                            "keywordValues": [],
                            "patternValues": [],
                            "combinationValues": [],
                            "keywordMatches": 0,
                            "patternMatches": 0,
                            "combinationMatches": 0,
                            "event": {
                              "pattern": [],
                              "keyword": [],
                              "combination": []
                            }
                          }
                        }
                      }
                    }
                  },
                  "withViolations": {
                    "summary": "DLP violations detected",
                    "value": {
                      "reference": "665e03739c0b4243e6325b8269fd6253",
                      "sender": "mailbox@domain.com",
                      "timestamp": 1778213465,
                      "violations": 17,
                      "action": "block",
                      "documents": {
                        "665e03739c0b4243e6325b8269fd6253": {
                          "type": "pdf",
                          "violations": 17,
                          "results": {
                            "keywordValues": [
                              "BKR-registratie",
                              "IBAN",
                              "kredietregistratie",
                              "uitkering",
                              "BSN",
                              "TouchID",
                              "CVV"
                            ],
                            "patternValues": [
                              "Creditcard (Visa): /(?<!\\d)4\\d{12}(?:\\d{3})?(?!\\d)/",
                              "Algemene API secret keys (>=32 tekens): /[A-Za-z0-9_-]{32,}/",
                              "Polisnummer (10 cijfers): /[0-9]{10}\\b/"
                            ],
                            "combinationValues": [
                              {
                                "kredietregistratie": 1,
                                "BKR-registratie": 1
                              },
                              {
                                "IBAN": 1,
                                "uitkering": 1
                              }
                            ],
                            "keywordMatches": 8,
                            "patternMatches": 7,
                            "combinationMatches": 2,
                            "event": {
                              "pattern": [
                                {
                                  "Creditcard (Visa)": [
                                    [
                                      "4222222222222"
                                    ]
                                  ]
                                },
                                {
                                  "Algemene API secret keys (>=32 tekens)": [
                                    [
                                      "aaYZ8MdLxbiNkAH5McrTdaXJVVvF1WPl",
                                      "lbBzM1iMY54oROXFuUYCNXYgHAVIB1HO",
                                      "GmPC0XynCxYcaqVAH6Zvo8H3qyJv9q76"
                                    ]
                                  ]
                                },
                                {
                                  "Polisnummer (10 cijfers)": [
                                    [
                                      "1245126199",
                                      "1530093459",
                                      "2222222222"
                                    ]
                                  ]
                                }
                              ],
                              "keyword": [
                                {
                                  "BKR-registratie": 1
                                },
                                {
                                  "IBAN": 2
                                },
                                {
                                  "kredietregistratie": 1
                                },
                                {
                                  "uitkering": 1
                                },
                                {
                                  "BSN": 1
                                },
                                {
                                  "TouchID": 1
                                },
                                {
                                  "CVV": 1
                                }
                              ],
                              "combination": [
                                [
                                  {
                                    "CVV": 1
                                  },
                                  {
                                    "kredietregistratie": 1
                                  },
                                  {
                                    "BKR-registratie": 1
                                  }
                                ],
                                [
                                  {
                                    "CVV": 1
                                  },
                                  {
                                    "kredietregistratie": 1
                                  },
                                  {
                                    "BKR-registratie": 1
                                  },
                                  {
                                    "CVV": 1
                                  },
                                  {
                                    "IBAN": 2
                                  },
                                  {
                                    "uitkering": 1
                                  }
                                ]
                              ]
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "post": {
        "description": "After a successful response the client must PUT the raw `.eml` file to `upload_url` within 5 minutes.",
        "operationId": "requestPresignedUrl",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PostRequest"
              },
              "example": {
                "sender": "mailbox@domain.com"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PostResponse"
                },
                "example": {
                  "reference": "c894fda1-61ee-4096-a7c4-cd4b2c364787",
                  "sender": "mailbox@domain.com",
                  "timestamp": 1778045254
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PostRequest": {
        "required": [
          "sender"
        ],
        "type": "object",
        "properties": {
          "sender": {
            "type": "string",
            "description": "An e-mail address used to identify the specific sender. Must belong to a domain configured for the API key.",
            "format": "email",
            "example": "mailbox@domain.com"
          }
        }
      },
      "PostResponse": {
        "required": [
          "reference",
          "sender",
          "timestamp",
          "upload_url"
        ],
        "type": "object",
        "properties": {
          "reference": {
            "type": "string",
            "description": "UUID assigned by SecuMailer to uniquely identify this DLP request.",
            "format": "uuid",
            "example": "c894fda1-61ee-4096-a7c4-cd4b2c364787"
          },
          "sender": {
            "type": "string",
            "description": "The sender e-mail address as provided in the request.",
            "format": "email",
            "example": "mailbox@domain.com"
          },
          "timestamp": {
            "type": "integer",
            "description": "Unix timestamp (seconds) when SecuMailer received the request.",
            "format": "int64",
            "example": 1778045254
          },
          "upload_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "GetResponse": {
        "required": [
          "documents",
          "reference",
          "sender",
          "timestamp",
          "violations"
        ],
        "type": "object",
        "properties": {
          "reference": {
            "type": "string",
            "description": "UUID identifying this DLP request.",
            "format": "uuid",
            "example": "c894fda1-61ee-4096-a7c4-cd4b2c364787"
          },
          "sender": {
            "type": "string",
            "description": "The sender e-mail address associated with this request.",
            "format": "email",
            "example": "mailbox@domain.com"
          },
          "timestamp": {
            "type": "integer",
            "description": "Unix timestamp (seconds) when the original POST request was received.",
            "format": "int64",
            "example": 1778045254
          },
          "violations": {
            "type": "integer",
            "description": "Total number of DLP violations detected across all analysed documents.",
            "example": 17
          },
          "documents": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/DocumentResult"
            },
            "description": "Map of document identifiers to their individual DLP analysis results.\nKeys are UUIDs corresponding to documents submitted for analysis."
          }
        }
      },
      "DocumentResult": {
        "required": [
          "results",
          "type",
          "violations"
        ],
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "MIME type or document type as determined during analysis.",
            "example": "pdf"
          },
          "violations": {
            "type": "integer",
            "description": "Number of DLP violations detected for this document.",
            "example": 17
          },
          "results": {
            "$ref": "#/components/schemas/DlpResults"
          }
        }
      },
      "DlpResults": {
        "type": "object",
        "properties": {
          "keywordValues": {
            "type": "array",
            "description": "DLP policy keywords triggered in this document.",
            "example": [
              "BSN",
              "CVV"
            ],
            "items": {
              "type": "string"
            }
          },
          "patternValues": {
            "type": "array",
            "description": "DLP regex patterns triggered in this document, each formatted as a human-readable label followed by the pattern expression.",
            "example": [
              "Creditcard (Visa): /(?<!\\d)4\\d{12}(?:\\d{3})?(?!\\d)/"
            ],
            "items": {
              "type": "string"
            }
          },
          "combinationValues": {
            "type": "array",
            "description": "Keyword combinations that triggered a combination rule. Each item is a map of keyword to occurrence count.",
            "example": [
              {
                "IBAN": 1,
                "uitkering": 1
              }
            ],
            "items": {
              "type": "object",
              "additionalProperties": {
                "type": "integer"
              }
            }
          },
          "keywordMatches": {
            "type": "integer",
            "description": "Total number of individual keyword occurrences detected across all keyword rules.",
            "example": 8
          },
          "patternMatches": {
            "type": "integer",
            "description": "Total number of individual pattern occurrences detected across all pattern rules.",
            "example": 7
          },
          "combinationMatches": {
            "type": "integer",
            "description": "Total number of combination rule matches detected.",
            "example": 2
          },
          "event": {
            "$ref": "#/components/schemas/DlpEvent"
          }
        }
      },
      "DlpEvent": {
        "type": "object",
        "properties": {
          "pattern": {
            "type": "array",
            "description": "Each item maps a pattern name to the list of value groups matched by that pattern.",
            "items": {
              "type": "object",
              "additionalProperties": {
                "type": "array",
                "items": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "keyword": {
            "type": "array",
            "description": "Each item maps a keyword to the number of times it was found.",
            "items": {
              "type": "object",
              "additionalProperties": {
                "type": "integer"
              }
            }
          },
          "combination": {
            "type": "array",
            "description": "Each item is a list of keyword-count maps that together triggered a combination rule.",
            "items": {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer"
                }
              }
            }
          }
        },
        "description": "Raw match data broken down by detection type."
      },
      "ErrorResponse": {
        "required": [
          "code",
          "message"
        ],
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code.",
            "example": 403
          },
          "message": {
            "type": "string",
            "description": "Human-readable description of the error.",
            "example": "Forbidden. Domain mismatch."
          }
        }
      },
      "InternalErrorResponse": {
        "required": [
          "code",
          "message"
        ],
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code.",
            "example": 500
          },
          "subcode": {
            "type": "string",
            "example": "E_DYN_001"
          },
          "message": {
            "type": "string",
            "description": "Human-readable description of the error."
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Missing or invalid request parameter",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "missingSender": {
                "summary": "sender field absent from request body",
                "value": {
                  "code": 400,
                  "message": "Missing required field: sender"
                }
              },
              "emptySender": {
                "summary": "sender field present but empty",
                "value": {
                  "code": 400,
                  "message": "Invalid value for field: sender"
                }
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "Request forbidden due to an authentication or configuration error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "noApiKey": {
                "summary": "No API key provided",
                "value": {
                  "code": 403,
                  "message": "Forbidden. No API key provided."
                }
              },
              "misconfiguredMailbox": {
                "summary": "API key has no mailboxes configured",
                "value": {
                  "code": 403,
                  "message": "Forbidden. Misconfigured mailbox."
                }
              },
              "domainMismatch": {
                "summary": "Sender domain not authorised for this API key",
                "value": {
                  "code": 403,
                  "message": "Forbidden. Domain mismatch."
                }
              },
              "domainUserNotFound": {
                "summary": "Domain user record not found",
                "value": {
                  "code": 403,
                  "message": "Forbidden. Domain user not found."
                }
              },
              "noConfig": {
                "summary": "No DLP configuration found for the domain",
                "value": {
                  "code": 403,
                  "message": "Forbidden. No configuration found."
                }
              }
            }
          }
        }
      },
      "MethodNotAllowed": {
        "description": "HTTP method not supported — only GET and POST are accepted",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "code": 405,
              "message": "Method not allowed."
            }
          }
        }
      },
      "InternalServerError": {
        "description": "An unexpected server-side error occurred",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/InternalErrorResponse"
            },
            "example": {
              "code": 500,
              "subcode": "E_DYN_001"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "name": "x-api-key",
        "in": "header"
      }
    }
  },
  "tags": []
}