List stakeholders

You can retrieve all stakeholders associated with a verification using the GET endpoint. This is useful for displaying stakeholder status to users, tracking verification progress, or for auditing purposes.

GET/v5/verifications/:trace/stakeholders

List all stakeholders

This endpoint returns summary data for all stakeholders associated with a verification. Each stakeholder summary includes their roles, entity type, name, and timestamps.

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

Path parameters

Name
trace
Type
string
Description
The unique identifier for the verification (received when creating 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 (e.g., `["director", "shareholder"]`).
`type`	string	Entity type (`individual`, `company`, `trust`, etc.).
`subType`	string	Entity sub-type (e.g., `discretionaryTrust`, `none`).
`country`	string	ISO3 country code.
`name`	string	Display name (full name for individuals, entity name for companies).
`verificationStatus`	string	Current verification state for the stakeholder (e.g., `pending`, `verified`, `rejected`, or the stakeholder-only `removed`). Optional — absent until the stakeholder has been acted on.
`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.
`submissionStatus`	string	Data-collection state; `"locked"` once a retryable stakeholder has exhausted its attempt cap. Optional.
`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.
`rejectionReasons`	object[]	Reasons for the latest rejected attempt (`reason`, `description`, `help`). Present on a `rejected` retryable stakeholder. Optional.
`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 https://dev.bronid.com/v5/verifications/abc123-verification-trace/stakeholders \
  --user "XL7ULiU6B4QE9Y2iWFZnhtMDKFN2:api_sec_NJAtNcRtUrPlf7xYDrMNP9URI-ZfN314"

Response

{
  "timestamp": "2026-01-30T04:00:00.000Z",
  "serviceUid": "XL7ULiU6B4QE9Y2iWFZnhtMDKFN2",
  "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 a specific stakeholder

To retrieve full details about a specific stakeholder, use the stakeholder ID in the path. This returns the complete stakeholder data including all entity details, identifiers, and addresses, together with the stakeholder's 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 (from the list response).

Response fields

The response contains the 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 https://dev.bronid.com/v5/verifications/abc123-verification-trace/stakeholders/stk-id-123 \
  --user "XL7ULiU6B4QE9Y2iWFZnhtMDKFN2:api_sec_NJAtNcRtUrPlf7xYDrMNP9URI-ZfN314"

Response

{
  "timestamp": "2026-01-30T04:05:00.000Z",
  "serviceUid": "XL7ULiU6B4QE9Y2iWFZnhtMDKFN2",
  "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": "XL7ULiU6B4QE9Y2iWFZnhtMDKFN2",
  "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",
        "code": "not_found",
        "path": ["stakeholderId"]
      }
    ]
  }
}

Stakeholder roles

Stakeholders can hold one or more of the following roles:

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

What's next?

Now that you know how to list and retrieve stakeholders, explore Include stakeholders to learn how to add stakeholders when creating a verification, or see the full Stakeholders API reference for updating stakeholder requests.