Verifications

You can use the /verification endpoints to manage verifications programmatically. We'll look at how to create and retrieve verifications.

POST/v5/verifications

Create a verification

This endpoint allows you to create a new KYB verification. Provide the entity details including type, identifiers, documents, and stakeholders.

Request body

Name
userId
Type
string
Description
Optional. Your internal user identifier. Use this to track which of your users submitted the verification. Must be unique per verification.
Name
onBehalfUid
Type
string
Description
Optional. The UID of an onBehalf account if submitting account-grouped verifications.
Name
tags
Type
array
Description
Optional. Array of tag labels to attach to the verification for filtering and reporting. Use >>> (with surrounding spaces) to express hierarchy (e.g. tier-1 >>> gold). Up to 50 tags, each up to 500 characters. Labels referenced here are auto-registered into your tag registry on submission.
Name
country
Type
string
Description
ISO3 Country code of the entity (e.g. AUS).
Name
type
Type
string
Description
Entity type (e.g. trust).
Name
subType
Type
string
Description
Entity sub-type (e.g. bareTrust).
Name
name
Type
string
Description
Entity name.
Name
industry
Type
string
Description
Industry description.
Name
website
Type
string
Description
Entity website URL.
Name
inputRisk
Type
string
Description
Risk level (e.g. unknown/low/medium/high).
Name
identifiers
Type
object
Description
Entity identifiers keyed by scheme (e.g. abn, acn, etc.).
Name
addresses
Type
object
Description
Entity addresses (e.g. registeredAddress, principalPlaceOfBusiness, etc.).
Name
documents
Type
array
Description
Array of document objects with kind, mimeType, source, data, and optional description.
Name
stakeholders
Type
array
Description
Array of stakeholder objects with roles, type, country, and entity fields.

For Australian and New Zealand entities, use the Lookup API before submitting a verification. It returns the entity name, identifiers, and the correct type and subType values from the registry, which you can pass directly into your verification request.

Request

POST

/v5/verifications

curl https://dev.bronid.com/v5/verifications \
  --user "XL7ULiU6B4QE9Y2iWFZnhtMDKFN2:api_sec_NJAtNcRtUrPlf7xYDrMNP9URI-ZfN314" \
  --header "Content-Type: application/json" \
  --data '{
    "country": "AUS",
    "type": "trust",
    "subType": "bareTrust",
    "name": "My Trust",
    "industry": "My industry",
    "website": "https://bronid.com",
    "inputRisk": "unknown",
    "identifiers": {},
    "addresses": {
	      "registeredAddress": "125 York St, Sydney, NSW, Australia"},
    "documents": [
      {
        "kind": "trustDeed",
        "mimeType": "application/pdf",
        "source": "url",
        "data": "https://example.com",
        "description": ""
      }
    ],
    "stakeholders": [
      {
        "roles": ["trustee"],
        "type": "company",
        "subType": "none",
        "country": "AUS",
        "name": "My Trustee",
        "industry": "Trustee Services",
        "website": "https://mytrustee.com.au",
        "identifiers": {
          "acn": "004028077"
        },
        "addresses": {
          "registeredAddress": "125 York St, Sydney, NSW, Australia"
        }
      }
    ],
    "tags": ["region:apac", "tier-1 >>> gold"]
  }'

Response

{
  "timestamp": "2026-01-27T04:25:42.101Z",
  "serviceUid": "XL7ULiU6B4QE9Y2iWFZnhtMDKFN2",
  "trace": "_mycHhuXA8vDMTgbCsqJf",
  "path": "/v5/verifications",
  "pathParams": {},
  "statusCode": 200,
  "message": "Verification created successfully",
  "help": null,
  "status": "success",
  "data": null,
  "error": null
}

GET/v5/verifications/:trace

Retrieve a verification

This endpoint returns detailed information about a verification by its trace identifier. It is how you act on a webhook: the webhook tells you the status changed, and this endpoint returns the full detail for that status.

Response varies by status

Every response shares the same envelope and a common set of verification fields. The data payload then carries extra fields depending on verificationStatus — it is a discriminated union keyed on that field:

`verificationStatus`	Extra fields in `data`	What to do next
`new`	— (entity fields are `null`)	Submit the verification
`pending`	—	Wait for the next webhook
`info`	`formUrl`, `remainingActions`	Provide missing information
`verified`	—	Read stakeholders & documents
`rejected`	`rejectionReasons`	Resubmit or retry
`error`	`errorReasons`	Retry shortly; contact support if it persists

See Verification statuses for the full lifecycle, and the status diagram for how info loops back to pending.

Response fields

On top of the entity fields, every response carries the verification state:

Name
submissionStatus
Type
string
Description
Data-collection state: new, unsubmitted, in_progress, submitted, or locked. See submission status.
Name
verificationStatus
Type
string
Description
Current state — the discriminator that determines which extra fields are present (see table above).
Name
attempt
Type
number
Description
Which verification attempt the status belongs to, starting at 1. Present for individual verifications that can be retried in place — subType: data resubmits on the same form, subType: biometric re-attempts on the hosted eKYC link; once submissionStatus is locked, no further resubmissions are accepted.
Name
maxAttempts
Type
number
Description
The attempt cap in force on the record. Present on verifications that track capped retries — its presence alone does not mean a retry is open: a rejected status is retryable in place only with attempt below maxAttempts and a non-locked submissionStatus. Absent when the record has no capped-retry regime — treat such a rejection as final. Read the cap from this field rather than assuming 5; it can be raised on a specific verification.
Name
idvRisk
Type
string
Description
Calculated IDV risk (low … high). Absent until risk has been calculated. See IDV risks.
Name
createdAt
Type
number
Description
Date submitted, as a Unix timestamp in milliseconds. For individual verifications it is re-stamped by each re-submission, so it tracks the latest submission. For entity verifications it is stamped once, at the first submission, and stays fixed for the life of the verification.
Name
updatedAt
Type
number
Description
Unix timestamp (milliseconds) of the last change to the verification record.
Name
message
Type
string
Description
Human-readable explanation of the current status.
Name
timestamp
Type
number
Description
Unix timestamp (milliseconds) of the last update to the verification status information — moves when the status, message, remaining actions, or attempt change. Risk recalculation on its own does not move it. null until the verification has been submitted. This is not the submission time; use createdAt for that.
Name
formUrl
Type
string | null
Description
Present only when verificationStatus is info — the link to the verification's hosted form, where your customer can complete every remaining action themselves. For an entity form or an individual data form created with POST /v5/forms, it is the same link that call returned. null when there is no hosted form link to offer; provide the missing information through the API instead. See Forwarding your customer to the hosted form.
Name
remainingActions
Type
object
Description
Present only when verificationStatus is info — the documents and stakeholders still required. See remainingActions.
Name
rejectionReasons
Type
array
Description
Present only when verificationStatus is rejected — client-safe reasons for the latest attempt. See rejectionReasons.
Name
errorReasons
Type
array
Description
Present only when verificationStatus is error — details of the processing error. See errorReasons.

Request

GET

/v5/verifications/:trace

curl https://dev.bronid.com/v5/verifications/wPdizyxulRLADcd2tD-Eh \
  --user "XL7ULiU6B4QE9Y2iWFZnhtMDKFN2:api_sec_NJAtNcRtUrPlf7xYDrMNP9URI-ZfN314"

Response by status

{
  "timestamp": "2026-01-27T04:27:03.225Z",
  "serviceUid": "XL7ULiU6B4QE9Y2iWFZnhtMDKFN2",
  "trace": "wPdizyxulRLADcd2tD-Eh",
  "path": "/v5/verifications/:trace",
  "pathParams": { "trace": "wPdizyxulRLADcd2tD-Eh" },
  "statusCode": 200,
  "message": "Verification details retrieved successfully.",
  "help": null,
  "status": "success",
  "data": {
    "userId": "user-123",
    "onBehalfUid": null,
    "trace": "wPdizyxulRLADcd2tD-Eh",
    "submissionId": "wPdizyxulRLADcd2tD-Eh",
    "country": "AUS",
    "type": "company",
    "subType": "none",
    "name": "Acme Holdings Pty Ltd",
    "industry": "Financial services",
    "website": "https://acme.example",
    "identifiers": { "abn": "51824753556", "acn": "004028077" },
    "addresses": { "registeredAddress": "125 York St, Sydney, NSW, Australia" },
    "inputRisk": "medium",
    "tags": ["region:apac"],
    "other": [],
    "submissionStatus": "in_progress",
    "verificationStatus": "info",
    "message": "Additional information is required to continue processing the verification.",
    "timestamp": 1767004900000,
    "idvRisk": "medium",
    "createdAt": 1767004800000,
    "updatedAt": 1767004900000,
    "formUrl": "https://forms.bronid.com/ekyc-start/wPdizyxulRLADcd2tD-Eh",
    "remainingActions": {
      "document": {
        "5K6KfEmJbmj_LBPP8I0T3": {
          "id": "5K6KfEmJbmj_LBPP8I0T3",
          "type": "document",
          "name": "Certificate of incorporation",
          "description": "Certificate of incorporation for Acme Holdings Pty Ltd.",
          "reason": "Required to confirm the company's registration.",
          "uploadUrl": "https://storage.googleapis.com/…?X-Goog-Signature=…",
          "uploadHeaders": {
            "Content-Type": "application/octet-stream",
            "x-goog-content-length-range": "1,26214400"
          },
          "help": null
        }
      },
      "stakeholder": {
        "FdXE96z011CwWJ9Z5ulGf": {
          "id": "FdXE96z011CwWJ9Z5ulGf",
          "type": "individual",
          "subType": "biometric",
          "name": "Jane Citizen",
          "description": "Director of Acme Holdings Pty Ltd.",
          "reason": "Identity verification is required for all directors.",
          "help": null,
          "roles": ["director"],
          "formUrl": "https://ekyc.bronid.com/ekyc-start/FdXE96z011CwWJ9Z5ulGf",
          "email": "jane.citizen@example.com",
          "phone": "+61400000000"
        }
      }
    }
  },
  "error": null
}

remainingActions

Returned when verificationStatus is info. Each entry is keyed by its own ID — the document ID or stakeholder ID you use to fulfil it. The webhook does not include this object; fetch it here. See Provide missing information for the end-to-end workflow.

You can fulfil each entry through the API, as described below, or, when formUrl is not null, send your customer to it: the hosted form lists the same remaining actions and lets them upload the documents and get each individual verified themselves.

document — documents to upload, keyed by document ID. Fulfil each with PUT /v5/verifications/:trace/documents/:documentId (see Documents).

Field	Type	Description
`id`	string	The document ID (same as the key). Use it as `:documentId`.
`type`	string	Always `"document"`.
`name`	string	Short label for the requested document.
`description`	string	What the document is.
`reason`	string	Why it is required.
`uploadUrl`	string	Absolute URL to upload the raw file bytes to.
`uploadHeaders`	object	Headers to send verbatim with the upload request — they are part of the URL signature, so the upload is rejected without them. May be absent on actions issued before this field existed.
`help`	string \| null	Optional guidance (e.g. a sample upload command).

Treat uploadUrl and uploadHeaders as one inseparable bundle: read the headers from each response and send them unchanged with that URL's upload. Do not hard-code the header values — they can differ between URLs and change over time (for example if the size limit changes), and a hard-coded or missing header makes the upload fail signature verification.

stakeholder — individuals who must complete their own identity verification, keyed by stakeholder ID. Direct each to their formUrl.

Field	Type	Description
`id`	string	The stakeholder ID (same as the key).
`type`	string	Always `"individual"`.
`subType`	string	Which flow `formUrl` points at: `biometric` (biometric eKYC) or `data` (data form).
`name`	string	The individual's name.
`description`	string	Their relationship to the entity.
`reason`	string	Why their verification is required.
`help`	string \| null	Optional guidance.
`roles`	array	Roles held within the entity (e.g. `["director"]`).
`formUrl`	string	Link to send the individual to complete their verification.
`email`	string	The individual's email.
`phone`	string	The individual's phone, when provided.

rejectionReasons

Returned when verificationStatus is rejected, describing the latest attempt. These are client-safe summaries — the raw vendor outcomes are never returned. They are deliberately omitted from webhook payloads; fetch them here.

Field	Type	Description
`reason`	string	One of the client-safe titles below.
`description`	string	A customer-facing explanation.
`help`	string \| null	Optional next-step guidance.

For individual (subType: data) and entity verifications:

`reason`	When it is used
`Identity could not be verified`	The submitted details did not match official records.
`Verification could not be completed`	A technical issue prevented the check; retry shortly.
`Country not supported`	Identity verification is not available for the selected country.

For individual (subType: biometric) verifications — the outcome of a manual review of the submitted documents and biometrics:

`reason`	When it is used
`Verification was not successful`	The verification could not be completed; review the submission and retry.
`Documents do not meet requirements`	Two or more uploaded documents do not meet the requirements.
`Document has expired`	An uploaded document has expired.
`Document type not accepted`	An uploaded document is not an accepted document type.
`Biometrics did not match`	The selfie did not match the photo on the identity document.
`Liveness check could not be verified`	A live capture of the face could not be confirmed.
`Required details are missing`	Required details could not be read from an uploaded document.
`Images are unclear`	The uploaded images were blurry or unreadable.
`Document is not a physical copy`	The images appear to be of a screenshot or a photo of a screen.
`Address is incomplete`	The address provided was incomplete or could not be confirmed.

To retry a rejected individual verification in place, see Retrying a rejected individual verification.

errorReasons

Returned when verificationStatus is error — a rare, usually transient processing failure. Retry after a short delay, and contact support if it persists.

Field	Type	Description
`reason`	string	Short error label.
`description`	string	Human-readable explanation.
`help`	string \| null	Optional next-step guidance.

The verification model

The verification model consists of several fixed properties (country, type, subType, name, industry, website), but also includes properies which depend on the country and entity type you are submitting (identifiers, addresses, stakeholders). Please look at the specific country and entity schemas for a detailed description.

Properties

Name
country
Type
string
Description
ISO3 Country code of the entity (e.g. AUS).
Name
type
Type
string
Description
Entity type (e.g. trust).
Name
subType
Type
string
Description
Entity sub-type (e.g. bareTrust).
Name
name
Type
string
Description
Entity name.
Name
industry
Type
string
Description
Industry description.
Name
website
Type
string
Description
Entity website URL.
Name
inputRisk
Type
string
Description
Risk level (e.g. unknown/low/medium/high).
Name
identifiers
Type
object
Description
Entity identifiers keyed by scheme.
Name
addresses
Type
object
Description
Entity addresses.
Name
tags
Type
array
Description
Optional. Array of tag labels for filtering and reporting (e.g. ["region:apac", "tier-1 >>> gold"]).