Skip to main content
A guide to the types of issues that can arise during KYC workflows and how to handle them.
Note:
In the FrankieOne v2.0.0 API, an “issue” is a fundamental concept used to communicate problems, errors, or specific outcomes that require attention. Issues can arise from simple input validation errors to complex workflow results that require manual review.

​
The Structure of an Issue

An issue is typically represented as an Issue object, which contains details about what went wrong and where. While the exact structure can vary slightly depending on the context (e.g., a synchronous API error vs. a workflow result), it generally contains the following key fields:
FieldTypeDescription
issuestringHuman-readable description of the problem
issueLocationstringContext/location where the issue was identified (e.g., VALIDATE-entityId)
issueTypestring(Optional) Category for the issue
Example: 400 Bad Request Error Response
{
  "errorCode": "API-0400",
  "errorMsg": "Multiple Errors: See Issues list",
  "details": [
    {
      "issue": "entityId in path must be of type uuid: \"test\"",
      "issueLocation": "VALIDATE-entityId"
    }
  ],
  "requestId": "01HM5XJ7VASZ3EJMB1VQGTBFJ4"
}

​
How Issues are Created

Synchronous errors occur when an API request cannot be fulfilled due to issues like invalid authentication, malformed requests, or server-side problems. The API returns a standard Error object with a relevant HTTP status code (e.g., 400, 401, 500).
FieldDescription
errorCodeUnique FrankieOne code for the error (e.g., AUTH-0002)
errorMsgSummary of the error (e.g., Unauthorized)
detailsArray of Issue objects detailing each problem
Common Error Scenarios:
  • 400 Bad Request: Validation errors (e.g., malformed entityId)
  • 401 Unauthorized: Missing or invalid api_key
  • 404 Not Found: Resource does not exist
  • 5xx Server Error: Internal platform issues
When a workflow runs, the platform performs a series of checks. If any check produces a result that requires attention, a Workflow-Issue object is generated and included in the workflow execution summary.
FieldTypeDescription
issueIdstringUnique identifier for the issue
categorystringBroad classification (e.g., AML, KYC, FRAUD, DOCUMENT)
issuestringSpecific issue type (e.g., SANCTION, NOT_FOUND)
severitystringSeverity level (INFO, REVIEW, BLOCK, WARNING, CRITICAL, ERROR)
isClearedbooleanIndicates if the issue has been manually addressed/resolved
createdAtstringTimestamp when the issue was created
Example: Workflow-Execution-Summary with an Issue
{
  "workflowName": "kyc_onboarding",
  "workflowExecutionId": "01HNE42K1T6JXV41S8W5W8W6X8",
  "status": "REVIEW",
  "issues": [
    {
      "issueId": "01HNE42K2G4S8Z6G8Y4Y7B3A2C",
      "category": "AML",
      "issue": "SANCTION",
      "severity": "CRITICAL",
      "isCleared": false,
      "createdAt": "2024-05-15T02:18:11.365Z"
    }
  ]
}

​
Issue Severity Levels

SeverityDescription
INFOInformational only, no action required
REVIEWRequires manual review before proceeding
BLOCKBlocks workflow completion until resolved
WARNINGIndicates a potential problem, but not blocking
CRITICALSerious issue, typically blocks onboarding
ERRORError state, usually requires technical intervention

​
Workflow Issue Categories

This table lists the general categories that an issue can fall under.
CategoryDescription
AMLAnti-Money Laundering issues.
BAD_DATAIndicates that the data provided is invalid or incorrect.
BIOMETRICSIssues found during a biometrics check.
BLOCKLISTEDThe entity has a hit on a blocklist.
DECEASEDIndicates that the entity is deceased.
DEVICEIssues found during device checks.
DOCUMENTIssues found during a document check.
DUPLICATEIndicates that the entity has duplicates.
EXPIRYIndicates that a process or document for the entity has expired.
FRAUDPossible fraud detected.
IDVIssues found during an Identity Verification (IDV) process.
INFORMATIONALInformational messages that are not issues but are required to be returned.
KYCIssues found during a Know Your Customer (KYC) process.
SYSTEMSystem-level issues.
VERIFYIssues found during a verification process.
VISAIssues found during a visa check.
WATCHLISTIssues found during a watchlist check.
ACTIVITYIssues found during an activity process.

​
Workflow Issue Types & Descriptions

Issue TypeDescription
PEPThe entity has Politically Exposed Person (PEP) hits.
SANCTIONThe entity has sanction hits.
MEDIAThe entity has adverse media hits.
WATCHLISTThe entity has watchlist hits.
INTERNAL_MATCHThe entity matched an internal watchlist.
AML_ISSUEGeneral AML issue.
Issue TypeDescription
BAD_DATA_NAMEName is required but missing or unusable.
BAD_DATA_DOBDate of Birth is required but missing or unusable.
BAD_DATA_ADDRESSAddress is required but missing or unusable.
BAD_DATA_IDID is required but missing or unusable.
BAD_DATA_EMAILEmail is required but missing or unusable.
BAD_DATA_MOBILEMobile is required but missing or unusable.
BAD_DATA_DEVICEDevice is required but missing or unusable.
BAD_DATA_IP_ADDRESSIP Address is required but missing or unusable.
BAD_DATA_EMAIL_ADDRESSEmail Address is required but missing or unusable.
Issue TypeDescription
MATCHED_INTERNALThe entity matched an internal blocklist.
MATCHED_SHAREDThe entity matched a shared blocklist.
MATCHED_EXTERNALThe entity matched an external blocklist.
BLOCKEDGeneral blocklist issue.
Issue TypeDescription
DECEASEDThe person whose data is being verified is deceased.
Issue TypeDescription
DEVICE_FRAUD_MATCHFraud detected on the device.
DEVICE_INVALIDThe device is invalid.
FRAUD_LISTThe entity is on a fraud list.
FRAUD_CHECKFraud detected during checks.
FRAUD_DEVICEDevice fraud detected.
FRAUD_IP_ADDRESSIP address fraud detected.
FRAUD_EMAIL_ADDRESSEmail address fraud detected.
FRAUD_PHONE_NUMBERPhone number fraud detected.
FRAUD_INCOMPLETEThe fraud check was incomplete.
FRAUD_ISSUEGeneral fraud issue.
Issue TypeDescription
DUPLICATEThe entity is a duplicate of another entity.
Issue TypeDescription
REQUIRES_KYCKYC process needs to be re-initiated.
REQUIRES_IDVIDV process needs to be re-initiated.
REQUIRES_AMLAML process needs to be re-initiated.
REQUIRES_VISAVisa process needs to be re-initiated.
Issue TypeDescription
DATA_COMPARISONData comparison issue.
DATA_VALIDATIONData validation issue.
DATA_CONSISTENCYData consistency issue.
VISUAL_AUTHENTICITYVisual authenticity issue.
IMAGE_INTEGRITYImage integrity issue.
COMPROMISED_DOCUMENTDocument is compromised.
LIVENESS_DETECTIONLiveness detection failed.
DOCUMENT_COMPARISONDocument comparison issue.
OCRThe OCR data does not match what was entered by the user.
Issue TypeDescription
CREDIT_HEADERCredit header information was returned as part of a credit agency check.
Issue TypeDescription
PARTIALThe KYC check was only partially successful.
NOT_FOUNDNo match was found for the given data.
Issue TypeDescription
SERVICE_TIMEOUTAll providers have timed out.
SERVICE_ERRORAll providers have returned an error or an internal error has occurred.
Issue TypeDescription
DENY_LISTThe entity matched a visa deny list.
VISA_FAILEDVisa check failed from the provider.
Issue TypeDescription
ACTIVITY_AMLAML-related activity issue.
ACTIVITY_FRAUDFraud-related activity issue.
ACTIVITY_DEVICEDevice-related activity issue.

​
Workflow Issue Severity Levels

Severity levels help determine the urgency and impact of an issue. Use them to drive workflow logic and user experience.
SeverityDescription
INFOInformational only.
REVIEWRequires review.
BLOCKBlocks further processing.
WARNINGWarning, but not blocking.
CRITICALCritical issue.
ERRORError encountered.

​
Best Practices for Handling Issues

  • Monitor theissues array in workflow results to drive automated decisions or flag cases for manual review.
  • MapissueLocation to specific fields in your UI for targeted feedback.
  • Useseverity to determine whether to block, warn, or allow user progression.
  • LogissueId and requestId for troubleshooting and support.
Tip:
By building logic around issues, you can streamline compliance, automate onboarding, and improve user experience.