Skip to content
APIs/Parties/Beneficial owners

Create a beneficial owner

Request

Security
basicAuth
Path
partyIdstring, = 25 characters^par[a-zA-Z0-9-_]*0$required

A unique identifier for the party generated by us. This is sent in the response of your party creation call.

Headers
WP-Api-Versionstring, (date)required

The API version.

Example:2025-01-01
Bodyapplication/jsonrequired
beneficialOwnerReferencestring, [ 3 .. 64 ] characters^[A-Za-z0-9\-_ ]*$required

Your reference for this beneficial owner, must be unique within an entity.

Example:"Hosaka27384910"
personalDetailsobjectrequired
relationshipToBusinessobjectrequired
emailstring, (email)
phonesArray of objects
identityDocumentsArray of objects
{
  "beneficialOwnerReference": "xdl12goH60",
  "personalDetails": {
    "title": "Dr",
    "firstName": "John",
    "middleName": "Illusionet",
    "lastName": "Bailey",
    "alias": "John Smith",
    "socialSecurityNumber": "333-55-6666",
    "residentialStatus": "nonResident",
    "dateOfBirth": "1972-05-22",
    "nationality": "GB",
    "address": {
      "address1": "200 Downing Street",
      "address2": "Flat 404",
      "city": "London",
      "type": "home",
      "countryCode": "GB",
      "postalCode": "SW1A 2AA"
    },
    "currentAddressLessThanThreeYears": true,
    "previousHomeAddress": {
      "address1": "425 Oxford Street",
      "address2": "Flat 101",
      "city": "London",
      "type": "home",
      "countryCode": "GB",
      "postalCode": "W1D 1LP"
    }
  },
  "relationshipToBusiness": {
    "ownershipPercentage": 10,
    "director": false,
    "isPrincipalOwner": false,
    "position": "partner"
  },
  "identityDocuments": [
    {
      "type": "passport",
      "number": "B98765432",
      "issuingInstitution": "UK Passport Office",
      "issuingCountry": "GB",
      "validFrom": "2018-05-15",
      "validTo": "2028-05-15"
    }
  ],
  "email": "John.bailey@example.com",
  "phones": [
    {
      "number": "0205556789",
      "prefix": "44"
    }
  ]
}

Responses

Created

Bodyapplication/json
identityVerificationStatestringread-only
Enum:"verified""notVerified""pending""rejected""notApplicable""started""startedAction""pendingStepUpAction""pendingManualReview - stepUpReceived"
identityVerificationMethodstringread-only
Enum:"merchantCompliant""identityVerificationService"
identityVerificationDatestring, (date)read-only

A valid date as YYYY-MM-DD

Example:"2033-11-22"
urlstringread-only

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

messagestringread-only

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

beneficialOwnerReferencestring, [ 3 .. 64 ] characters^[A-Za-z0-9\-_ ]*$required

Your reference for this beneficial owner, must be unique within an entity.

Example:"Hosaka27384910"
beneficialOwnerIdstringread-only

A unique identifier for the beneficial owner generated by us.

personalDetailsobjectrequired
relationshipToBusinessobjectrequired
emailstring, (email)
phonesArray of objects
identityDocumentsArray of objects
dateTimeCreatedstringread-only

The date and time that the beneficial owner was created, as an ISO 8601 zoned date time.

Example:"2025-01-23T12:23:445.222Z"
versioninteger, (int32)read-only
dateTimeUpdatedstringread-only

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

Beneficial owner for existing party type company (modular)

{
  "identityVerificationState": "notVerified",
  "identityVerificationMethod": "identityVerificationService",
  "beneficialOwnerReference": "owner28",
  "beneficialOwnerId": "parNtJbNC8_fd_HRKyQRekiN0",
  "personalDetails": {
    "title": "Dr",
    "firstName": "John",
    "middleName": "Illusionet",
    "lastName": "Bailey",
    "alias": "John bailey",
    "socialSecurityNumber": "333-55-1666",
    "dateOfBirth": "1972-05-22",
    "address": {
      "address1": "200 Downing Street",
      "address2": "Flat 404",
      "city": "London",
      "countryCode": "GB",
      "postalCode": "SW1A 2AA",
      "type": "home"
    },
    "residentialStatus": "nonResident",
    "nationality": "GB",
    "currentAddressLessThanThreeYears": true,
    "previousHomeAddress": {
      "address1": "425 Oxford Street",
      "address2": "Flat 101",
      "city": "London",
      "countryCode": "GB",
      "postalCode": "W1D 1LP",
      "type": "home"
    }
  },
  "relationshipToBusiness": {
    "ownershipPercentage": 10,
    "director": false,
    "isPrincipalOwner": false,
    "position": "partner"
  },
  "email": "John.bailey@example.com",
  "phones": [
    {
      "prefix": "44",
      "number": "0205556789"
    }
  ],
  "identityDocuments": [
    {
      "type": "passport",
      "number": "B98765432",
      "issuingInstitution": "UK Passport Office",
      "issuingCountry": "GB",
      "validFrom": "2018-05-15",
      "validTo": "2028-05-15"
    }
  ],
  "dateTimeCreated": "2025-03-20T18:33:41.480Z",
  "version": 0
}