Create individual account

curl --request POST \
  --url https://sandbox.api.byzantine.fi/v1/submit/create-individual-account \
  --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 '
{
  "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>"
  },
  "byzantineTermsSignedAt": "2025-11-19T21:14:58.328Z",
  "rootUsers": [
    {
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@example.com",
      "authenticators": [
        {
          "authenticatorName": "<string>",
          "challenge": "<string>",
          "attestation": {
            "credentialId": "<string>",
            "clientDataJson": "<string>",
            "attestationObject": "<string>",
            "transports": []
          }
        }
      ]
    }
  ],
  "additionalUserInfo": {
    "employmentStatus": "employed",
    "expectedMonthlyPaymentsUsd": "5000_9999",
    "sourceOfFunds": "salary",
    "mostRecentOccupation": "151252"
  },
  "verificationDocuments": [
    {
      "issuingCountry": "FRA",
      "document": "data:image/png;base64,iVBORw0lFTkSuQmCC...",
      "documentNumber": "FR1234567890",
      "description": "Additional supporting document"
    }
  ],
  "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"
}
'

import requests

url = "https://sandbox.api.byzantine.fi/v1/submit/create-individual-account"

payload = {
    "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>"
    },
    "byzantineTermsSignedAt": "2025-11-19T21:14:58.328Z",
    "rootUsers": [
        {
            "firstName": "John",
            "lastName": "Smith",
            "email": "john.smith@example.com",
            "authenticators": [
                {
                    "authenticatorName": "<string>",
                    "challenge": "<string>",
                    "attestation": {
                        "credentialId": "<string>",
                        "clientDataJson": "<string>",
                        "attestationObject": "<string>",
                        "transports": []
                    }
                }
            ]
        }
    ],
    "additionalUserInfo": {
        "employmentStatus": "employed",
        "expectedMonthlyPaymentsUsd": "5000_9999",
        "sourceOfFunds": "salary",
        "mostRecentOccupation": "151252"
    },
    "verificationDocuments": [
        {
            "issuingCountry": "FRA",
            "document": "data:image/png;base64,iVBORw0lFTkSuQmCC...",
            "documentNumber": "FR1234567890",
            "description": "Additional supporting document"
        }
    ],
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"
}
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({
    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>'
    },
    byzantineTermsSignedAt: '2025-11-19T21:14:58.328Z',
    rootUsers: [
      {
        firstName: 'John',
        lastName: 'Smith',
        email: 'john.smith@example.com',
        authenticators: [
          {
            authenticatorName: '<string>',
            challenge: '<string>',
            attestation: {
              credentialId: '<string>',
              clientDataJson: '<string>',
              attestationObject: '<string>',
              transports: []
            }
          }
        ]
      }
    ],
    additionalUserInfo: {
      employmentStatus: 'employed',
      expectedMonthlyPaymentsUsd: '5000_9999',
      sourceOfFunds: 'salary',
      mostRecentOccupation: '151252'
    },
    verificationDocuments: [
      {
        issuingCountry: 'FRA',
        document: 'data:image/png;base64,iVBORw0lFTkSuQmCC...',
        documentNumber: 'FR1234567890',
        description: 'Additional supporting document'
      }
    ],
    walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18'
  })
};

fetch('https://sandbox.api.byzantine.fi/v1/submit/create-individual-account', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "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>"
  },
  "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  "byzantineTermsSignedAt": "2025-11-19T21:14:58.328Z",
  "rootUsers": [
    {
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@example.com",
      "isPasskeyActivated": true,
      "isOtpActivated": false
    }
  ],
  "additionalUserInfo": {
    "employmentStatus": "employed",
    "expectedMonthlyPaymentsUsd": "5000_9999",
    "sourceOfFunds": "salary",
    "mostRecentOccupation": "151252"
  },
  "verificationDocuments": [
    {
      "documentType": "passport",
      "issuingCountry": "FRA",
      "documentId": "830c219c-d197-451d-b879-77936a80c452",
      "documentNumber": "FR1234567890",
      "description": "Additional supporting document",
      "warnings": [
        "<string>"
      ],
      "errors": [
        "<string>"
      ]
    }
  ],
  "missingDocuments": [
    "<string>"
  ]
}

Customer creation

Create individual account

The account beneficiary is the person described in user_info (the KYC subject). root_users are the signers: the owner themselves (same email), or a wealth manager / CGP operating on the owner’s behalf.

email must be unique at each call of the endpoint. You can use the + sign to make them unique, e.g. alice+1@example.com. It is possible to create an individual account with only the following details and then call the update-individual-account to complete the application:

firstName
lastName
email
byzantineTermsSignedAt

POST

submit

create-individual-account

Create individual account

curl --request POST \
  --url https://sandbox.api.byzantine.fi/v1/submit/create-individual-account \
  --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 '
{
  "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>"
  },
  "byzantineTermsSignedAt": "2025-11-19T21:14:58.328Z",
  "rootUsers": [
    {
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@example.com",
      "authenticators": [
        {
          "authenticatorName": "<string>",
          "challenge": "<string>",
          "attestation": {
            "credentialId": "<string>",
            "clientDataJson": "<string>",
            "attestationObject": "<string>",
            "transports": []
          }
        }
      ]
    }
  ],
  "additionalUserInfo": {
    "employmentStatus": "employed",
    "expectedMonthlyPaymentsUsd": "5000_9999",
    "sourceOfFunds": "salary",
    "mostRecentOccupation": "151252"
  },
  "verificationDocuments": [
    {
      "issuingCountry": "FRA",
      "document": "data:image/png;base64,iVBORw0lFTkSuQmCC...",
      "documentNumber": "FR1234567890",
      "description": "Additional supporting document"
    }
  ],
  "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"
}
'

import requests

url = "https://sandbox.api.byzantine.fi/v1/submit/create-individual-account"

payload = {
    "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>"
    },
    "byzantineTermsSignedAt": "2025-11-19T21:14:58.328Z",
    "rootUsers": [
        {
            "firstName": "John",
            "lastName": "Smith",
            "email": "john.smith@example.com",
            "authenticators": [
                {
                    "authenticatorName": "<string>",
                    "challenge": "<string>",
                    "attestation": {
                        "credentialId": "<string>",
                        "clientDataJson": "<string>",
                        "attestationObject": "<string>",
                        "transports": []
                    }
                }
            ]
        }
    ],
    "additionalUserInfo": {
        "employmentStatus": "employed",
        "expectedMonthlyPaymentsUsd": "5000_9999",
        "sourceOfFunds": "salary",
        "mostRecentOccupation": "151252"
    },
    "verificationDocuments": [
        {
            "issuingCountry": "FRA",
            "document": "data:image/png;base64,iVBORw0lFTkSuQmCC...",
            "documentNumber": "FR1234567890",
            "description": "Additional supporting document"
        }
    ],
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"
}
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({
    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>'
    },
    byzantineTermsSignedAt: '2025-11-19T21:14:58.328Z',
    rootUsers: [
      {
        firstName: 'John',
        lastName: 'Smith',
        email: 'john.smith@example.com',
        authenticators: [
          {
            authenticatorName: '<string>',
            challenge: '<string>',
            attestation: {
              credentialId: '<string>',
              clientDataJson: '<string>',
              attestationObject: '<string>',
              transports: []
            }
          }
        ]
      }
    ],
    additionalUserInfo: {
      employmentStatus: 'employed',
      expectedMonthlyPaymentsUsd: '5000_9999',
      sourceOfFunds: 'salary',
      mostRecentOccupation: '151252'
    },
    verificationDocuments: [
      {
        issuingCountry: 'FRA',
        document: 'data:image/png;base64,iVBORw0lFTkSuQmCC...',
        documentNumber: 'FR1234567890',
        description: 'Additional supporting document'
      }
    ],
    walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18'
  })
};

fetch('https://sandbox.api.byzantine.fi/v1/submit/create-individual-account', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "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>"
  },
  "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  "byzantineTermsSignedAt": "2025-11-19T21:14:58.328Z",
  "rootUsers": [
    {
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@example.com",
      "isPasskeyActivated": true,
      "isOtpActivated": false
    }
  ],
  "additionalUserInfo": {
    "employmentStatus": "employed",
    "expectedMonthlyPaymentsUsd": "5000_9999",
    "sourceOfFunds": "salary",
    "mostRecentOccupation": "151252"
  },
  "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...

Body

application/json

Byzantine individual account creation body

User to be created. The vast majority of fields are required in order to complete the identity verification process.

userInfo

object

required

Personal information about the user required for identity verification.

Show child attributes

byzantineTermsSignedAt

string

required

The timestamp when the Byzantine Finance Terms & Conditions were signed. For more information, see individual account creation - KYC.

Example:

"2025-11-19T21:14:58.328Z"

rootUsers

object[]

required

Show child attributes

additionalUserInfo

object | null

Additional user information for KYC. All fields are required when provided.

Show child attributes

verificationDocuments

object[] | null

Show child attributes

walletAddress

string | null

Optional wallet address for self-custodial accounts. If provided, no Turnkey sub-organization will be created and required_approvals will be set to 0.

Example:

"0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"

Response

Individual account created successfully

Response body for creating a Byzantine user

userId

string<uuid>

required

A UUID string

Example:

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

accountId

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

walletAddress

string

required

The wallet address associated with this account.

Example:

"0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"

byzantineTermsSignedAt

string

required

The timestamp when the Byzantine Finance Terms & Conditions were signed. For more information, see individual account creation - KYC.

Example:

"2025-11-19T21:14:58.328Z"

rootUsers

object[]

required

Show child attributes

additionalUserInfo

object | null

Additional user information for KYC. All fields are required when provided.

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

Create individual account

Authorizations

Headers

Body

Response