Add an associated person to an entity account

curl --request POST \
  --url https://sandbox.api.byzantine.fi/v1/submit/add-associated-person \
  --header 'Content-Type: application/json' \
  --header 'X-Pubkey: <x-pubkey>' \
  --header 'X-Pubkey, X-Timestamp, X-Signature: <api-key>' \
  --header 'X-Signature: <x-signature>' \
  --header 'X-Timestamp: <x-timestamp>' \
  --data '
{
  "accountId": "550e8400-e29b-41d4-a716-446655440000",
  "associatedPerson": {
    "userInfo": {
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@example.com",
      "middleName": "William",
      "phone": "+33 123 456 789",
      "birthDate": "1990-01-01",
      "nationality": "FRA",
      "residentialAddress": {
        "streetLine1": "33 Rue La Fayette",
        "city": "Paris",
        "postalCode": "75009",
        "country": "FRA",
        "streetLine2": "WeWork",
        "state": "IDF"
      },
      "socialSecurityNumber": "123-45-6789",
      "profilePictureUrl": "<string>",
      "countryOfBirth": "FRA"
    },
    "beneficiaryDetails": {
      "beneficiaryType": [
        "ubo"
      ],
      "title": "CEO",
      "ownershipPercentage": "32.5"
    },
    "verificationDocuments": [
      {
        "issuingCountry": "FRA",
        "document": "data:image/png;base64,iVBORw0lFTkSuQmCC...",
        "documentNumber": "FR1234567890",
        "description": "Additional supporting document"
      }
    ]
  }
}
'

import requests

url = "https://sandbox.api.byzantine.fi/v1/submit/add-associated-person"

payload = {
    "accountId": "550e8400-e29b-41d4-a716-446655440000",
    "associatedPerson": {
        "userInfo": {
            "firstName": "John",
            "lastName": "Smith",
            "email": "john.smith@example.com",
            "middleName": "William",
            "phone": "+33 123 456 789",
            "birthDate": "1990-01-01",
            "nationality": "FRA",
            "residentialAddress": {
                "streetLine1": "33 Rue La Fayette",
                "city": "Paris",
                "postalCode": "75009",
                "country": "FRA",
                "streetLine2": "WeWork",
                "state": "IDF"
            },
            "socialSecurityNumber": "123-45-6789",
            "profilePictureUrl": "<string>",
            "countryOfBirth": "FRA"
        },
        "beneficiaryDetails": {
            "beneficiaryType": ["ubo"],
            "title": "CEO",
            "ownershipPercentage": "32.5"
        },
        "verificationDocuments": [
            {
                "issuingCountry": "FRA",
                "document": "data:image/png;base64,iVBORw0lFTkSuQmCC...",
                "documentNumber": "FR1234567890",
                "description": "Additional supporting document"
            }
        ]
    }
}
headers = {
    "X-Pubkey": "<x-pubkey>",
    "X-Timestamp": "<x-timestamp>",
    "X-Signature": "<x-signature>",
    "X-Pubkey, X-Timestamp, X-Signature": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Pubkey': '<x-pubkey>',
    'X-Timestamp': '<x-timestamp>',
    'X-Signature': '<x-signature>',
    'X-Pubkey, X-Timestamp, X-Signature': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    accountId: '550e8400-e29b-41d4-a716-446655440000',
    associatedPerson: {
      userInfo: {
        firstName: 'John',
        lastName: 'Smith',
        email: 'john.smith@example.com',
        middleName: 'William',
        phone: '+33 123 456 789',
        birthDate: '1990-01-01',
        nationality: 'FRA',
        residentialAddress: {
          streetLine1: '33 Rue La Fayette',
          city: 'Paris',
          postalCode: '75009',
          country: 'FRA',
          streetLine2: 'WeWork',
          state: 'IDF'
        },
        socialSecurityNumber: '123-45-6789',
        profilePictureUrl: '<string>',
        countryOfBirth: 'FRA'
      },
      beneficiaryDetails: {beneficiaryType: ['ubo'], title: 'CEO', ownershipPercentage: '32.5'},
      verificationDocuments: [
        {
          issuingCountry: 'FRA',
          document: 'data:image/png;base64,iVBORw0lFTkSuQmCC...',
          documentNumber: 'FR1234567890',
          description: 'Additional supporting document'
        }
      ]
    }
  })
};

fetch('https://sandbox.api.byzantine.fi/v1/submit/add-associated-person', 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",
    "residentialAddress": {
      "streetLine1": "33 Rue La Fayette",
      "city": "Paris",
      "postalCode": "75009",
      "country": "FRA",
      "streetLine2": "WeWork",
      "state": "IDF"
    },
    "socialSecurityNumber": "123-45-6789",
    "profilePictureUrl": "<string>",
    "countryOfBirth": "FRA"
  },
  "beneficiaryDetails": {
    "beneficiaryType": [
      "ubo"
    ],
    "title": "CEO",
    "ownershipPercentage": "32.5"
  },
  "verificationDocuments": [
    {
      "issuingCountry": "FRA",
      "documentId": "830c219c-d197-451d-b879-77936a80c452",
      "documentNumber": "FR1234567890",
      "description": "Additional supporting document",
      "warnings": [
        "<string>"
      ],
      "errors": [
        "<string>"
      ]
    }
  ],
  "missingDocuments": [
    "<string>"
  ]
}

POST

submit

add-associated-person

Add an associated person to an entity account

curl --request POST \
  --url https://sandbox.api.byzantine.fi/v1/submit/add-associated-person \
  --header 'Content-Type: application/json' \
  --header 'X-Pubkey: <x-pubkey>' \
  --header 'X-Pubkey, X-Timestamp, X-Signature: <api-key>' \
  --header 'X-Signature: <x-signature>' \
  --header 'X-Timestamp: <x-timestamp>' \
  --data '
{
  "accountId": "550e8400-e29b-41d4-a716-446655440000",
  "associatedPerson": {
    "userInfo": {
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@example.com",
      "middleName": "William",
      "phone": "+33 123 456 789",
      "birthDate": "1990-01-01",
      "nationality": "FRA",
      "residentialAddress": {
        "streetLine1": "33 Rue La Fayette",
        "city": "Paris",
        "postalCode": "75009",
        "country": "FRA",
        "streetLine2": "WeWork",
        "state": "IDF"
      },
      "socialSecurityNumber": "123-45-6789",
      "profilePictureUrl": "<string>",
      "countryOfBirth": "FRA"
    },
    "beneficiaryDetails": {
      "beneficiaryType": [
        "ubo"
      ],
      "title": "CEO",
      "ownershipPercentage": "32.5"
    },
    "verificationDocuments": [
      {
        "issuingCountry": "FRA",
        "document": "data:image/png;base64,iVBORw0lFTkSuQmCC...",
        "documentNumber": "FR1234567890",
        "description": "Additional supporting document"
      }
    ]
  }
}
'

import requests

url = "https://sandbox.api.byzantine.fi/v1/submit/add-associated-person"

payload = {
    "accountId": "550e8400-e29b-41d4-a716-446655440000",
    "associatedPerson": {
        "userInfo": {
            "firstName": "John",
            "lastName": "Smith",
            "email": "john.smith@example.com",
            "middleName": "William",
            "phone": "+33 123 456 789",
            "birthDate": "1990-01-01",
            "nationality": "FRA",
            "residentialAddress": {
                "streetLine1": "33 Rue La Fayette",
                "city": "Paris",
                "postalCode": "75009",
                "country": "FRA",
                "streetLine2": "WeWork",
                "state": "IDF"
            },
            "socialSecurityNumber": "123-45-6789",
            "profilePictureUrl": "<string>",
            "countryOfBirth": "FRA"
        },
        "beneficiaryDetails": {
            "beneficiaryType": ["ubo"],
            "title": "CEO",
            "ownershipPercentage": "32.5"
        },
        "verificationDocuments": [
            {
                "issuingCountry": "FRA",
                "document": "data:image/png;base64,iVBORw0lFTkSuQmCC...",
                "documentNumber": "FR1234567890",
                "description": "Additional supporting document"
            }
        ]
    }
}
headers = {
    "X-Pubkey": "<x-pubkey>",
    "X-Timestamp": "<x-timestamp>",
    "X-Signature": "<x-signature>",
    "X-Pubkey, X-Timestamp, X-Signature": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Pubkey': '<x-pubkey>',
    'X-Timestamp': '<x-timestamp>',
    'X-Signature': '<x-signature>',
    'X-Pubkey, X-Timestamp, X-Signature': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    accountId: '550e8400-e29b-41d4-a716-446655440000',
    associatedPerson: {
      userInfo: {
        firstName: 'John',
        lastName: 'Smith',
        email: 'john.smith@example.com',
        middleName: 'William',
        phone: '+33 123 456 789',
        birthDate: '1990-01-01',
        nationality: 'FRA',
        residentialAddress: {
          streetLine1: '33 Rue La Fayette',
          city: 'Paris',
          postalCode: '75009',
          country: 'FRA',
          streetLine2: 'WeWork',
          state: 'IDF'
        },
        socialSecurityNumber: '123-45-6789',
        profilePictureUrl: '<string>',
        countryOfBirth: 'FRA'
      },
      beneficiaryDetails: {beneficiaryType: ['ubo'], title: 'CEO', ownershipPercentage: '32.5'},
      verificationDocuments: [
        {
          issuingCountry: 'FRA',
          document: 'data:image/png;base64,iVBORw0lFTkSuQmCC...',
          documentNumber: 'FR1234567890',
          description: 'Additional supporting document'
        }
      ]
    }
  })
};

fetch('https://sandbox.api.byzantine.fi/v1/submit/add-associated-person', 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",
    "residentialAddress": {
      "streetLine1": "33 Rue La Fayette",
      "city": "Paris",
      "postalCode": "75009",
      "country": "FRA",
      "streetLine2": "WeWork",
      "state": "IDF"
    },
    "socialSecurityNumber": "123-45-6789",
    "profilePictureUrl": "<string>",
    "countryOfBirth": "FRA"
  },
  "beneficiaryDetails": {
    "beneficiaryType": [
      "ubo"
    ],
    "title": "CEO",
    "ownershipPercentage": "32.5"
  },
  "verificationDocuments": [
    {
      "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...

Body

application/json

Add an associated person to an entity account

Request body for adding an associated person to an entity account.

accountId

string<uuid>

required

A UUID string

Example:

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

associatedPerson

object

required

Associated person (beneficiary or representative).

Show child attributes

Response

Associated person added 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.

Update an entity account's company details Update an associated person's details

Integrator API

API endpoints

Add an associated person to an entity account

Authorizations

Headers

Body

Response