Submit fraud report

Private pre-release
  • Updated on May 29, 2025
  • Published on May 22, 2025
Prev Next
Post
/v1/feedback/fraud-reports

Submit one or more fraud reports for evaluation and processing.

This pre-release API is currently active for select few customers. Requests to the API URL will not return data if you are not part of the trial. We will expand availability in near future to all customers.

This endpoint accepts a batch of reports and processes each independently. Each report will receive a separate status in the response, enabling partial success scenarios where some reports succeed while others fail.

Response statuses per report

Each item in the reports array of the response will have a status:

  • reported: The fraud report was successfully processed and recorded. The reportId field will contain the ID that was assigned to the report.
  • error: The report could not be processed. The detailsfield will contain the reason, such as:
    • "The categories [...] are not valid."
    • "The specified sessionId was not found."
    • "The verification is in a state that cannot be reported."
    • "A report already exists for this session."
    • "An unexpected error occurred..."
Header parameters
VRF-AUTH-CLIENT
stringRequired

API key

VRF-HMAC-SIGNATURE
stringRequired

Full request path signed with the shared secret key

Body parameters
submitting_several_reports
{
  "reports": [
    {
      "sessionId": "d4f37a0d-2858-4270-aa74-0be2a78cadcb",
      "categories": [
        "document_is_manipulated"
      ],
      "comment": "Right side of the document appears to be cut off"
    },
    {
      "sessionId": "cef3dc5b-4af1-476f-b75d-708dea4b7582",
      "categories": [
        "injected_media"
      ],
      "comment": "Media is injected"
    }
  ]
}
submitting_one_report
{
  "reports": [
    {
      "sessionId": "d4f37a0d-2858-4270-aa74-0be2a78cadcb",
      "categories": [
        "document_is_manipulated"
      ],
      "comment": "Right side of the document appears to be cut off"
    }
  ]
}
Expand All
object

Request body model for submitting one or more fraud reports.

reports
Array of object (FraudReportItem) Required

List of fraud reports to submit.

Min items1
object
sessionId
string (uuid) Required

The unique identifier of the Veriff session being reported.

categories
Array of string Required

List of fraud category codes associated with this report.

Min items1
string

A fraud category code (obtainable from GET /fraud-categories).

Exampledocument_is_manipulated
comment
string | null

Optional additional details or context about the fraud report (max 500 characters).

ExampleDocument corners appear cropped; possible tampering.
Responses
200

Successful Response

reporting_success
{
  "reports": [
    {
      "sessionId": "d4f37a0d-2858-4270-aa74-0be2a78cadcb",
      "reportId": "a565f8b9-9c0a-4e8e-95c4-94c4b51e150e",
      "status": "reported"
    }
  ]
}
reporting_success_and_error
{
  "reports": [
    {
      "sessionId": "d4f37a0d-2858-4270-aa74-0be2a78cadcb",
      "reportId": "a565f8b9-9c0a-4e8e-95c4-94c4b51e150e",
      "status": "reported"
    },
    {
      "sessionId": "cef3dc5b-4af1-476f-b75d-708dea4b7582",
      "reportId": "3a8d086a-bd10-4e66-ba29-a4d2671d0b49",
      "status": "error",
      "details": "The verification is in a state that cannot be reported."
    }
  ]
}
reporting_error
{
  "reports": [
    {
      "sessionId": "cef3dc5b-4af1-476f-b75d-708dea4b7582",
      "reportId": "3a8d086a-bd10-4e66-ba29-a4d2671d0b49",
      "status": "error",
      "details": "The verification is in a state that cannot be reported."
    }
  ]
}
Expand All
object

Response model for fraud report submission, providing both detailed per-item results and summary statistics for the batch operation.

reports
Array of object (FraudReportResponseItem)

Detailed results for each individual report submission, including status and error details if applicable.

object
sessionId
string (uuid) | null

The session ID corresponding to this report result.

reportId
string (uuid) | null

The unique ID assigned to the successfully processed fraud report. Null if processing failed.

status
string

The processing status of this individual report ('reported' or 'error').

Valid values[ "reported", "error" ]
Examplereported
details
string | null

Provides error details if the status is 'error', otherwise null.

ExampleThe verification is in a state that cannot be reported.
processedCount
integer

Total number of reports received and processed in this request batch.

Example2
successCount
integer

Number of reports that were successfully submitted and recorded.

Example1
errorCount
integer

Number of reports that failed validation or processing.

Example1
401

Unauthorized. Possible reasons: invalid API key or signature.

invalidApiKey
{
  "code": "1803",
  "message": "Integration with the API key '6ee9e344-20a6-439d-bf21-b6610db63ad6' was not found."
}
object

Generic error response structure.

code
string

A machine-readable error code indicating the type of error.

message
string

A human-readable message explaining the error.

422

Unprocessable Entity. Input validation failed.

categoriesFieldRequired
{
  "code": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed: reports: Field required"
}
object

Generic error response structure.

code
string

A machine-readable error code indicating the type of error.

message
string

A human-readable message explaining the error.

429

Too Many Requests. Rate limit exceeded.

rateLimitExceeded
{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Limit exceeded: 1000 per minute"
}
object

Generic error response structure.

code
string

A machine-readable error code indicating the type of error.

message
string

A human-readable message explaining the error.

500

Internal Server Error. An unexpected error occurred.

internalServerError
{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}
object

Generic error response structure.

code
string

A machine-readable error code indicating the type of error.

message
string

A human-readable message explaining the error.