# Update a beneficial owner

Endpoint: PUT /parties/{partyId}/beneficialOwners/{beneficialOwnerId}
Version: 2025-01-01
Security: basicAuth

## Path parameters:

  - `partyId` (string, required)
    A unique identifier for the party generated by us. This is sent in the response of your party creation call.

  - `beneficialOwnerId` (string, required)
    A unique identifier for the beneficialOwner generated by us. This is sent in the response of your beneficialOwner creation call.

## Header parameters:

  - `WP-Api-Version` (string, required)
    The API version.
    Example: "2025-01-01"

## Request fields (application/json):

  - `beneficialOwnerReference` (string, required)
    Your reference for this beneficial owner, must be unique within an entity.
    Example: "Hosaka27384910"

  - `personalDetails` (object, required)

  - `personalDetails.title` (string, required)
    The title for this person/soleTrader.
    Enum: "Mr", "Mrs", "Miss", "Ms", "Dr", "Mx", "Misc"

  - `personalDetails.firstName` (string, required)
    The person's/soleTrader's first name.
    Example: "Case"

  - `personalDetails.middleName` (string)
    The person's/soleTrader's middle name or initial.
    Example: "Henry"

  - `personalDetails.lastName` (string, required)
    The person's/soleTrader's last name.
    Example: "Mitchell"

  - `personalDetails.alias` (string)
    An alternative or commonly-used name for the individual (e.g., preferred or informal name). Does not replace the legal name.
    Example: "Junior Case"

  - `personalDetails.socialSecurityNumber` (string)
    The individual’s U.S. Social Security Number (SSN), required for U.S.-based tax or identity checks.
    Example: "004-54-6578"

  - `personalDetails.dateOfBirth` (string)
    The date the person/soleTrader was born.
    Example: "1983-10-12"

  - `personalDetails.address` (object, required)
    Object containing details about the address.

  - `personalDetails.address.address1` (string, required)
    The address.

 Must consist of at least two letters, two words, and one number.
    Example: "1847 Kingsbury Court"

  - `personalDetails.address.address2` (string)
    Line two of the address.
    Example: "Unit 42"

  - `personalDetails.address.city` (string, required)
    The city of this address.
    Example: "London"

  - `personalDetails.address.state` (string)
    The state of this address.
    Example: "Greater London"

  - `personalDetails.address.countryCode` (string, required)
    The country code specified in [ISO 3166-1 Alpha-2 code format](/products/reference/supported-countries-currencies#iso-country-codes).
    Example: "GB"

  - `personalDetails.address.postalCode` (string)
    The postal code of this address.
    Example: "NW9 0RR"

  - `personalDetails.address.type` (string)
    Identifies the type of this address.
    Enum: "home", "business", "poBox", "other"

  - `personalDetails.residentialStatus` (string)
    The residential status of the person/soleTrader.
    Enum: "resident", "nonResident", "other"

  - `personalDetails.customerReference` (string)
    Unique reference provided by the payee. Only required for certain payout destinations.
    Example: "7564389201"

  - `personalDetails.nationality` (string)
    The nationality of the person/soleTrader.

  - `personalDetails.currentAddressLessThanThreeYears` (boolean)

  - `personalDetails.previousHomeAddress` (object)
    Object containing details about the address.

  - `personalDetails.previousHomeAddress.address1` (string, required)
    The address.

 Must consist of at least two letters, two words, and one number.
    Example: "1847 Kingsbury Court"

  - `personalDetails.previousHomeAddress.address2` (string)
    Line two of the address.
    Example: "Unit 42"

  - `personalDetails.previousHomeAddress.city` (string, required)
    The city of this address.
    Example: "London"

  - `personalDetails.previousHomeAddress.state` (string)
    The state of this address.
    Example: "Greater London"

  - `personalDetails.previousHomeAddress.countryCode` (string, required)
    The country code specified in [ISO 3166-1 Alpha-2 code format](/products/reference/supported-countries-currencies#iso-country-codes).
    Example: "GB"

  - `personalDetails.previousHomeAddress.postalCode` (string)
    The postal code of this address.
    Example: "NW9 0RR"

  - `personalDetails.previousHomeAddress.type` (string)
    Identifies the type of this address.
    Enum: "home", "business", "poBox", "other"

  - `personalDetails.website` (string)
    The URL of the merchant's website.
    Example: "https://example.com/"

  - `relationshipToBusiness` (object, required)

  - `relationshipToBusiness.ownershipPercentage` (number, required)
    Percentage of the ownership of the beneficial owner over the company.

  - `relationshipToBusiness.director` (boolean, required)
    A flag indicating if the beneficial owner is also a director for the company.

  - `relationshipToBusiness.isPrincipalOwner` (boolean)
    A flag indicating if the beneficial owner is also a principal owner for the company.
{% admonition type="info" name="Note" %}You can set no more than one beneficial owner per party record of type company, as principal owner.{% /admonition %}
    Example: true

  - `relationshipToBusiness.position` (string, required)
    Type of position of the beneficial owner within the company.
    Enum: "soleTrader", "accountant", "bursar", "chairman", "chairwoman", "chiefExecutiveOfficer", "clerk", "companySecretary", "creditController", "deputyLeader", "generalManager", "leader", "manager", "managingDirector", "master", "guarantor", "mayor", "officeManager", "operationsManager", "president", "principal", "proprietor", "townClerk", "director", "apportionmentAndOversight", "chiefExecutive", "complianceOversight", "directorUnincorporatedAssociate", "nonExecutiveDirector", "significantManagement", "smallFriendlySociety", "chairperson", "designatedMember", "secretary", "trustee", "treasurer", "businessRepresentative", "authorisedSignatory", "signatory", "technicalContact", "contractSignatory", "publicOfficer", "controller", "beneficialOwner", "partner", "shareholder", "chiefFinancialOfficer", "chiefOperatingOfficer", "beneficiary", "charitySecretary", "member", "protector", "settlor", "soleProprietor", "nonDesignatedMember"

  - `email` (string)

  - `phones` (array)

  - `phones.prefix` (string, required)
    The dialing prefix for the phone number.
    Example: "44"

  - `phones.number` (string, required)
    The phone number, without dashes.
    Example: "4281234"

  - `identityDocuments` (array)

  - `identityDocuments.type` (string, required)
    The type of the identity document.
    Enum: "passport", "nationalId", "driverLicence", "workPermit", "employmentPass", "studentPass", "permanentResidentCard", "companyRegistrationNumber", "companyVATNumber", "citizenshipCard", "taxId", "nationalInsurance", "other", "legalIdentityCard", "taxRegistrationCode"

  - `identityDocuments.number` (string, required)

  - `identityDocuments.issuingInstitution` (string)
    The name of the institution that issued this document.
    Example: "State Department"

  - `identityDocuments.issuingCountry` (string, required)
    The country code of the issuing country specified in [ISO 3166-1 Alpha-2 code](/products/reference/supported-countries-currencies#iso-country-codes) format.
    Example: "JP"

  - `identityDocuments.validFrom` (string)
    The ISO 8601 date since when this document is valid from.
    Example: "2023-11-22"

  - `identityDocuments.validTo` (string)
    The ISO 8601 date until which this document is valid to.
    Example: "2023-11-22"

## Response 200 fields (application/json):

  - `identityVerificationState` (string)
    Enum: "verified", "notVerified", "pending", "rejected", "notApplicable", "started", "startedAction", "pendingStepUpAction", "pendingManualReview - stepUpReceived"

  - `identityVerificationMethod` (string)
    Enum: "merchantCompliant", "identityVerificationService"

  - `identityVerificationDate` (string)
    A valid date as YYYY-MM-DD
    Example: "2033-11-22"

  - `url` (string)
    The link returned from Identity Verification Status (IVS) used to retrieve additional details from the user.

  - `message` (string)
    The message associated with link returned from Identity Verification Status (IVS).

  - `beneficialOwnerReference` (string, required)
    Your reference for this beneficial owner, must be unique within an entity.
    Example: "Hosaka27384910"

  - `beneficialOwnerId` (string)
    A unique identifier for the beneficial owner generated by us.

  - `personalDetails` (object, required)

  - `personalDetails.title` (string, required)
    The title for this person/soleTrader.
    Enum: "Mr", "Mrs", "Miss", "Ms", "Dr", "Mx", "Misc"

  - `personalDetails.firstName` (string, required)
    The person's/soleTrader's first name.
    Example: "Case"

  - `personalDetails.middleName` (string)
    The person's/soleTrader's middle name or initial.
    Example: "Henry"

  - `personalDetails.lastName` (string, required)
    The person's/soleTrader's last name.
    Example: "Mitchell"

  - `personalDetails.alias` (string)
    An alternative or commonly-used name for the individual (e.g., preferred or informal name). Does not replace the legal name.
    Example: "Junior Case"

  - `personalDetails.socialSecurityNumber` (string)
    The individual’s U.S. Social Security Number (SSN), required for U.S.-based tax or identity checks.
    Example: "004-54-6578"

  - `personalDetails.dateOfBirth` (string)
    The date the person/soleTrader was born.
    Example: "1983-10-12"

  - `personalDetails.address` (object, required)
    Object containing details about the address.

  - `personalDetails.address.address1` (string, required)
    The address.

 Must consist of at least two letters, two words, and one number.
    Example: "1847 Kingsbury Court"

  - `personalDetails.address.address2` (string)
    Line two of the address.
    Example: "Unit 42"

  - `personalDetails.address.city` (string, required)
    The city of this address.
    Example: "London"

  - `personalDetails.address.state` (string)
    The state of this address.
    Example: "Greater London"

  - `personalDetails.address.countryCode` (string, required)
    The country code specified in [ISO 3166-1 Alpha-2 code format](/products/reference/supported-countries-currencies#iso-country-codes).
    Example: "GB"

  - `personalDetails.address.postalCode` (string)
    The postal code of this address.
    Example: "NW9 0RR"

  - `personalDetails.address.type` (string)
    Identifies the type of this address.
    Enum: "home", "business", "poBox", "other"

  - `personalDetails.residentialStatus` (string)
    The residential status of the person/soleTrader.
    Enum: "resident", "nonResident", "other"

  - `personalDetails.customerReference` (string)
    Unique reference provided by the payee. Only required for certain payout destinations.
    Example: "7564389201"

  - `personalDetails.nationality` (string)
    The nationality of the person/soleTrader.

  - `personalDetails.currentAddressLessThanThreeYears` (boolean)

  - `personalDetails.previousHomeAddress` (object)
    Object containing details about the address.

  - `personalDetails.previousHomeAddress.address1` (string, required)
    The address.

 Must consist of at least two letters, two words, and one number.
    Example: "1847 Kingsbury Court"

  - `personalDetails.previousHomeAddress.address2` (string)
    Line two of the address.
    Example: "Unit 42"

  - `personalDetails.previousHomeAddress.city` (string, required)
    The city of this address.
    Example: "London"

  - `personalDetails.previousHomeAddress.state` (string)
    The state of this address.
    Example: "Greater London"

  - `personalDetails.previousHomeAddress.countryCode` (string, required)
    The country code specified in [ISO 3166-1 Alpha-2 code format](/products/reference/supported-countries-currencies#iso-country-codes).
    Example: "GB"

  - `personalDetails.previousHomeAddress.postalCode` (string)
    The postal code of this address.
    Example: "NW9 0RR"

  - `personalDetails.previousHomeAddress.type` (string)
    Identifies the type of this address.
    Enum: "home", "business", "poBox", "other"

  - `personalDetails.website` (string)
    The URL of the merchant's website.
    Example: "https://example.com/"

  - `relationshipToBusiness` (object, required)

  - `relationshipToBusiness.ownershipPercentage` (number, required)
    Percentage of the ownership of the beneficial owner over the company.

  - `relationshipToBusiness.director` (boolean, required)
    A flag indicating if the beneficial owner is also a director for the company.

  - `relationshipToBusiness.isPrincipalOwner` (boolean)
    A flag indicating if the beneficial owner is also a principal owner for the company.
{% admonition type="info" name="Note" %}You can set no more than one beneficial owner per party record of type company, as principal owner.{% /admonition %}
    Example: true

  - `relationshipToBusiness.position` (string, required)
    Type of position of the beneficial owner within the company.
    Enum: "soleTrader", "accountant", "bursar", "chairman", "chairwoman", "chiefExecutiveOfficer", "clerk", "companySecretary", "creditController", "deputyLeader", "generalManager", "leader", "manager", "managingDirector", "master", "guarantor", "mayor", "officeManager", "operationsManager", "president", "principal", "proprietor", "townClerk", "director", "apportionmentAndOversight", "chiefExecutive", "complianceOversight", "directorUnincorporatedAssociate", "nonExecutiveDirector", "significantManagement", "smallFriendlySociety", "chairperson", "designatedMember", "secretary", "trustee", "treasurer", "businessRepresentative", "authorisedSignatory", "signatory", "technicalContact", "contractSignatory", "publicOfficer", "controller", "beneficialOwner", "partner", "shareholder", "chiefFinancialOfficer", "chiefOperatingOfficer", "beneficiary", "charitySecretary", "member", "protector", "settlor", "soleProprietor", "nonDesignatedMember"

  - `email` (string)

  - `phones` (array)

  - `phones.prefix` (string, required)
    The dialing prefix for the phone number.
    Example: "44"

  - `phones.number` (string, required)
    The phone number, without dashes.
    Example: "4281234"

  - `identityDocuments` (array)

  - `identityDocuments.type` (string, required)
    The type of the identity document.
    Enum: "passport", "nationalId", "driverLicence", "workPermit", "employmentPass", "studentPass", "permanentResidentCard", "companyRegistrationNumber", "companyVATNumber", "citizenshipCard", "taxId", "nationalInsurance", "other", "legalIdentityCard", "taxRegistrationCode"

  - `identityDocuments.number` (string, required)

  - `identityDocuments.issuingInstitution` (string)
    The name of the institution that issued this document.
    Example: "State Department"

  - `identityDocuments.issuingCountry` (string, required)
    The country code of the issuing country specified in [ISO 3166-1 Alpha-2 code](/products/reference/supported-countries-currencies#iso-country-codes) format.
    Example: "JP"

  - `identityDocuments.validFrom` (string)
    The ISO 8601 date since when this document is valid from.
    Example: "2023-11-22"

  - `identityDocuments.validTo` (string)
    The ISO 8601 date until which this document is valid to.
    Example: "2023-11-22"

  - `dateTimeCreated` (string)
    The date and time that the beneficial owner was created, as an ISO 8601 zoned date time.
    Example: "2025-01-23T12:23:445.222Z"

  - `version` (integer)

  - `dateTimeUpdated` (string)
    The date and time that the beneficial owner was last updated, as an ISO 8601 zoned date time.
    Example: "2025-01-25T14:57:012.302Z"

## Response 400 fields (application/json):

  - `errorName` (string)
    An ordinal error type that is part of the API contract. It is machine readable, but also human readable for clarity and semantic understanding of the error.
    Example: "bodyDoesNotMatchSchema"

  - `message` (string)
    A human readable message giving a corrective action for the error. THIS IS NOT FOR MACHINE CONSUMPTION.

  - `validationErrors` (array)

  - `validationErrors.errorName` (string)

  - `validationErrors.message` (string)

  - `validationErrors.path` (string)

  - `validationErrors.jsonPath` (string)

  - `validationErrors.queryParameter` (string)

  - `validationErrors.pathParameter` (string)

  - `pathParameter` (string)

  - `queryParameter` (string)

  - `jsonPath` (string)

## Response 500 fields (application/json):

  - `errorName` (string)
    An ordinal error type that is part of the API contract. It is machine readable, but also human readable for clarity and semantic understanding of the error.
    Example: "bodyDoesNotMatchSchema"

  - `message` (string)
    A human readable message giving a corrective action for the error. THIS IS NOT FOR MACHINE CONSUMPTION.

  - `validationErrors` (array)

  - `validationErrors.errorName` (string)

  - `validationErrors.message` (string)

  - `validationErrors.path` (string)

  - `validationErrors.jsonPath` (string)

  - `validationErrors.queryParameter` (string)

  - `validationErrors.pathParameter` (string)

  - `pathParameter` (string)

  - `queryParameter` (string)

  - `jsonPath` (string)

## Response 503 fields (application/json):

  - `errorName` (string)
    An ordinal error type that is part of the API contract. It is machine readable, but also human readable for clarity and semantic understanding of the error.
    Example: "bodyDoesNotMatchSchema"

  - `message` (string)
    A human readable message giving a corrective action for the error. THIS IS NOT FOR MACHINE CONSUMPTION.

  - `validationErrors` (array)

  - `validationErrors.errorName` (string)

  - `validationErrors.message` (string)

  - `validationErrors.path` (string)

  - `validationErrors.jsonPath` (string)

  - `validationErrors.queryParameter` (string)

  - `validationErrors.pathParameter` (string)

  - `pathParameter` (string)

  - `queryParameter` (string)

  - `jsonPath` (string)