KYC State Machine

A deep-dive into different KYC states

State flow


Starting a new KYC

After successfully initializing a KYC, the KYC state of a customer begins in submitted.

API Call

As indicated by the diagram, a KYC on a customer is triggered by an API call. For a consumer banking program, this API call is Start KYC (Know-Your-Customer), and for a secured charge card program this API call is Submit credit application.

Error HTTP response codes

When Initializing a KYC, the expected HTTP response code is 201. However, there is the possibility of error response codes as well. The main cases are 409, 4XX excluding 409, and 5XX. The latter two can be handled in accordance with standard REST processes. The former 409 case indicates that a KYC is already initialized for the customer, and the Retrieve KYC Status endpoint should be used to check on KYC status.

Bond evaluation

After a KYC is successfully initialized, it will reach Bond's automatic evaluation process. There are multiple possible outcomes of the automatic evaluation process.

PassedThe customer information provided was sufficient to fulfill KYC obligations
More information neededAdditional information is required to complete the KYC process
Review requiredBond must review the provided information for a final decision
ErrorAn error occurred during the KYC process


More than 90% of successfully initialized KYC attempts are able to pass or reach a terminal state without additional action from users.


When a KYC is passed, the state of the KYC will become passed and a kyc.verification.success webhook will be sent to any subscribed listeners. The customer will now be eligible for the financial products on the Bond platform associated with the program ID for which they have completed KYC.

More information needed

Sometimes a customer's information contains discrepancies or ambiguities and needs to be verified in other ways via document collection. This always results in a document_required state and an associated kyc.verification.document_required webhook being sent to any subscribed listeners. The customer has 14 days to provide the relevant information. After providing the information, the customer's KYC is returned back to Bond's automatic evaluation process for reevaluation.


If the customer does not provide the relevant information within 14 days, the customer's KYC attempt expires and a kyc.verification.timeout webhook is sent to any subscribed listeners. A new KYC must be initialized for customers when this happens.

Review required

Some KYC attempts require a manual review of the provided information to ensure compliance with KYC regulations. This is communicated via an under_review state and a kyc.verification.under_review webhook being sent to any subscribed listeners. The review occurs on Bond's side and does not need to be actioned by the customer.

A review may result in a passing judgment, which transforms the state of the KYC to passed and sends a corresponding kyc.verification.success webhook. A review may also result in a failure judgment, which transforms the state of the KYC to failed and sends a corresponding kyc.verification.failure webhook. The latter indicates that a new KYC must be started.


At times, Bond's systems may experience transient errors. This will be communicated via kyc.verification.error webhooks to any subscribed listeners. KYC attempts that experience errors should be retried. If the problem persists, escalation to Bond support is suggested.