Get details of a single associated person

curl --request GET \
  --url https://sandbox.api.byzantine.fi/v1/query/get-associated-person-details \
  --header 'X-Pubkey: <x-pubkey>' \
  --header 'X-Pubkey, X-Timestamp, X-Signature: <api-key>' \
  --header 'X-Signature: <x-signature>' \
  --header 'X-Timestamp: <x-timestamp>'

import requests

url = "https://sandbox.api.byzantine.fi/v1/query/get-associated-person-details"

headers = {
    "X-Pubkey": "<x-pubkey>",
    "X-Timestamp": "<x-timestamp>",
    "X-Signature": "<x-signature>",
    "X-Pubkey, X-Timestamp, X-Signature": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'X-Pubkey': '<x-pubkey>',
    'X-Timestamp': '<x-timestamp>',
    'X-Signature': '<x-signature>',
    'X-Pubkey, X-Timestamp, X-Signature': '<api-key>'
  }
};

fetch('https://sandbox.api.byzantine.fi/v1/query/get-associated-person-details', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "beneficiaryId": "550e8400-e29b-41d4-a716-446655440000",
  "verificationStatus": "active",
  "userInfo": {
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@example.com",
    "middleName": "William",
    "phone": "+33 123 456 789",
    "birthDate": "1990-01-01",
    "nationality": "FRA",
    "countryOfBirth": "FRA",
    "residentialAddress": {
      "streetLine1": "33 Rue La Fayette",
      "city": "Paris",
      "postalCode": "75009",
      "country": "FRA",
      "streetLine2": "WeWork",
      "state": "IDF"
    },
    "socialSecurityNumber": "123-45-6789",
    "profilePictureUrl": "<string>"
  },
  "beneficiaryDetails": {
    "beneficiaryType": [
      "ubo"
    ],
    "title": "CEO",
    "ownershipPercentage": "32.5"
  },
  "verificationDocuments": [
    {
      "documentType": "passport",
      "issuingCountry": "FRA",
      "documentId": "830c219c-d197-451d-b879-77936a80c452",
      "documentNumber": "FR1234567890",
      "description": "Additional supporting document",
      "warnings": [
        "<string>"
      ],
      "errors": [
        "<string>"
      ]
    }
  ],
  "missingDocuments": [
    "<string>"
  ]
}

Customer management

Get details of a single associated person

This endpoint returns the full record of one beneficiary or representative of an entity:

Personal information (name, contact, birth details, residential address)
Beneficiary details (type, title held at the business, ownership share)
Verification status and the documents still missing

The beneficiaryId is returned by get-entity-details and by the associated person submit endpoints. A person belonging to another integrator returns the same 404 as one that does not exist, so this endpoint never reveals the existence of a foreign record.

GET

query

get-associated-person-details

Get details of a single associated person

curl --request GET \
  --url https://sandbox.api.byzantine.fi/v1/query/get-associated-person-details \
  --header 'X-Pubkey: <x-pubkey>' \
  --header 'X-Pubkey, X-Timestamp, X-Signature: <api-key>' \
  --header 'X-Signature: <x-signature>' \
  --header 'X-Timestamp: <x-timestamp>'

import requests

url = "https://sandbox.api.byzantine.fi/v1/query/get-associated-person-details"

headers = {
    "X-Pubkey": "<x-pubkey>",
    "X-Timestamp": "<x-timestamp>",
    "X-Signature": "<x-signature>",
    "X-Pubkey, X-Timestamp, X-Signature": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'X-Pubkey': '<x-pubkey>',
    'X-Timestamp': '<x-timestamp>',
    'X-Signature': '<x-signature>',
    'X-Pubkey, X-Timestamp, X-Signature': '<api-key>'
  }
};

fetch('https://sandbox.api.byzantine.fi/v1/query/get-associated-person-details', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "beneficiaryId": "550e8400-e29b-41d4-a716-446655440000",
  "verificationStatus": "active",
  "userInfo": {
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@example.com",
    "middleName": "William",
    "phone": "+33 123 456 789",
    "birthDate": "1990-01-01",
    "nationality": "FRA",
    "countryOfBirth": "FRA",
    "residentialAddress": {
      "streetLine1": "33 Rue La Fayette",
      "city": "Paris",
      "postalCode": "75009",
      "country": "FRA",
      "streetLine2": "WeWork",
      "state": "IDF"
    },
    "socialSecurityNumber": "123-45-6789",
    "profilePictureUrl": "<string>"
  },
  "beneficiaryDetails": {
    "beneficiaryType": [
      "ubo"
    ],
    "title": "CEO",
    "ownershipPercentage": "32.5"
  },
  "verificationDocuments": [
    {
      "documentType": "passport",
      "issuingCountry": "FRA",
      "documentId": "830c219c-d197-451d-b879-77936a80c452",
      "documentNumber": "FR1234567890",
      "description": "Additional supporting document",
      "warnings": [
        "<string>"
      ],
      "errors": [
        "<string>"
      ]
    }
  ],
  "missingDocuments": [
    "<string>"
  ]
}

Authorizations

X-Pubkey, X-Timestamp, X-Signature

string

header

required

Headers

X-Pubkey

string

required

Integrator's ECDSA public key (P-256 curve, compressed SEC1 format). Example: 0x038fedef7c12f93bbf342ad8943b7a825a3b41f61c9dc118b2c718efebabbf62fd

X-Timestamp

string

required

Unix timestamp in seconds (UTC). Must be within tolerance window (1 minute) to prevent replay attacks. Example: 1760375826

X-Signature

string

required

ECDSA signature (DER-encoded, hex with 0x prefix). Signs the message: {timestamp}{METHOD}{path_and_query}{json_body}. Example: 0x3045022100...

Query Parameters

beneficiaryId

string<uuid>

required

A UUID string

Example:

"550e8400-e29b-41d4-a716-446655440000"

Response

Associated person retrieved successfully

Response body for an associated person

beneficiaryId

string<uuid>

required

A UUID string

Example:

"550e8400-e29b-41d4-a716-446655440000"

verificationStatus

enum<string>

required

The identity verification status of the user.

Available options:

not_started,

init,

under_review,

awaiting_associated_person_information,

awaiting_information,

resubmission_requested,

active,

rejected,

inactive

Example:

"active"

userInfo

object

required

Personal information about the user required for identity verification.

Show child attributes

beneficiaryDetails

object

required

Additional details about beneficiaries.

Show child attributes

verificationDocuments

object[] | null

Show child attributes

missingDocuments

string[] | null

List of missing required verification documents. Present only if not all required documents have been submitted.

Integrator API

API endpoints

Get details of a single associated person

Authorizations

Headers

Query Parameters

Response