Stakeholders

Stakeholders are individuals or entities associated with a verification that require their own identity verification. Use this endpoint to update stakeholder requests when responding to info requests.

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 this endpoint to update stakeholder details before they complete their verification.

All stakeholder endpoints require a valid trace identifier, which uniquely identifies the parent verification. The verification must be in info status to update stakeholder requests.

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. 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`	The primary applicant or contact person for the verification
`director`	A director of the company or organization being verified
`shareholder`	A shareholder or owner of the entity
`beneficialOwner`	A beneficial owner with significant control or ownership
`trustee`	A trustee of a trust entity
`beneficiary`	A beneficiary of a trust
`settlor`	The settlor or creator of a trust
`partner`	A partner in a partnership entity
`secretary`	Company secretary
`authorizedRepresentative`	An authorized representative of the entity
`other`	Any other stakeholder type not covered above

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"].