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

# Add an owner and its ownership edge in one request



## OpenAPI

````yaml /openapi.json post /api/v1/kyb/b2b/kyb/owners
openapi: 3.1.0
info:
  title: HEVN API
  description: Backend API for HEVN mobile neobank
  version: 0.1.2
servers: []
security: []
paths:
  /api/v1/kyb/b2b/kyb/owners:
    post:
      tags:
        - B2B
        - kyb
      summary: Add an owner and its ownership edge in one request
      operationId: create_kyb_owner_package_alias_api_v1_kyb_b2b_kyb_owners_post
      parameters:
        - name: x-api-key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KybOwnerCreateRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KybOwnerResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    KybOwnerCreateRequest:
      properties:
        ownershipPercentage:
          anyOf:
            - type: number
              maximum: 100
              exclusiveMinimum: 0
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Ownershippercentage
        entity:
          $ref: '#/components/schemas/EntityDraftWrite'
        targetEntityId:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Targetentityid
        hasControl:
          type: boolean
          title: Hascontrol
          default: false
        isDirector:
          type: boolean
          title: Isdirector
          default: false
        isSigner:
          type: boolean
          title: Issigner
          default: false
      type: object
      required:
        - entity
      title: KybOwnerCreateRequest
      description: >-
        Add an owner: the person (or holding company) AND the edge that makes

        them one.


        Two requests could not express this. An entity saved without its edge is

        unreachable from the ownership walk, so nothing could ever show it again
        —

        which is how editors accumulated people nobody could see.
    KybOwnerResponse:
      properties:
        entity:
          $ref: '#/components/schemas/EntityData'
        relationship:
          $ref: '#/components/schemas/EntityRelationshipDraftData'
      type: object
      required:
        - entity
        - relationship
      title: KybOwnerResponse
      description: Both halves of the owner that was just created, with their ids.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    EntityDraftWrite:
      properties:
        id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Id
        firstName:
          anyOf:
            - type: string
            - type: 'null'
          title: Firstname
        middleName:
          anyOf:
            - type: string
            - type: 'null'
          title: Middlename
        lastName:
          anyOf:
            - type: string
            - type: 'null'
          title: Lastname
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
        phone:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone
        country:
          anyOf:
            - $ref: '#/components/schemas/CountryCode'
            - type: 'null'
        dateOfBirth:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Dateofbirth
        birthCountry:
          anyOf:
            - $ref: '#/components/schemas/CountryCode'
            - type: 'null'
        nationalities:
          anyOf:
            - items:
                $ref: '#/components/schemas/CountryCode'
              type: array
            - type: 'null'
          title: Nationalities
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
          deprecated: true
        legalName:
          anyOf:
            - type: string
            - type: 'null'
          title: Legalname
        tradeName:
          anyOf:
            - type: string
            - type: 'null'
          title: Tradename
        registrationNumber:
          anyOf:
            - type: string
            - type: 'null'
          title: Registrationnumber
        taxId:
          anyOf:
            - type: string
              maxLength: 64
            - type: 'null'
          title: Taxid
          description: >-
            As the registry issues it. No shape is imposed — the per-country
            pattern the provider sends in the requirement constraints is the
            only one that applies. The bound is a size guard, not a format.
        address:
          anyOf:
            - $ref: '#/components/schemas/EntityAddress'
            - type: 'null'
        documents:
          anyOf:
            - additionalProperties:
                items:
                  type: string
                  format: uuid
                type: array
              type: object
            - type: 'null'
          title: Documents
        identityDocuments:
          anyOf:
            - items:
                $ref: '#/components/schemas/EntityIdentityDocument'
              type: array
            - type: 'null'
          title: Identitydocuments
        companyDdData:
          anyOf:
            - $ref: '#/components/schemas/CompanyDueDiligenceData-Input'
            - type: 'null'
        usageData:
          anyOf:
            - $ref: '#/components/schemas/EntityUsageData'
            - type: 'null'
        acceptedTermsAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Acceptedtermsat
      type: object
      title: EntityDraftWrite
      description: Create or partially update an entity from the KYB draft editor.
    EntityData:
      properties:
        id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Id
        referenceId:
          anyOf:
            - type: string
            - type: 'null'
          title: Referenceid
        creatorUserId:
          type: string
          format: uuid
          title: Creatoruserid
        firstName:
          anyOf:
            - type: string
            - type: 'null'
          title: Firstname
        middleName:
          anyOf:
            - type: string
            - type: 'null'
          title: Middlename
        lastName:
          anyOf:
            - type: string
            - type: 'null'
          title: Lastname
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
        phone:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone
        country:
          anyOf:
            - $ref: '#/components/schemas/CountryCode'
            - type: 'null'
        dateOfBirth:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Dateofbirth
        birthCountry:
          anyOf:
            - $ref: '#/components/schemas/CountryCode'
            - type: 'null'
        nationalities:
          items:
            $ref: '#/components/schemas/CountryCode'
          type: array
          title: Nationalities
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
          deprecated: true
        legalName:
          anyOf:
            - type: string
            - type: 'null'
          title: Legalname
        tradeName:
          anyOf:
            - type: string
            - type: 'null'
          title: Tradename
        registrationNumber:
          anyOf:
            - type: string
            - type: 'null'
          title: Registrationnumber
        taxId:
          anyOf:
            - type: string
            - type: 'null'
          title: Taxid
        address:
          anyOf:
            - $ref: '#/components/schemas/EntityAddress'
            - type: 'null'
        documents:
          additionalProperties:
            items:
              type: string
              format: uuid
            type: array
          type: object
          title: Documents
        identityDocuments:
          items:
            $ref: '#/components/schemas/EntityIdentityDocument'
          type: array
          title: Identitydocuments
        companyDdData:
          $ref: '#/components/schemas/CompanyDueDiligenceData-Output'
        usageData:
          $ref: '#/components/schemas/EntityUsageData'
        acceptedTermsAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Acceptedtermsat
        corporateAuthorityDocumentIds:
          $ref: '#/components/schemas/CorporateAuthorityDocumentIds'
          description: >-
            Expose typed authority IDs without creating a second source of
            truth.
          readOnly: true
      type: object
      required:
        - creatorUserId
        - corporateAuthorityDocumentIds
      title: EntityData
    EntityRelationshipDraftData:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        sourceEntityId:
          type: string
          format: uuid
          title: Sourceentityid
        targetEntityId:
          type: string
          format: uuid
          title: Targetentityid
        ownershipPercentage:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Ownershippercentage
        hasControl:
          type: boolean
          title: Hascontrol
        isDirector:
          type: boolean
          title: Isdirector
        isSigner:
          type: boolean
          title: Issigner
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        status:
          $ref: '#/components/schemas/EntityRelationshipStatus'
          default: active
        verifications:
          items:
            $ref: '#/components/schemas/EntityProviderVerificationData'
          type: array
          title: Verifications
      type: object
      required:
        - id
        - sourceEntityId
        - targetEntityId
        - hasControl
        - isDirector
        - isSigner
      title: EntityRelationshipDraftData
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    CountryCode:
      type: string
      enum:
        - AF
        - AX
        - AL
        - DZ
        - AS
        - AD
        - AO
        - AI
        - AQ
        - AG
        - AR
        - AM
        - AW
        - AU
        - AT
        - AZ
        - BS
        - BH
        - BD
        - BB
        - BY
        - BE
        - BZ
        - BJ
        - BM
        - BT
        - BO
        - BQ
        - BA
        - BW
        - BV
        - BR
        - IO
        - BN
        - BG
        - BF
        - BI
        - CV
        - KH
        - CM
        - CA
        - KY
        - CF
        - TD
        - CL
        - CN
        - CX
        - CC
        - CO
        - KM
        - CG
        - CD
        - CK
        - CR
        - CI
        - HR
        - CU
        - CW
        - CY
        - CZ
        - DK
        - DJ
        - DM
        - DO
        - EC
        - EG
        - SV
        - GQ
        - ER
        - EE
        - SZ
        - ET
        - FK
        - FO
        - FJ
        - FI
        - FR
        - GF
        - PF
        - TF
        - GA
        - GM
        - GE
        - DE
        - GH
        - GI
        - GR
        - GL
        - GD
        - GP
        - GU
        - GT
        - GG
        - GN
        - GW
        - GY
        - HT
        - HM
        - VA
        - HN
        - HK
        - HU
        - IS
        - IN
        - ID
        - IR
        - IQ
        - IE
        - IM
        - IL
        - IT
        - JM
        - JP
        - JE
        - JO
        - KZ
        - KE
        - KI
        - KP
        - KR
        - KW
        - KG
        - LA
        - LV
        - LB
        - LS
        - LR
        - LY
        - LI
        - LT
        - LU
        - MO
        - MG
        - MW
        - MY
        - MV
        - ML
        - MT
        - MH
        - MQ
        - MR
        - MU
        - YT
        - MX
        - FM
        - MD
        - MC
        - MN
        - ME
        - MS
        - MA
        - MZ
        - MM
        - NA
        - NR
        - NP
        - NL
        - NC
        - NZ
        - NI
        - NE
        - NG
        - NU
        - NF
        - MK
        - MP
        - 'NO'
        - OM
        - PK
        - PW
        - PS
        - PA
        - PG
        - PY
        - PE
        - PH
        - PN
        - PL
        - PT
        - PR
        - QA
        - RE
        - RO
        - RU
        - RW
        - BL
        - SH
        - KN
        - LC
        - MF
        - PM
        - VC
        - WS
        - SM
        - ST
        - SA
        - SN
        - RS
        - SC
        - SL
        - SG
        - SX
        - SK
        - SI
        - SB
        - SO
        - ZA
        - GS
        - SS
        - ES
        - LK
        - SD
        - SR
        - SJ
        - SE
        - CH
        - SY
        - TW
        - TJ
        - TZ
        - TH
        - TL
        - TG
        - TK
        - TO
        - TT
        - TN
        - TR
        - TM
        - TC
        - TV
        - UG
        - UA
        - AE
        - GB
        - US
        - UM
        - UY
        - UZ
        - VU
        - VE
        - VN
        - VG
        - VI
        - WF
        - EH
        - YE
        - ZM
        - ZW
      title: CountryCode
      description: ISO 3166-1 alpha-2 country codes.
    EntityAddress:
      properties:
        streetAddress:
          anyOf:
            - type: string
            - type: 'null'
          title: Streetaddress
        city:
          anyOf:
            - type: string
            - type: 'null'
          title: City
        country:
          anyOf:
            - $ref: '#/components/schemas/CountryCode'
            - type: 'null'
        addressLine2:
          anyOf:
            - type: string
            - type: 'null'
          title: Addressline2
        state:
          anyOf:
            - type: string
            - type: 'null'
          title: State
        zip:
          anyOf:
            - type: string
            - type: 'null'
          title: Zip
      type: object
      title: EntityAddress
    EntityIdentityDocument:
      properties:
        type:
          anyOf:
            - $ref: '#/components/schemas/FiatIdentityDocumentType'
            - type: 'null'
        issuingCountry:
          anyOf:
            - $ref: '#/components/schemas/CountryCode'
            - type: 'null'
        number:
          anyOf:
            - type: string
            - type: 'null'
          title: Number
      type: object
      title: EntityIdentityDocument
      description: |-
        Issuing metadata for one identity document held by a person entity.

        The scanned pages live in ``Entity.documents`` keyed by upload slot
        (``passport_front``, ``id_card_back``, …); this carries what the slot
        cannot express and what providers ask for: the document's own type, the
        country that issued it and its number.
    CompanyDueDiligenceData-Input:
      properties:
        entityType:
          anyOf:
            - type: string
            - type: 'null'
          title: Entitytype
        entityTypeDescription:
          anyOf:
            - type: string
            - type: 'null'
          title: Entitytypedescription
        incorporationDate:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Incorporationdate
        industry:
          anyOf:
            - type: string
            - type: 'null'
          title: Industry
        websites:
          items:
            type: string
          type: array
          title: Websites
        operatingCountries:
          anyOf:
            - items:
                $ref: '#/components/schemas/CountryCode'
              type: array
            - type: 'null'
          title: Operatingcountries
        expectedMonthlyVolumeUsd:
          anyOf:
            - type: number
              minimum: 0
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Expectedmonthlyvolumeusd
        estimatedAnnualRevenue:
          anyOf:
            - type: number
              minimum: 0
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Estimatedannualrevenue
        hasUsBank:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Hasusbank
        deniedUsBank:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Deniedusbank
        hasPep:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Haspep
        bizAdverse:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Bizadverse
        ownersAdverse:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Ownersadverse
        publicListed:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Publiclisted
        txPerMonth:
          anyOf:
            - $ref: '#/components/schemas/FiatTransactionCount'
            - type: 'null'
        usesBlockchain:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Usesblockchain
        revenueCovers:
          anyOf:
            - $ref: '#/components/schemas/RevenueCoverage'
            - type: 'null'
        institutionalInvestors:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Institutionalinvestors
        isRegulated:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Isregulated
      type: object
      title: CompanyDueDiligenceData
    EntityUsageData:
      properties:
        business:
          anyOf:
            - type: string
            - type: 'null'
          title: Business
        businessIndustry:
          anyOf:
            - type: string
              pattern: ^\d{6}$
            - type: 'null'
          title: Businessindustry
        businessType:
          anyOf:
            - type: string
            - type: 'null'
          title: Businesstype
        businessTypeDetails:
          anyOf:
            - type: string
            - type: 'null'
          title: Businesstypedetails
        verifierRole:
          anyOf:
            - type: string
            - type: 'null'
          title: Verifierrole
        sourceOfFunds:
          anyOf:
            - type: string
            - type: 'null'
          title: Sourceoffunds
        sourceOfFundsDetails:
          anyOf:
            - type: string
            - type: 'null'
          title: Sourceoffundsdetails
        purposeOfFunds:
          anyOf:
            - type: string
            - type: 'null'
          title: Purposeoffunds
        purposeOfFundsDetails:
          anyOf:
            - type: string
            - type: 'null'
          title: Purposeoffundsdetails
        flowOfFunds:
          anyOf:
            - type: string
            - type: 'null'
          title: Flowoffunds
        complianceScreening:
          anyOf:
            - type: string
            - type: 'null'
          title: Compliancescreening
        handlesCustomerFunds:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Handlescustomerfunds
        actingAsIntermediary:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Actingasintermediary
        sanctionedCountryOperations:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Sanctionedcountryoperations
        highRiskActivities:
          items:
            type: string
          type: array
          title: Highriskactivities
        depositMethods:
          items:
            type: string
          type: array
          title: Depositmethods
        contactInfo:
          anyOf:
            - type: string
            - type: 'null'
          title: Contactinfo
      type: object
      title: EntityUsageData
    CompanyDueDiligenceData-Output:
      properties:
        entityType:
          anyOf:
            - type: string
            - type: 'null'
          title: Entitytype
        entityTypeDescription:
          anyOf:
            - type: string
            - type: 'null'
          title: Entitytypedescription
        incorporationDate:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Incorporationdate
        industry:
          anyOf:
            - type: string
            - type: 'null'
          title: Industry
        websites:
          items:
            type: string
          type: array
          title: Websites
        operatingCountries:
          anyOf:
            - items:
                $ref: '#/components/schemas/CountryCode'
              type: array
            - type: 'null'
          title: Operatingcountries
        expectedMonthlyVolumeUsd:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Expectedmonthlyvolumeusd
        estimatedAnnualRevenue:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Estimatedannualrevenue
        hasUsBank:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Hasusbank
        deniedUsBank:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Deniedusbank
        hasPep:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Haspep
        bizAdverse:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Bizadverse
        ownersAdverse:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Ownersadverse
        publicListed:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Publiclisted
        txPerMonth:
          anyOf:
            - $ref: '#/components/schemas/FiatTransactionCount'
            - type: 'null'
        usesBlockchain:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Usesblockchain
        revenueCovers:
          anyOf:
            - $ref: '#/components/schemas/RevenueCoverage'
            - type: 'null'
        institutionalInvestors:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Institutionalinvestors
        isRegulated:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Isregulated
      type: object
      title: CompanyDueDiligenceData
    CorporateAuthorityDocumentIds:
      properties:
        authorizationToActDocumentId:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Authorizationtoactdocumentid
        authorityToBindDocumentId:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Authoritytobinddocumentid
      type: object
      title: CorporateAuthorityDocumentIds
      description: Canonical authority-document references exposed by the KYB structure.
    EntityRelationshipStatus:
      type: string
      enum:
        - pending
        - active
        - revoked
      title: EntityRelationshipStatus
      description: Consent state for a KYB ownership or authority relationship.
    EntityProviderVerificationData:
      properties:
        id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Id
        provider:
          $ref: '#/components/schemas/FiatProvider'
        externalId:
          anyOf:
            - type: string
            - type: 'null'
          title: Externalid
        status:
          type: string
          title: Status
        kycLink:
          anyOf:
            - type: string
            - type: 'null'
          title: Kyclink
        kycLinkState:
          anyOf:
            - type: string
            - type: 'null'
          title: Kyclinkstate
        kycLinkExpiresAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Kyclinkexpiresat
      type: object
      required:
        - provider
        - status
      title: EntityProviderVerificationData
    FiatIdentityDocumentType:
      type: string
      enum:
        - passport
        - id_card
        - drivers_license
        - driver_license
        - residence_permit
        - government_id
        - state_or_provincial_id
        - visa
      title: FiatIdentityDocumentType
      description: Identity document type.
    FiatTransactionCount:
      type: string
      enum:
        - <10
        - 10-50
        - 50-200
        - 200-1,000
        - 1,000+
      title: FiatTransactionCount
      description: Expected monthly transaction-count range declared during KYB.
    RevenueCoverage:
      type: string
      enum:
        - all_operating_expenses
        - most
        - some
        - minimal
      title: RevenueCoverage
      description: Share of operating expenses covered by current business revenue.
    FiatProvider:
      type: string
      enum:
        - swipelux
        - align
        - dakota
        - mcp
        - wirex
        - conduit_fiat
        - conduit_crypto
        - due
      title: FiatProvider
      description: Supported fiat payment providers.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````