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	Unix timestamp of creation.
`updatedAt`	number	Unix timestamp of last update.
`createdTime`	string	Human-readable creation time.
`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": 1737254548899,
        "updatedAt": 1737254548899,
        "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": 1737254600000,
        "updatedAt": 1737254600000,
        "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.

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 trace identifier.
`stakeholderId`	string	Unique stakeholder identifier.
`country`	string	ISO3 country code.
`type`	string	Entity type (`individual`, `company`, etc.).
`subType`	string	Entity sub-type.
`name`	string	Display name (derived from firstName + lastName for individuals, entity name for companies).
`roles`	string[]	Every role the stakeholder was requested under (for example, `["director", "shareholder"]`).
`submissionId`	string	Reference to the submission that created this stakeholder.
`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).
`idvRisk`	string	Identity verification risk level (`low`, `medium`, `high`, etc.). Only present when a risk assessment has been completed.
`createdAt`	number	Unix timestamp of creation.
`updatedAt`	number	Unix timestamp of last update.

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",
    "country": "AUS",
    "type": "company",
    "subType": "none",
    "name": "Smith Trustee Pty Ltd",
    "roles": ["trustee"],
    "submissionId": "sub-abc123",
    "industry": "Trustee Services",
    "website": "https://smithtrustee.com.au",
    "identifiers": {
      "acn": "123456789",
      "abn": "98765432101"
    },
    "addresses": {
      "registeredAddress": "Level 5, 100 Collins St, Melbourne VIC 3000",
      "principalPlaceOfBusiness": "Suite 10, 50 Bridge St, Sydney NSW 2000"
    },
    "idvRisk": "low",
    "createdAt": 1737254548899,
    "updatedAt": 1737254548899
  },
  "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
`president`	Leads the organisation's governing committee
`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"].