Stakeholders

Stakeholders are individuals or entities associated with a verification that require their own identity verification. Use these endpoints to list, retrieve, and update stakeholder requests throughout the verification lifecycle.

Overview

Common stakeholder use cases include:

Directors of a company being verified
Applicants who are the primary contact for the verification
Other stakeholders such as beneficial owners, trustees, or authorized representatives

When a verification transitions to info status and requires stakeholder verification, the system generates stakeholder requests with unique form URLs. You can use these endpoints to monitor stakeholder records and update stakeholder details before they complete their verification.

All stakeholder endpoints require a valid trace identifier, which uniquely identifies the parent verification:

GET /v5/verifications/:trace/stakeholders - List stakeholder summaries for a verification
GET /v5/verifications/:trace/stakeholders/:stakeholderId - Retrieve full details for a specific stakeholder
PUT /v5/verifications/:trace/stakeholders/:stakeholderId - Update a requested stakeholder while the verification is in info status

GET/v5/verifications/:trace/stakeholders

List stakeholders

Retrieve summary data for all stakeholders associated with a verification. This is useful for displaying stakeholder progress and determining which stakeholder to retrieve in full.

This endpoint returns lightweight summary data for efficient listing. For full stakeholder details (including complete entity data), use the Get stakeholder endpoint.

Path parameters

Name
trace
Type
string
Description
The unique identifier for the verification.

Response fields

The response contains a data.stakeholders array. Each stakeholder summary includes:

Field	Type	Description
`stakeholderId`	string	Unique stakeholder identifier.
`roles`	string[]	Every role the stakeholder was requested under (for example, `["director", "shareholder"]`).
`type`	string	Entity type (`individual`, `company`, `trust`, etc.).
`subType`	string	Entity sub-type (for example, `discretionaryTrust`, `none`).
`country`	string	ISO3 country code.
`name`	string	Display name (full name for individuals, entity name for companies).
`createdAt`	number	Date submitted (Unix milliseconds). Re-stamped by a re-submission, so it tracks the stakeholder's latest submission.
`updatedAt`	number	Unix timestamp of last update.
`createdTime`	string	Human-readable form of `createdAt` (date submitted).
`updatedTime`	string	Human-readable update time.

Request

GET

/v5/verifications/:trace/stakeholders

curl -X GET "https://api.bronid.com/v5/verifications/{trace}/stakeholders" \
  -H "Authorization: Basic {credentials}"

Response

{
  "timestamp": "2026-01-30T04:00:00.000Z",
  "serviceUid": "5qA5Hq0n1JQTY2TASItxYXSRyND3",
  "trace": "abc123-verification-trace",
  "path": "/v5/verifications/:trace/stakeholders",
  "pathParams": {
    "trace": "abc123-verification-trace"
  },
  "statusCode": 200,
  "message": "Stakeholders listed successfully.",
  "help": null,
  "status": "success",
  "data": {
    "stakeholders": [
      {
        "stakeholderId": "stk-id-123",
        "roles": ["trustee"],
        "type": "company",
        "subType": "none",
        "country": "AUS",
        "name": "Smith Trustee Pty Ltd",
        "createdAt": 1769742000000,
        "updatedAt": 1769742000000,
        "createdTime": "30/01/2026 14:00:00",
        "updatedTime": "30/01/2026 14:00:00"
      },
      {
        "stakeholderId": "stk-id-456",
        "roles": ["director"],
        "type": "individual",
        "subType": "none",
        "country": "AUS",
        "name": "John Smith",
        "createdAt": 1769742300000,
        "updatedAt": 1769742300000,
        "createdTime": "30/01/2026 14:05:00",
        "updatedTime": "30/01/2026 14:05:00"
      }
    ]
  },
  "error": null
}

GET/v5/verifications/:trace/stakeholders/:stakeholderId

Get stakeholder

Retrieve full details for a specific stakeholder using the stakeholder ID from the list endpoint. The response carries the stakeholder's entity data together with its current verification state — the same state block GET /v5/verifications/:trace returns for the parent, keyed on the stakeholder's own status.

Path parameters

Name
trace
Type
string
Description
The unique identifier for the verification.
Name
stakeholderId
Type
string
Description
The unique identifier for the stakeholder.

Response fields

The response contains full stakeholder data at data:

Field	Type	Description
`trace`	string	The parent verification's trace.
`stakeholderId`	string	Unique stakeholder identifier. The stakeholder webhooks about this person carry it as their `trace`.
`roles`	string[]	Every role the stakeholder was requested under (e.g., `["director", "shareholder"]`).
`submissionId`	string	Reference to the submission that created this stakeholder.
`userId`	string \| null	Always `null`: a stakeholder has no user ID of its own. The parent verification's `userId` is on the parent.
`onBehalfUid`	string \| null	The account the parent verification was created on behalf of, or `null`.
`tags`	string[]	The parent verification's tags.
`country`	string	ISO3 country code.
`type`	string	Entity type (`individual`, `company`, etc.).
`subType`	string	Entity sub-type.
`name`	string	Display name (full name for individuals, entity name for companies).
`industry`	string \| null	Industry (`null` for individuals).
`website`	string \| null	Website (`null` for individuals).
`identifiers`	object \| null	Entity identifiers such as ABN, ACN (`null` for individuals).
`addresses`	object \| null	Entity addresses (`null` for individuals).
`inputRisk`	string \| null	Always `null`: input risk is set on the parent verification, not per stakeholder.
`idvRisk`	string	Calculated IDV risk (`low` … `high`); `unknown` until the stakeholder's risk has been calculated. See IDV risks.
`submissionStatus`	string \| null	Data-collection state: `submitted`, or `locked` once a retryable stakeholder has exhausted its attempt cap. `null` until the stakeholder has a verification status.
`verificationStatus`	string	Current verification state for the stakeholder: `pending`, `verified`, `rejected`, `error`, `new`, or the stakeholder-only `removed`. Absent until the stakeholder has been acted on, as on the list.
`attempt`	number	Which verification attempt the current status belongs to, starting at `1`. Present for retryable individual stakeholders — `subType: data` (resubmitted via the API) and `subType: biometric` (re-attempted on the hosted eKYC link). Optional.
`maxAttempts`	number	The attempt cap in force (`5`), so clients can render "attempt x of y" and derive the locked gate from the data. Present alongside `attempt`. Optional.
`message`	string \| null	Human-readable explanation of the current status, or `null` when there is none.
`timestamp`	number \| null	Unix timestamp (milliseconds) of the last change to the stakeholder's status information. `null` until the stakeholder has a verification status. This is not the submission time; use `createdAt` for that.
`rejectionReasons`	object[]	Present only when `verificationStatus` is `rejected`: client-safe reasons for the latest attempt (`reason`, `description`, `help`).
`errorReasons`	object[]	Present only when `verificationStatus` is `error`: details of the processing error (`reason`, `description`, `help`).
`removalReason`	string	Present only when `verificationStatus` is `removed`: why the stakeholder was marked as removed. One of `Deceased`, `Minor`, `Removed as a beneficiary`, `Removed as a trustee`, `Removed as an appointor/principal`, `Performed manual ID verification`, `Discretionary removal`, `Other`.
`removalDescription`	string	Present only when `verificationStatus` is `removed`: the free-text explanation entered with the removal reason.
`createdAt`	number	Date submitted (Unix milliseconds). Re-stamped by a re-submission, so it tracks the stakeholder's latest submission.
`updatedAt`	number	Unix timestamp of last update.
`createdTime`	string	Human-readable form of `createdAt` (date submitted).
`updatedTime`	string	Human-readable update time.

A stakeholder that was marked as removed before submitting anything is returned too, with verificationStatus: removed, the details known from the request, and null identifiers and addresses.

Error responses

Status Code	Error Type	Description
404	`not_found`	Stakeholder not found for the given verification.

Request

GET

/v5/verifications/:trace/stakeholders/:stakeholderId

curl -X GET "https://api.bronid.com/v5/verifications/{trace}/stakeholders/{stakeholderId}" \
  -H "Authorization: Basic {credentials}"

Response

{
  "timestamp": "2026-01-30T04:05:00.000Z",
  "serviceUid": "5qA5Hq0n1JQTY2TASItxYXSRyND3",
  "trace": "abc123-verification-trace",
  "path": "/v5/verifications/:trace/stakeholders/:stakeholderId",
  "pathParams": {
    "trace": "abc123-verification-trace",
    "stakeholderId": "stk-id-123"
  },
  "statusCode": 200,
  "message": "Stakeholder details retrieved successfully.",
  "help": null,
  "status": "success",
  "data": {
    "trace": "abc123-verification-trace",
    "stakeholderId": "stk-id-123",
    "roles": ["trustee"],
    "submissionId": "abc123-verification-trace",
    "userId": null,
    "onBehalfUid": null,
    "tags": [],
    "country": "AUS",
    "type": "company",
    "subType": "none",
    "name": "Smith Trustee Pty Ltd",
    "industry": "Trustee Services",
    "website": "https://smithtrustee.com.au",
    "identifiers": {
      "acn": "004028077",
      "abn": "51824753556"
    },
    "addresses": {
      "registeredAddress": "Level 5, 100 Collins St, Melbourne VIC 3000",
      "principalPlaceOfBusiness": "Suite 10, 50 Bridge St, Sydney NSW 2000"
    },
    "inputRisk": null,
    "idvRisk": "low",
    "submissionStatus": "submitted",
    "verificationStatus": "verified",
    "message": "Verification completed.",
    "timestamp": 1769742300000,
    "createdAt": 1769742000000,
    "updatedAt": 1769742000000,
    "createdTime": "30/01/2026 14:00:00",
    "updatedTime": "30/01/2026 14:00:00"
  },
  "error": null
}

Error response (404)

{
  "timestamp": "2026-01-30T04:05:00.000Z",
  "serviceUid": "5qA5Hq0n1JQTY2TASItxYXSRyND3",
  "trace": "abc123-verification-trace",
  "path": "/v5/verifications/:trace/stakeholders/:stakeholderId",
  "pathParams": {
    "trace": "abc123-verification-trace",
    "stakeholderId": "invalid-stakeholder-id"
  },
  "statusCode": 404,
  "message": "Not found",
  "help": null,
  "status": "error",
  "data": null,
  "error": {
    "type": "not_found",
    "details": [
      {
        "message": "Stakeholder not found: invalid-stakeholder-id",
        "code": "not_found",
        "path": ["stakeholderId"]
      }
    ]
  }
}

PUT/v5/verifications/:trace/stakeholders/:stakeholderId

Update stakeholder request

Update an existing stakeholder request. Use this to modify stakeholder details before they complete their verification.

Path parameters

Name
trace
Type
string
Description
The unique identifier for the verification.
Name
stakeholderId
Type
string
Description
The unique identifier for the stakeholder.

Required attributes

Name
name
Type
string
Description
Full name of the stakeholder.
Name
description
Type
string
Description
Description of the stakeholder's relationship to the entity.
Name
reason
Type
string
Description
Reason for requesting verification from this stakeholder.
Name
email
Type
string
Description
Valid email address for the stakeholder.
Name
roles
Type
string[]
Description
Array of roles assigned to the stakeholder — at least one role is required. See Stakeholder Roles below.

Constraints

The verification must exist
The verification must be in info status
The stakeholder must exist in the verification's remaining actions

Error responses

Status Code	Error Type	Description
404	`not_found`	Verification state not found
404	`not_found`	Entity not in info status
404	`not_found`	Stakeholder is not requested
422	`validation_error`	Invalid request parameters

Request

PUT

/v5/verifications/:trace/stakeholders/:stakeholderId

curl -X PUT "https://api.bronid.com/v5/verifications/{trace}/stakeholders/{stakeholderId}" \
  -H "Authorization: Basic {credentials}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "description": "CEO and Director",
    "reason": "Updated verification reason",
    "email": "john.smith@example.com",
    "roles": ["director", "applicant"]
  }'

Response

{
  "serviceUid": "5qA5Hq0n1JQTY2TASItxYXSRyND3",
  "trace": "DriJoJAkKk-YUBKFVXW7c",
  "path": "/v5/verifications/:trace/stakeholders/:stakeholderId",
  "pathParams": {
    "trace": "DriJoJAkKk-YUBKFVXW7c",
    "stakeholderId": "stk_z_dBQc-tkL7Ext04ifOhw"
  },
  "timestamp": "2026-01-19T02:35:00.000Z",
  "status": "success",
  "statusCode": 200,
  "data": null,
  "message": "Stakeholder updated successfully.",
  "help": null,
  "error": null
}

Error response

{
  "timestamp": "2024-01-12T10:30:00.000Z",
  "trace": "xyz789abc",
  "path": "/v5/verifications/:trace/stakeholders/:stakeholderId",
  "status": "error",
  "statusCode": 404,
  "message": "Not found",
  "help": null,
  "data": null,
  "error": {
    "type": "not_found",
    "details": [
      {
        "message": "Stakeholder is not requested: stk_invalid123",
        "code": "not_found",
        "path": ["stakeholderId"]
      }
    ]
  }
}

Stakeholder roles reference

The roles field accepts an array of the following values:

Role	Description
`applicant`	Submits the application on behalf of the entity
`director`	Board member governing the company
`trustee`	Holds and manages the Trust assets for the Beneficiaries
`settlor`	Established the Trust by settling the initial assets
`beneficiary`	Entitled to benefit from the Trust
`shareholder`	Holds shares in the company
`partner`	Shares ownership and control of the Partnership
`beneficialOwner`	Person who owns or controls 25% or more of the entity
`appointor`	Has the power to appoint or remove the Trustee
`guardian`	Consent required for certain Trustee decisions
`protector`	Oversees the Trustee and may veto or direct certain Trustee decisions
`principal`	Named in the Trust Deed to appoint or remove the Trustee
`chairperson`	Chairs the entity's governing body
`deputyChairperson`	Acts as Chairperson in their absence
`president`	Leads the organisation's governing committee
`vicePresident`	Acts as President in their absence
`ceo`	Manages the entity's day-to-day operations
`publicOfficer`	Responsible for the entity's statutory and tax obligations
`treasurer`	Responsible for the organisation's finances
`secretary`	Responsible for the entity's records and statutory filings
`unitHolder`	Holds units in the Unit Trust
`other`	Any other type of owner or controller of the entity

Common role combinations by entity type

Companies:

Directors: ["director"]
Director who is also the applicant: ["director", "applicant"]
Shareholders with significant control: ["shareholder", "beneficialOwner"]

Trusts:

Corporate trustee directors: ["director"]
Individual trustees: ["trustee"]
Beneficiaries: ["beneficiary"]
Settlors: ["settlor"]

Partnerships:

Partners: ["partner"]
Managing partner: ["partner", "applicant"]

A stakeholder can have multiple roles. For example, a person who is both the applicant and a director would have roles: ["applicant", "director"].