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": "123456789"
        },
        "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`	`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 (subType: data) verifications that can be retried in place; once submissionStatus is locked, no further resubmissions are accepted.
Name
idvRisk
Type
string
Description
Calculated IDV risk (low … high). Absent until risk has been calculated. See IDV risks.
Name
message
Type
string
Description
Human-readable explanation of the current status.
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": "12345678901", "acn": "123456789" },
    "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,
    "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.

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.

`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.

To retry a rejected individual (subType: data) 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"]).