Verification Statuses

Verifications move through a series of statuses from submission to completion. Understanding these statuses is essential for building a robust integration.

Status overview

The verificationStatus field indicates the current state of a verification. Each status change triggers a webhook notification to your registered endpoint.

Entity verification flow

After submission, a verification typically follows this flow:

1. Submitted to pending: Verification is queued for processing
2. pending to verified / rejected / info: Processing completes with a result
3. info to pending: After missing information is provided, returns to processing
4. rejected to pending: A rejected individual (subType: data) verification returns to processing when the individual resubmits with corrected details
5. The cycle can repeat until reaching a terminal state (verified, or rejected once no further attempts are possible)

Status details

new

The verification entry exists but no data has been submitted yet. This status is returned when:

• A trace identifier has been created (e.g., via form creation)
• No entity data has been submitted for verification

Response includes:

• trace - The verification trace identifier
• userId - Your internal user identifier (if provided during form creation)
• onBehalfUid - The onBehalf account UID (if applicable)
• submissionStatus - Current submission status (typically new)
• verificationStatus - Set to new
• message - Explanation that entity has not been submitted
• Entity fields (country, type, name, etc.) will be null

What to do: Submit entity data using POST /v5/verifications to begin the verification process.

pending

The verification has been submitted and is being processed. This is typically the first status after submission.

What to do: Wait for a webhook notification with the next status. Processing times vary:

• Median: Under 15 minutes
• Extended cases: Up to 24-48 hours (during registry maintenance or high load)

info

Additional information is required to complete the verification. This typically means:

• Additional documents are needed (e.g., trust deed, certificate of incorporation)
• Additional stakeholders need to be verified (e.g., directors, beneficial owners)

What to do:

1. Fetch the remainingActions using GET /v5/verifications/:trace
2. Upload any requested documents using PUT /v5/verifications/:trace/documents/:documentId
3. Direct stakeholders to complete their verification using the provided formUrl

See Provide Missing Information for detailed instructions.

verified

The verification was successful and satisfies the bronID verification requirements.

What to do: Update your system to reflect the successful verification. The customer can proceed with your onboarding flow.

Response includes:

• Summary entity data
• IDV risk score
• Verification timestamp

What to do:

1. Read detailed verification information
2. Read detailed stakeholder information
3. Read detailed document information
4. Update your system to reflect the successful verification

rejected

The verification requirements were not met. Common reasons include:

• Entity could not be found in the relevant registry
• Incorrect entity details were submitted
• Document verification failed
• Stakeholder verification failed

What to do:

1. Fetch rejection details using GET /v5/verifications/:trace
2. Review the rejectionReasons array for specific issues
3. If correctable, submit a new verification with corrected information — or, for rejected individual (subType: data) verifications, have the individual resubmit the same verification (see below)

Retrying a rejected individual verification

A rejected individual (subType: data) verification is retryable in place: the individual corrects their details on the same verification form and submits again. No new verification or new trace is needed.

• On resubmission the status moves backwards from rejected to pending — design your integration so a pending webhook after a rejected one updates the customer state instead of being treated as out of order.
• The attempt field (in webhook payloads and the GET response) reports which attempt the current status belongs to, starting at 1.
• Up to 5 attempts are allowed. The rejection that exhausts the cap also locks the verification (submissionStatus: "locked"), and any further resubmission is refused with HTTP error 474 too_many_attempts.
• rejectionReasons always describe the latest attempt. They are not included in webhook payloads — fetch them via GET /v5/verifications/:trace.

For an entity verification, an individual (subType: biometric) stakeholder has an analogous capped retry — but it is not an API resubmit: the individual re-attempts on their hosted eKYC link, advancing attempt toward the same 5-attempt cap and reaching submissionStatus: "locked" when it is exhausted. The stakeholder's attempt, maxAttempts, and rejectionReasons surface on the stakeholders list; its attempt and submissionStatus (incl. "locked") also appear on stakeholder webhooks. The parent entity stays in info (the stakeholder action remains open) until the stakeholder is verified or removed.

error

A system error occurred during processing. This is rare and typically indicates a temporary issue.

The response includes an errorReasons array with details about what failed.

What to do: Contact bronID support if the error persists. You may retry the verification after a short delay.

Submission status

In addition to verificationStatus, the submissionStatus field tracks the data collection state:

Best practices

Design for asynchronous processing

Processing times can range from seconds to hours. Design your flow so that:

• Users do not wait on a loading screen for verification results
• Status updates are communicated via email or in-app notifications
• Your system polls or listens for webhook updates

Handle all statuses

Ensure your integration handles all possible status transitions.

Use webhooks

Rather than polling the API, configure webhooks to receive real-time status updates. This is more efficient and provides immediate notifications.