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.

A stakeholder of an entity verification can additionally report one status that an entity or standalone verification never does:

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 verification returns to processing when the individual retries — subType: data by resubmitting with corrected details, subType: biometric by re-attempting on the hosted eKYC link
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

Alternatively, forward your customer to the verification's own formUrl, returned in the same response (null when there is no link to offer): the hosted form lists the remaining actions and lets them complete steps 2 and 3 themselves.

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 verifications, have the individual retry 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 by default. The cap in force is reported as maxAttempts alongside attempt on the same surfaces — read the cap from the record rather than hardcoding 5, as it can be raised on a specific verification (e.g. after a support request). 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.

An individual (subType: biometric) verification 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. rejected is therefore not terminal for a biometric individual either, until the cap is exhausted. The retry window is carried on the record itself as the maxAttempts cap: a rejected biometric verification that reports maxAttempts with attempt below it (and is not locked) can be retried in place, while one that reports no maxAttempts has no open retry window — treat that rejection as final and create a new verification if the individual should try again. Do not infer retryability from attempt alone: webhook payloads always populate attempt (defaulting to 1), so only the presence of maxAttempts — surfaced on both the GET response and webhook payloads (see below) — signals an open retry window.

• For a standalone biometric verification, attempt, maxAttempts, and rejectionReasons surface on GET /v5/verifications/:trace, and attempt, maxAttempts, and submissionStatus (incl. "locked") appear on its webhooks — the same shape as a data individual.
• For a biometric stakeholder of an entity verification, attempt, maxAttempts, and rejectionReasons surface on the stakeholders list; its attempt, maxAttempts, and submissionStatus (incl. "locked") also appear on stakeholder webhooks. The stakeholder action remains open until the stakeholder is verified or marked as removed, and the parent entity stays in info while it is open.

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.

removed

A stakeholder-only status. An individual who was requested as a stakeholder of an entity verification (e.g. a director or beneficial owner) was marked as removed before completing their verification. A stakeholder is marked as removed in the bronID portal while the entity is in info, together with a removal reason. Being marked as removed does not necessarily mean the person has left the entity: the reason may be, for example, that their identity was verified manually.

• It is reported only for stakeholders: on stakeholder webhooks (those carrying parentTrace) and in the stakeholders list. An entity or standalone verification never reports removed.
• It is final for that individual on that entity: the stakeholder action is closed and the individual no longer needs to verify.
• A removed webhook may be the first webhook you receive for that individual, since a stakeholder can be marked as removed before they submitted anything.
• If this was the entity's last outstanding action (no other stakeholders or requested documents are still outstanding), the entity then moves on from info and receives its own webhook as usual. Otherwise it stays in info until the remaining actions are completed.

What to do: Mark the individual as removed in your system, and keep processing the entity from its own webhooks. Treat removed as a known value when you validate stakeholder webhook payloads.

Reading the removal reason: the reason is not included in the webhook payload. To read it:

1. Fetch the stakeholders list (GET /v5/verifications/:trace/stakeholders) using the webhook's parentTrace as the trace.
2. Find the stakeholder whose stakeholderId matches the webhook's trace.
3. Read its removalReason and removalDescription:
   • removalReason is one of Deceased, Minor, Removed as a beneficiary, Removed as a trustee, Removed as an appointor/principal, Performed manual ID verification, Discretionary removal or Other.
   • removalDescription is the free-text explanation entered when the stakeholder was marked as removed.

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.