openapi: 3.2.0
info:
  title: Business Beneficial owners API
  description: Businesses
  version: '0'
servers:
- url: https://sandbox.bond.tech/api/v0
security:
- identity: []
  authorization: []
tags:
- name: Beneficial owners
paths:
  /businesses/{business_id}/beneficial_owners:
    get:
      tags:
      - Beneficial owners
      summary: Retrieve all beneficial owners
      description: Retrieves all beneficial owners associated with a business
      operationId: get_beneficial_owners
      parameters:
      - name: business_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              examples:
                example:
                  value:
                    page_info:
                      page_size: 2
                      page: 1
                      pages: 1
                    data:
                    - beneficial_owner_id: 4943fc81-e7e8-43b5-8be6-9c43fcec505a
                      first_name: David
                      last_name: Letterman
                      date_created: '2019-08-24T14:15:22.000Z'
                      date_updated: '2019-08-24T14:15:22.000Z'
                      dob: '1980-04-04'
                      address:
                      - address_id: 12348579-5d05-4e3e-a5e3-e61e3a5b1234
                        address_type: MAILING
                        street: 345 California Ave.
                        street2: Suit 600
                        city: San Francisco
                        state: CA
                        zip_code: 12345-1234
                        country: US
                        is_primary: true
                    - beneficial_owner_id: 29ec6db6-4e12-4521-8ba7-7afc5c4730dd
                      first_name: Conan
                      last_name: O'Brian
                      date_created: '2019-08-24T14:15:22.000Z'
                      date_updated: '2019-08-24T14:15:22.000Z'
                      dob: '1980-04-04'
                      address:
                      - address_id: 12348579-5d05-4e3e-a5e3-e61e3a5b1234
                        address_type: MAILING
                        street: 345 California Ave.
                        street2: Suit 600
                        city: San Francisco
                        state: CA
                        zip_code: 12345-1234
                        country: US
                        is_primary: true
    post:
      tags:
      - Beneficial owners
      summary: Create a beneficial owner
      description: Creates a beneficial owner associated with a business
      operationId: post_beneficial_owners
      parameters:
      - name: business_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BeneficialOwnerPostSerializer'
        required: true
      responses:
        '201':
          $ref: '#/components/responses/beneficial-owner-write'
  /businesses/{business_id}/beneficial_owners/{beneficial_owner_id}:
    get:
      tags:
      - Beneficial owners
      summary: Retrieve a beneficial owner
      description: Retrieves a beneficial owner associated with a business
      operationId: get_beneficial_owner
      parameters:
      - name: business_id
        in: path
        required: true
        schema:
          type: string
      - name: beneficial_owner_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/beneficial-owner'
    delete:
      tags:
      - Beneficial owners
      summary: Delete a beneficial owner
      description: Deletes a beneficial owner associated with a business
      operationId: delete_beneficial_owner
      parameters:
      - name: business_id
        in: path
        required: true
        schema:
          type: string
      - name: beneficial_owner_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: ''
          content: {}
    patch:
      tags:
      - Beneficial owners
      summary: Update a beneficial owner
      description: Updates a beneficial owner associated with a business
      operationId: patch_beneficial_owner
      parameters:
      - name: business_id
        in: path
        required: true
        schema:
          type: string
      - name: beneficial_owner_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BeneficialOwnerPatchSerializer'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/beneficial-owner-write'
  /businesses/{business_id}/beneficial_owners/{beneficial_owner_id}/verification-kyc:
    get:
      tags:
      - Beneficial owners
      summary: Retrieve KYC Status
      description: Retrieve the KYC status of a `Beneficial Owner`
      operationId: get_beneficial_owner_kyc
      parameters:
      - name: business_id
        in: path
        required: true
        schema:
          type: string
      - name: beneficial_owner_id
        in: path
        required: true
        schema:
          type: string
      - name: program_id
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              examples:
                example:
                  value:
                    customer_id: d856bf10-d4a6-4153-b8f8-2b93072dd8da
                    brand_id: ce027c9c-39c6-47f4-a12d-abb543f7cf63
                    kyc_status: passed
                    results:
                      ofac: passed
                      bureau: passed
                      email: passed
                      ip: passed
                      mobile: passed
                    health:
                      overall: SERVICE_GOOD
                      ofac: SERVICE_GOOD
                      bureau: SERVICE_GOOD
                      email: SERVICE_GOOD
                      ip: SERVICE_GOOD
                      mobile: SERVICE_GOOD
                    info:
                      ofac:
                        name_matched: false
                        dob_matched: false
                      bureau:
                        application_status: Pass
                      phone:
                        first_name_match: 100
                        last_name_match: 100
                        service_status: ACTIVE
                        service_type: CONTRACT
                        service_duration: UNKNOWN
                        service_ported_duration: NONE
    post:
      tags:
      - Beneficial owners
      summary: Start KYC (Know-Your-Customer)
      description: Start a KYC verification for a `Beneficial Owner`
      operationId: post_beneficial_owner_kyc
      parameters:
      - name: business_id
        in: path
        required: true
        schema:
          type: string
      - name: beneficial_owner_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KYCPostPayload'
        required: true
      responses:
        '201':
          description: ''
          content:
            application/json:
              examples:
                example:
                  value:
                    customer_id: 2df10ec1-130f-41bb-b0cf-f3af48350eb7
                    kyc_status: initialized
components:
  responses:
    beneficial-owner-write:
      description: Example response
      content:
        application/json:
          schema:
            description: ''
            type: object
            properties:
              first_name:
                type: string
                minLength: 1
              last_name:
                type: string
                minLength: 1
              dob:
                type: string
                minLength: 1
              address:
                type: array
                uniqueItems: true
                minItems: 1
                items:
                  required:
                  - address_type
                  - street
                  - street2
                  - city
                  - state
                  - zip_code
                  - country
                  - is_primary
                  properties:
                    address_type:
                      type: string
                      minLength: 1
                    street:
                      type: string
                      minLength: 1
                      maxLength: 40
                    street2:
                      type: string
                      maxLength: 40
                    city:
                      type: string
                      minLength: 2
                      maxLength: 40
                    state:
                      type: string
                      minLength: 1
                    zip_code:
                      type: string
                      minLength: 1
                    country:
                      type: string
                      minLength: 1
                    is_primary:
                      type: boolean
            required:
            - first_name
            - last_name
            - dob
            - address
          examples:
            example:
              value:
                first_name: New
                last_name: Owner
                dob: '1999-10-10'
                address:
                - address_type: PHYSICAL
                  street: 345 California St.
                  street2: Suit 600
                  city: San Francisco
                  state: CA
                  zip_code: 94104-2657
                  country: US
                  is_primary: true
    beneficial-owner:
      description: Example response
      content:
        application/json:
          schema:
            properties:
              id:
                type: string
          examples:
            example:
              value:
                beneficial_owner_id: 12345678-5d05-4562-a5e3-e61e12345678
                first_name: New
                last_name: Owner
                date_created: '2019-08-24T14:15:22Z'
                dob: '1999-10-10'
                address:
                - date_created: '2019-08-24T14:15:22Z'
                  address_id: 12374791-5d05-4e3e-a5e3-e61e3817622134
                  address_type: PHYSICAL
                  street: 345 California St.
                  street2: Suit 600
                  city: San Francisco
                  state: CA
                  zip_code: 94104-2657
                  country: US
                  is_primary: true
  schemas:
    BeneficialOwnerPostSerializer:
      type: object
      properties:
        dob:
          type: string
          description: Date of birth in YYYY-MM-DD format.
          format: string
          example: '1980-04-04'
        first_name:
          type: string
          description: First name.<br />Has a 1 to 20-character limit. Must start with an alphabet and may only contain alphabets, spaces, and apostrophes.
          example: John
        middle_name:
          type: string
          description: Middle name.<br />Has a 20-character limit. Must start with an alphabet and may only contain alphabets, spaces, and apostrophes.
          example: O'Shea
        last_name:
          type: string
          description: Last name.<br />Has a 2 to 20-character limit. Must start with an alphabet and may only contain alphabets, spaces, and apostrophes.
          example: Doe
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
      required:
      - first_name
      - last_name
      - addresses
      x-examples:
        example-1:
          dob: '1980-04-04'
          first_name: John
          middle_name: O'Shea
          last_name: Doe
          addresses:
          - address_type: MAILING
            street: 345 California Ave.
            street2: Suit 600
            city: San Francisco
            state: CA
            zip_code: 12345-1234
            country: US
            is_primary: true
    Address:
      title: ''
      type: object
      properties:
        address_type:
          type: string
          description: 'Address type is one of the following : MAILING, PHYSICAL, REGISTERED'
          enum:
          - MAILING
          - PHYSICAL
          - REGISTERED
        street:
          type: string
          description: 'Has a 1 to 40-character limit. May only contain alphanumerics and the special characters `. , _ - #`'
          example: 345 California Ave.
        street2:
          type: string
          description: 'Has a 40-character limit. May only contain alphanumerics and the special characters `. , _ - #`'
          example: Suit 600
        city:
          type: string
          description: Has a 2 to 40-character limit. May contain only alphanumerics, `-`, `_`,`.`, and spaces
          example: San Francisco
          minLength: 2
          maxLength: 40
        state:
          type: string
          description: Has a 2-character limit for US address.<br />Has a 20-character limit for non US address.
          example: CA
        zip_code:
          type: string
          description: zip code in 5-digit (12345) or 9-digit (12345-1234) format for US address.<br />Has a 2 to 20-character limit for non US address.
          example: 12345-1234
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code.<br />Has a 2-character limit.
          example: US
        is_primary:
          type: boolean
          description: Is Primary Address?
          example: true
      required:
      - address_type
      - street
      - city
      - state
      - zip_code
      - country
      - is_primary
    KYCPostPayload:
      required:
      - email
      - ip
      - phone
      - phone_country_code
      - program_id
      - ssn
      type: object
      properties:
        dob:
          type: string
          description: Date of birth in YYYY-MM-DD format.
          format: string
          example: '1980-04-04'
        program_id:
          type: string
          description: String in acceptable UUID format that corresponds to a valid `Program` program_id.
          example: 72585109-8222-4221-b15b-48e87ffed790
        ssn:
          type: string
          description: 'Must be in ######### or ###-##-#### format'
          example: 123-45-6789
        phone:
          type: string
          description: Numbers only or dash-separated are acceptable
          example: 555-111-2222
        phone_country_code:
          type: string
          description: Must be a string of 1-3 digits
          example: '1'
        email:
          type: string
          description: Must be a valid email address
          example: customer@bond.tech
        ip:
          type: string
          description: Must be dot separated
          example: 257.134.1.57
        kyc_retry_request:
          type: boolean
          description: If failure threshold has been reached, set this to `true` to request further attempts
    BeneficialOwnerPatchSerializer:
      type: object
      properties:
        dob:
          type: string
          description: Date of birth in YYYY-MM-DD format.
          format: string
          example: '1980-04-04'
        first_name:
          type: string
          description: First name.<br />Has a 1 to 20-character limit. Must start with an alphabet and may only contain alphabets, spaces, and apostrophes.
          example: John
        middle_name:
          type: string
          description: Middle name.<br />Has a 20-character limit. Must start with an alphabet and may only contain alphabets, spaces, and apostrophes.
          example: Johnson
        last_name:
          type: string
          description: Last name.<br />Has a 2 to 20-character limit. Must start with an alphabet and may only contain alphabets, spaces, and apostrophes.
          example: Doe
  securitySchemes:
    identity:
      type: apiKey
      name: Identity
      in: header
    authorization:
      type: apiKey
      name: Authorization
      in: header
x-samples-languages:
- curl
- node
- ruby
- javascript
- python
- csharp
- java
x-provenance:
  method: searched
  source: https://docs.bond.tech/reference
  harvested: '2026-10-14'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.bond.tech/reference/delete_beneficial_owner.md
  - https://docs.bond.tech/reference/delete_beneficial_owner_address.md
  - https://docs.bond.tech/reference/delete_business.md
  - https://docs.bond.tech/reference/delete_business_address.md
  - https://docs.bond.tech/reference/get_beneficial_owner.md
  - https://docs.bond.tech/reference/get_beneficial_owner_address.md
  - https://docs.bond.tech/reference/get_beneficial_owner_addresses.md
  - https://docs.bond.tech/reference/get_beneficial_owner_kyc.md
  - https://docs.bond.tech/reference/get_beneficial_owners.md
  - https://docs.bond.tech/reference/get_business.md
  - https://docs.bond.tech/reference/get_business_address.md
  - https://docs.bond.tech/reference/get_business_addresses.md
  - https://docs.bond.tech/reference/get_businesses.md
  - https://docs.bond.tech/reference/get_kyb.md
  - https://docs.bond.tech/reference/patch_beneficial_owner.md
  - https://docs.bond.tech/reference/patch_beneficial_owner_address.md
  - https://docs.bond.tech/reference/patch_business.md
  - https://docs.bond.tech/reference/patch_business_address.md
  - https://docs.bond.tech/reference/post_beneficial_owner_addresses.md
  - https://docs.bond.tech/reference/post_beneficial_owner_kyc.md
  - https://docs.bond.tech/reference/post_beneficial_owners.md
  - https://docs.bond.tech/reference/post_business_addresses.md
  - https://docs.bond.tech/reference/post_businesses.md
  - https://docs.bond.tech/reference/post_kyb.md
  - https://docs.bond.tech/reference/post_kyb_2.md
  - https://docs.bond.tech/reference/post_kyb_resume.md
  merge:
    pages: 26
    deduped: 64
    conflicts_kept_first: 0