> ## Documentation Index
> Fetch the complete documentation index at: https://docs.byzantine.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Create entity account

> `email` and `associatedPersons.email` must be unique at each call of the endpoint.
For emails, you can use the `+` sign to make them unique, e.g. byzcorp+1@example.com.



## OpenAPI

````yaml /api-reference/openapi-integrator.json post /v1/submit/create-entity-account
openapi: 3.0.3
info:
  title: Byzantine Integrator API
  description: Byzantine REST API for integrators.
  license:
    name: ''
  version: 0.2.0
servers:
  - url: https://sandbox.api.byzantine.fi
    description: Sandbox
security: []
tags:
  - name: API health
    description: Check API status.
  - name: Customer management
    description: Endpoints to create, update, and retrieve customer information.
  - name: Account management
    description: Endpoints to manage accounts, bank accounts, invitations, and user roles.
  - name: Products
    description: Endpoints to get data about products and vaults.
  - name: Transactions
    description: Endpoints to create and manage transactions.
  - name: OTP authentication
    description: Endpoints to initialize and manage user authentication with OTP.
  - name: Webhooks
    description: Integrator-managed outbound webhook subscriptions and delivery history.
paths:
  /v1/submit/create-entity-account:
    post:
      tags:
        - Customer management
      summary: Create entity account
      description: >-
        `email` and `associatedPersons.email` must be unique at each call of the
        endpoint.

        For emails, you can use the `+` sign to make them unique, e.g.
        byzcorp+1@example.com.
      operationId: create_entity_account
      parameters:
        - name: X-Pubkey
          in: header
          description: >-
            Integrator's ECDSA public key (P-256 curve, compressed SEC1 format).
            Example:
            0x038fedef7c12f93bbf342ad8943b7a825a3b41f61c9dc118b2c718efebabbf62fd
          required: true
          schema:
            type: string
        - name: X-Timestamp
          in: header
          description: >-
            Unix timestamp in seconds (UTC). Must be within tolerance window (1
            minute) to prevent replay attacks. Example: 1760375826
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          description: >-
            ECDSA signature (DER-encoded, hex with 0x prefix). Signs the
            message: {timestamp}{METHOD}{path_and_query}{json_body}. Example:
            0x3045022100...
          required: true
          schema:
            type: string
      requestBody:
        description: Byzantine entity account creation body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEntityAccountRequest'
        required: true
      responses:
        '200':
          description: Entity account created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateEntityAccountResponse'
        '400':
          description: Invalid request payload
        '500':
          description: Internal server error
      security:
        - integrator_auth: []
components:
  schemas:
    CreateEntityAccountRequest:
      type: object
      description: Request body for creating a Byzantine entity
      required:
        - entityInfo
        - rootUsers
        - byzantineTermsSignedAt
      properties:
        entityInfo:
          $ref: '#/components/schemas/EntityInfo'
        entityDocuments:
          type: array
          items:
            $ref: '#/components/schemas/EntityVerificationDocument'
          nullable: true
        rootUsers:
          type: array
          items:
            $ref: '#/components/schemas/EntityRootUserRequest'
        associatedPersons:
          type: array
          items:
            $ref: '#/components/schemas/AssociatedPerson'
          nullable: true
        walletAddress:
          type: string
          description: >-
            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'
          nullable: true
        byzantineTermsSignedAt:
          type: string
          description: >-
            The timestamp when the Byzantine Finance Terms & Conditions were
            signed. For more information, see [individual account creation -
            KYC](https://docs.byzantine.fi/api-reference/kyc).
          example: '2025-11-19T21:14:58.328Z'
    CreateEntityAccountResponse:
      type: object
      description: Response body for creating a Byzantine entity
      required:
        - entityId
        - accountId
        - verificationStatus
        - entityInfo
        - rootUsers
        - walletAddress
        - byzantineTermsSignedAt
      properties:
        entityId:
          $ref: '#/components/schemas/Uuid'
        accountId:
          $ref: '#/components/schemas/Uuid'
        verificationStatus:
          $ref: '#/components/schemas/VerificationStatus'
        entityInfo:
          $ref: '#/components/schemas/EntityInfo'
        entityDocuments:
          type: array
          items:
            $ref: '#/components/schemas/VerificationDocumentResponse'
          nullable: true
        rootUsers:
          type: array
          items:
            $ref: '#/components/schemas/EntityRootUserResponse'
        associatedPersons:
          type: array
          items:
            $ref: '#/components/schemas/AssociatedPersonResponse'
          nullable: true
        walletAddress:
          type: string
          description: The wallet address associated with this account.
          example: '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18'
        byzantineTermsSignedAt:
          type: string
          description: >-
            The timestamp when the Byzantine Finance Terms & Conditions were
            signed. For more information, see [individual account creation -
            KYC](https://docs.byzantine.fi/api-reference/kyc).
          example: '2025-11-19T21:14:58.328Z'
        missingCompanyData:
          type: array
          items:
            type: string
          description: >-
            List of missing required company data. Present only if not all
            required company information has been provided.
          nullable: true
        missingDocuments:
          type: array
          items:
            type: string
          description: >-
            List of missing required entity verification documents. Present only
            if not all required documents have been submitted.
          nullable: true
    EntityInfo:
      type: object
      description: Entity information for KYB
      required:
        - businessLegalName
      properties:
        businessLegalName:
          type: string
          description: The legal name of the business.
          example: ByzCorp Incorporated
        businessTradeName:
          type: string
          description: The trade name of the business. Can be the same as the entity name.
          example: ByzCorp
          nullable: true
        businessType:
          allOf:
            - $ref: '#/components/schemas/BusinessType'
          nullable: true
        companyNumber:
          type: string
          description: >-
            The registered business number. Depending on the country of
            registration, we accept these [entity number
            types](https://docs.byzantine.fi/api-reference/lists/company-number-types).
          example: '123456789'
          nullable: true
        email:
          type: string
          description: Business contact email.
          example: byzcorp@example.com
          nullable: true
        website:
          type: string
          description: Business website.
          example: byzcorp.com
          nullable: true
        logoUrl:
          type: string
          description: URL of the entity's logo.
          example: https://byzcorp.com/logo.png
          nullable: true
        registeredAddress:
          allOf:
            - $ref: '#/components/schemas/Address'
          nullable: true
        physicalAddress:
          allOf:
            - $ref: '#/components/schemas/Address'
          nullable: true
        activityInfo:
          allOf:
            - $ref: '#/components/schemas/ActivityInfo'
          nullable: true
        financialInfo:
          allOf:
            - $ref: '#/components/schemas/FinancialInfo'
          nullable: true
        highRiskInfo:
          allOf:
            - $ref: '#/components/schemas/HighRiskInfo'
          nullable: true
    EntityVerificationDocument:
      type: object
      description: >-
        Entity verification document object. For a full list of required
        documents, see [accepted
        documents](https://docs.byzantine.fi/api-reference/documents).
      required:
        - documentType
        - issuingCountry
        - document
      properties:
        documentType:
          $ref: '#/components/schemas/EntityDocumentType'
        description:
          type: string
          description: >-
            A description of the document. Must be submitted if document if os
            type `other`.
          example: An overview of our business activities.
          nullable: true
        issuingCountry:
          $ref: '#/components/schemas/CountryCode'
        document:
          type: string
          format: data:[MIME];base64,[base64-encoded-data]
          description: >-
            The document to be uploaded.


            Supported MIME types: image/jpeg, image/png, image/heic, image/tiff,
            application/pdf
          example: data:image/png;base64,iVBORw0lFTkSuQmCC...
    EntityRootUserRequest:
      type: object
      description: Root user for acount management. At least one is required at creation.
      required:
        - firstName
        - lastName
        - email
      properties:
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: Smith
        email:
          type: string
          example: john.smith@example.com
        authenticators:
          type: array
          items:
            $ref: '#/components/schemas/AuthenticatorParam'
          nullable: true
    AssociatedPerson:
      type: object
      description: Associated person (beneficiary or representative).
      required:
        - userInfo
        - beneficiaryDetails
      properties:
        userInfo:
          $ref: '#/components/schemas/UserInfo'
        beneficiaryDetails:
          $ref: '#/components/schemas/BeneficiaryDetails'
        verificationDocuments:
          type: array
          items:
            $ref: '#/components/schemas/UserVerificationDocument'
          nullable: true
    Uuid:
      type: string
      format: uuid
      description: A UUID string
      example: 550e8400-e29b-41d4-a716-446655440000
    VerificationStatus:
      type: string
      description: The identity verification status of the user.
      enum:
        - not_started
        - init
        - under_review
        - awaiting_associated_person_information
        - awaiting_information
        - resubmission_requested
        - active
        - rejected
        - inactive
      example: active
    VerificationDocumentResponse:
      type: object
      description: Response body for verification documents.
      required:
        - documentType
        - issuingCountry
        - documentId
      properties:
        documentType:
          $ref: '#/components/schemas/DocumentType'
        documentNumber:
          type: string
          description: The full document number sent with the document.
          example: FR1234567890
          nullable: true
        description:
          type: string
          example: Additional supporting document
          nullable: true
        issuingCountry:
          type: string
          description: >-
            The ISO 3166-1 (three-character) country code of the relevant
            country. See the full list of
            [countries](https://docs.byzantine.fi/api-reference/lists/countries).
          example: FRA
        documentId:
          type: string
          description: Unique identifier assigned to the document.
          example: 830c219c-d197-451d-b879-77936a80c452
        warnings:
          type: array
          items:
            type: string
          nullable: true
        errors:
          type: array
          items:
            type: string
          nullable: true
    EntityRootUserResponse:
      type: object
      description: Root user with wallet access
      required:
        - userId
        - firstName
        - lastName
        - email
        - isPasskeyActivated
        - isOtpActivated
      properties:
        userId:
          $ref: '#/components/schemas/Uuid'
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: Smith
        email:
          type: string
          example: john.smith@example.com
        isPasskeyActivated:
          type: boolean
          description: >-
            An indicator showing whether passkey authentication is active for
            this user. For more information, see [authentication
            methods](https://docs.byzantine.fi/api-reference/authentication-methods).
          example: 'true'
        isOtpActivated:
          type: boolean
          description: >-
            An indicator showing whether OTP authentication is active for this
            user. For more information, see [authentication
            methods](https://docs.byzantine.fi/api-reference/authentication-methods).
          example: 'false'
    AssociatedPersonResponse:
      type: object
      description: Response body for an associated person
      required:
        - beneficiaryId
        - verificationStatus
        - userInfo
        - beneficiaryDetails
      properties:
        beneficiaryId:
          $ref: '#/components/schemas/Uuid'
        verificationStatus:
          $ref: '#/components/schemas/VerificationStatus'
        userInfo:
          $ref: '#/components/schemas/UserInfo'
        beneficiaryDetails:
          $ref: '#/components/schemas/BeneficiaryDetails'
        verificationDocuments:
          type: array
          items:
            $ref: '#/components/schemas/VerificationDocumentResponse'
          nullable: true
        missingDocuments:
          type: array
          items:
            type: string
          description: >-
            List of missing required verification documents. Present only if not
            all required documents have been submitted.
          nullable: true
    BusinessType:
      type: string
      description: >-
        Business legal form. Select that most appropriate one fitting your
        jurisdiction.
      enum:
        - cooperative
        - corporation
        - llc
        - other
        - partnership
        - sole_prop
        - trust
      example: llc
    Address:
      type: object
      description: Address information. Must be a valid address in the relevant country.
      required:
        - streetLine1
        - city
        - postalCode
        - country
      properties:
        streetLine1:
          type: string
          example: 33 Rue La Fayette
        streetLine2:
          type: string
          description: Optional additional details to the street name and number.
          example: WeWork
          nullable: true
        city:
          type: string
          example: Paris
        state:
          type: string
          description: >-
            Required for US addresses. Should be a valid ISO 3166-2 subdivision
            code.
          example: IDF
          nullable: true
        postalCode:
          type: string
          description: Postal code.
          example: '75009'
        country:
          $ref: '#/components/schemas/CountryCode'
    ActivityInfo:
      type: object
      description: >-
        Business activity details. Short business description and [industry
        code](https://docs.byzantine.fi/api-reference/lists/industry-codes#company-industry-codes)
      required:
        - businessDescription
        - businessIndustry
      properties:
        businessDescription:
          type: string
          example: ByzCorp does business.
          maxLength: 1024
          minLength: 1
        businessIndustry:
          type: integer
          format: int64
          example: 523110
          minimum: 0
    FinancialInfo:
      type: object
      description: Financial informations, required for compliance purposes.
      required:
        - preferredPrimaryCurrency
        - sourceOfFunds
        - estimatedAnnualRevenueUsd
        - expectedMonthlyPaymentsUsd
        - hasMaterialIntermediaryEntityOwner
      properties:
        preferredPrimaryCurrency:
          $ref: '#/components/schemas/Currency'
        sourceOfFunds:
          $ref: '#/components/schemas/EntitySourceOfFunds'
        estimatedAnnualRevenueUsd:
          $ref: '#/components/schemas/EstimatedAnnualRevenue'
        expectedMonthlyPaymentsUsd:
          type: integer
          format: int64
          example: '5000000'
        hasMaterialIntermediaryEntityOwner:
          type: boolean
          example: 'false'
    HighRiskInfo:
      type: object
      description: High risk business activities, required for compliance purposes.
      properties:
        operatesInProhibitedCountries:
          type: boolean
          example: 'false'
          nullable: true
        highRiskActivities:
          allOf:
            - $ref: '#/components/schemas/HighRiskActivity'
          nullable: true
        highRiskActivitiesExplanation:
          type: string
          nullable: true
        conductsMoneyServices:
          type: boolean
          example: 'false'
          nullable: true
        conductsMoneyServicesDescription:
          type: string
          nullable: true
    EntityDocumentType:
      type: string
      description: >-
        Entity document type. For a full list of accepted document types, see
        [accepted documents](https://docs.byzantine.fi/api-reference/documents).
      enum:
        - directors_registry
        - good_standing_cert
        - incorporation_articles
        - incorporation_cert
        - incumbency_cert
        - information_statement
        - partnership_agreement
        - power_of_attorney
        - proof_of_address
        - shareholder_registry
        - source_of_funds
        - state_registry
        - trust_agreement
        - other
      example: incorporation_cert
    CountryCode:
      type: string
      description: >-
        The ISO 3166-1 (three-character) country code of the relevant country.
        See the full list of
        [countries](https://docs.byzantine.fi/api-reference/lists/countries).
      enum:
        - ABW
        - AFG
        - AGO
        - ALB
        - AND
        - ARG
        - ARM
        - AUS
        - AUT
        - AZE
        - BEL
        - BGD
        - BGR
        - BHR
        - BHS
        - BIH
        - BLZ
        - BMU
        - BOL
        - BRA
        - BRB
        - BWA
        - CAN
        - CHL
        - CHN
        - CIV
        - CMR
        - COL
        - COM
        - CRI
        - CUW
        - CXR
        - CYM
        - CYP
        - CZE
        - DEU
        - DMA
        - DNK
        - DOM
        - DZA
        - ECU
        - EGY
        - ESP
        - EST
        - ETH
        - FIN
        - FJI
        - FRA
        - GBR
        - GEO
        - GHA
        - GIB
        - GRC
        - GTM
        - HKG
        - HND
        - HRV
        - HTI
        - HUN
        - IDN
        - IMN
        - IND
        - IRL
        - IRQ
        - ISL
        - ISR
        - ITA
        - JAM
        - JOR
        - JPN
        - KAZ
        - KEN
        - KGZ
        - KHM
        - KNA
        - KOR
        - KWT
        - LAO
        - LBN
        - LBR
        - LCA
        - LKA
        - LTU
        - LUX
        - LVA
        - MAR
        - MCO
        - MDA
        - MDG
        - MEX
        - MHL
        - MKD
        - MLT
        - MNE
        - MOZ
        - MRT
        - MUS
        - MWI
        - MYS
        - NAM
        - NGA
        - NIC
        - NLD
        - NOR
        - NPL
        - NZL
        - OMN
        - PAN
        - PER
        - PHL
        - PAK
        - POL
        - PRT
        - QAT
        - ROU
        - RUS
        - SAU
        - SEN
        - SGP
        - SVK
        - SVN
        - ZAF
        - SWE
        - CHE
        - THA
        - TUN
        - TUR
        - UGA
        - UKR
        - ARE
        - USA
        - URY
        - UZB
        - VEN
        - VNM
        - YEM
        - ZMB
        - ZWE
        - SMR
      example: FRA
    AuthenticatorParam:
      type: object
      description: Passkey authenticator object.
      required:
        - authenticatorName
        - challenge
        - attestation
      properties:
        authenticatorName:
          type: string
          description: Human-readable name for an Authenticator.
        challenge:
          type: string
          description: Challenge presented for authentication purposes.
        attestation:
          $ref: '#/components/schemas/Attestation'
    UserInfo:
      type: object
      description: Personal information about the user required for identity verification.
      required:
        - firstName
        - lastName
        - email
      properties:
        firstName:
          type: string
          description: First name of the user.
          example: John
        middleName:
          type: string
          description: Middle name of the user.
          example: William
          nullable: true
        lastName:
          type: string
          description: Last name of the user.
          example: Smith
        email:
          type: string
          description: Contact email of the user.
          example: john.smith@example.com
        phone:
          type: string
          description: Phone number of the user.
          example: +33 123 456 789
          nullable: true
        birthDate:
          type: string
          description: User's date of birth.
          example: '1990-01-01'
          nullable: true
        nationality:
          allOf:
            - $ref: '#/components/schemas/CountryCode'
          nullable: true
        residentialAddress:
          allOf:
            - $ref: '#/components/schemas/Address'
          nullable: true
        socialSecurityNumber:
          type: string
          description: >-
            Required exclusively for USA-based users. Must be the full social
            security number.
          example: 123-45-6789
          nullable: true
        profilePictureUrl:
          type: string
          description: URL of the user's profile picture (can be an avatar)
          nullable: true
        countryOfBirth:
          allOf:
            - $ref: '#/components/schemas/CountryCode'
          nullable: true
    BeneficiaryDetails:
      type: object
      description: Additional details about beneficiaries.
      required:
        - beneficiaryType
      properties:
        beneficiaryType:
          type: array
          items:
            $ref: '#/components/schemas/BeneficiaryType'
        title:
          type: string
          description: Required for representatives. The title held at the business.
          example: CEO
          nullable: true
        ownershipPercentage:
          type: number
          format: double
          description: Required for UBOs. The % of direct or indirect business ownership.
          example: '32.5'
          nullable: true
    UserVerificationDocument:
      type: object
      description: Document(s) to verify the identity of the user.
      required:
        - documentType
        - issuingCountry
        - document
      properties:
        documentType:
          $ref: '#/components/schemas/UserDocumentType'
        documentNumber:
          type: string
          description: >-
            Required for identity documents (passport, national ID). Must be the
            full document number.
          example: FR1234567890
          nullable: true
        description:
          type: string
          description: Required if document type is 'other'.
          example: Additional supporting document
          nullable: true
        issuingCountry:
          $ref: '#/components/schemas/CountryCode'
        document:
          type: string
          format: data:[MIME];base64,[base64-encoded-data]
          description: >-
            The document to be uploaded.


            Supported MIME types: image/jpeg, image/png, image/heic, image/tiff,
            application/pdf
          example: data:image/png;base64,iVBORw0lFTkSuQmCC...
    DocumentType:
      oneOf:
        - $ref: '#/components/schemas/UserDocumentType'
        - $ref: '#/components/schemas/EntityDocumentType'
      description: Type of verification document.
    Currency:
      type: string
      enum:
        - usd
        - eur
        - usdc
        - eurc
    EntitySourceOfFunds:
      type: string
      description: Source of funds for entities.
      enum:
        - business_loans
        - grants
        - inter_company_funds
        - investment_proceeds
        - legal_settlement
        - owners_capital
        - pension_retirement
        - sale_of_assets
        - sales_of_goods_and_services
        - tax_refund
        - third_party_funds
        - treasury_reserves
      example: treasury_reserves
    EstimatedAnnualRevenue:
      type: string
      description: Estimated annual business revenue in USD, defined as a range.
      enum:
        - '0_99999'
        - '100000_999999'
        - '1000000_9999999'
        - '10000000_49999999'
        - '50000000_249999999'
        - 250000000_plus
      example: '1000000_9999999'
    HighRiskActivity:
      type: string
      description: >-
        High risk business activities. Must be declared if the business is
        engaged in any.
      enum:
        - adult_entertainment
        - gambling
        - hold_client_funds
        - investment_services
        - lending_banking
        - marijuana_or_related_services
        - money_services
        - nicotine_tobacco_or_related_services
        - operate_foreign_exchange_virtual_currencies_brokerage_otc
        - pharmaceuticals
        - precious_metals_precious_stones_jewelry
        - safe_deposit_box_rentals
        - third_party_payment_processing
        - weapons_firearms_and_explosives
        - none_of_the_above
      example: none_of_the_above
    Attestation:
      type: object
      required:
        - credentialId
        - clientDataJson
        - attestationObject
        - transports
      properties:
        credentialId:
          type: string
          description: The cbor encoded then base64 url encoded id of the credential.
        clientDataJson:
          type: string
          description: >-
            A base64 url encoded payload containing metadata about the signing
            context and the challenge.
        attestationObject:
          type: string
          description: >-
            A base64 url encoded payload containing authenticator data and any
            attestation the webauthn provider chooses.
        transports:
          type: array
          items:
            $ref: '#/components/schemas/Transports'
    BeneficiaryType:
      type: string
      description: >-
        Beneficiary type.


        UBOs are any individuals who, directly or inderectly, own more than 25%
        of the business.


        Representatives are individuals who have direct control over daily
        operations.
      enum:
        - ubo
        - representative
      example: ubo
    UserDocumentType:
      type: string
      description: >-
        Type of the document. See the full list of [accepted
        documents](https://docs.byzantine.fi/api-reference/documents).
      enum:
        - passport
        - national_id_front
        - national_id_back
        - proof_of_address
        - other
    Transports:
      type: string
      enum:
        - AUTHENTICATOR_TRANSPORT_BLE
        - AUTHENTICATOR_TRANSPORT_INTERNAL
        - AUTHENTICATOR_TRANSPORT_NFC
        - AUTHENTICATOR_TRANSPORT_USB
        - AUTHENTICATOR_TRANSPORT_HYBRID
        - Unknown
  securitySchemes:
    integrator_auth:
      type: apiKey
      in: header
      name: X-Pubkey, X-Timestamp, X-Signature

````