openapi: 3.2.0
info:
  title: Caliza API documentation reference Related Person API
  description: The Caliza API enables seamless integration of financial services including payments, payouts, currency conversions, and compliance workflows.
  version: v1
  contact:
    name: Caliza API Support
    email: api-support@caliza.com
    url: https://docs.caliza.com
  termsOfService: https://caliza.com/terms
servers:
- url: https://api.sandbox.com
  description: Sandbox Environment
- url: https://api.caliza.com
  description: Production Environment
- url: https://api.sandbox.caliza.com
  description: Sandbox Environment (backoffice)
security:
- bearerAuth: []
tags:
- name: Related Person
  description: Manage related persons (e.g. beneficial owners, directors, representatives) linked to a beneficiary. Create, retrieve, update, list and delete related persons and upload supporting identity documents for compliance verification.
paths:
  /v1/beneficiaries/{beneficiaryId}/related-persons:
    post:
      tags:
      - Related Person
      summary: Create related person
      description: Creates a new related person for a beneficiary such as a beneficial owner, director, legal representative, or authorized signatory. Provide personal details including name, date of birth, citizenship, government ID, contact information, and residential address. Related persons are required for KYB compliance to identify individuals who own or control the beneficiary entity.
      operationId: createRelatedPerson
      parameters:
      - name: beneficiaryId
        in: path
        description: Unique identifier of the beneficiary to add the related person to.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelatedPersonResponse'
    get:
      tags:
      - Related Person
      summary: List related persons
      description: Retrieves all related persons associated with a beneficiary including beneficial owners, directors, legal representatives, and authorized signatories. Each entry includes full personal details, contact information, and address. Use this to review compliance information or display all individuals linked to a business beneficiary.
      operationId: listRelatedPersons
      parameters:
      - name: beneficiaryId
        in: path
        description: Unique identifier of the beneficiary to list related persons for.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RelatedPersonResponse'
  /v1/beneficiaries/{beneficiaryId}/related-persons/{id}:
    get:
      tags:
      - Related Person
      summary: Get related person
      description: Retrieves detailed information about a specific related person including personal details, contact information, residential address, and any uploaded compliance documents. Use this to inspect individual related person records for verification or compliance review.
      operationId: getRelatedPerson
      parameters:
      - name: beneficiaryId
        in: path
        description: Unique identifier of the beneficiary.
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Unique identifier of the related person.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelatedPersonResponse'
    put:
      tags:
      - Related Person
      summary: Update related person
      description: Updates the information of an existing related person including personal details, contact information, and residential address. Use this when a related person's information changes or when correcting previously submitted data during the compliance review process.
      operationId: updateRelatedPerson
      parameters:
      - name: beneficiaryId
        in: path
        description: Unique identifier of the beneficiary.
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Unique identifier of the related person to update.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelatedPersonResponse'
    delete:
      tags:
      - Related Person
      summary: Delete related person
      description: Removes a related person from a beneficiary's record. Use this when a related person is no longer associated with the beneficiary entity, for example when an owner sells their stake or a director resigns.
      operationId: deleteRelatedPerson
      parameters:
      - name: beneficiaryId
        in: path
        description: Unique identifier of the beneficiary.
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Unique identifier of the related person to delete.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
  /v1/beneficiaries/{beneficiaryId}/related-persons/{id}/documents:
    post:
      tags:
      - Related Person
      summary: Upload document for related person
      description: Uploads an identity or compliance document for a specific related person of a beneficiary. Documents can include government-issued IDs (passport, driver's license, national ID), proof of address, or other verification documents. Provide the front of the document as required, and optionally the back. Supported formats include JPG, PNG, and PDF.
      operationId: addRelatedPersonDocument
      parameters:
      - name: beneficiaryId
        in: path
        description: Unique identifier of the beneficiary.
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Unique identifier of the related person.
        required: true
        schema:
          type: string
      - name: name
        in: query
        description: Display name or filename for the document being uploaded.
        required: true
        schema:
          type: string
      - name: type
        in: query
        description: Type of identity or compliance document.
        required: true
        schema:
          type: string
          enum:
          - PASSPORT
          - DRIVER_LICENSE
          - NATIONAL_ID
          - PAN_CARD
          - ID_CARD
          - VOTER_ID_CARD
          - RESIDENT_CARD
          - ID_FRONT
          - ID_BACK
          - INCORPORATION_CERTIFICATE
          - TAX_REGISTRATION
          - BUSINESS_BANK_ACCOUNT
          - PROOF_OF_ADDRESS
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
              - documentFront
              type: object
              properties:
                documentFront:
                  type: string
                  format: binary
                  description: Front side of the document.
                documentBack:
                  type: string
                  format: binary
                  description: Back side of the document (optional).
      responses:
        '201':
          description: Created
components:
  schemas:
    AddressRequest:
      required:
      - city
      - country
      - state
      - streetOne
      - zipcode
      type: object
      description: Physical address request format for beneficiary or integrator registration.
      properties:
        streetOne:
          maxLength: 100
          minLength: 0
          type: string
        streetTwo:
          maxLength: 100
          minLength: 0
          type: string
        geolocation:
          type: string
        city:
          maxLength: 100
          minLength: 0
          type: string
        zipcode:
          type: string
        state:
          maxLength: 3
          minLength: 0
          type: string
        country:
          maxLength: 2
          minLength: 0
          type: string
    AddressEntity:
      type: object
      description: Physical address information with geolocation support.
      properties:
        streetOne:
          type: string
          description: Primary street address line.
          example: 123 Main Street
        streetTwo:
          type: string
          description: Secondary address line (apartment, suite, etc.).
          example: Apt 4B
        geolocation:
          type: string
          description: Geographic coordinates or location identifier.
          example: 40.7128,-74.0060
        city:
          type: string
          description: City name.
          example: New York
        zipcode:
          type: string
          description: Postal or ZIP code.
          example: '10001'
        state:
          type: string
          description: State or province.
          example: NY
        country:
          type: string
          description: Country name or ISO code.
          example: United States
    PersonRequest:
      required:
      - address
      - citizenship
      - dateOfBirth
      - email
      - firstName
      - idNumber
      - lastName
      - phoneNumber
      type: object
      description: Individual person information for beneficiary registration including identity documents, contact details, and compliance information.
      properties:
        firstName:
          maxLength: 100
          minLength: 0
          type: string
        lastName:
          maxLength: 100
          minLength: 0
          type: string
        dateOfBirth:
          type: string
          format: date
        placeOfBirth:
          type: string
        citizenship:
          type: string
        idNumber:
          type: string
        email:
          type: string
        phoneNumber:
          maxLength: 21
          minLength: 0
          pattern: ^(\+)[0-9\s.]{6,20}$
          type: string
        profession:
          type: string
        gender:
          type: string
          enum:
          - MALE
          - FEMALE
          - OTHER
        address:
          $ref: '#/components/schemas/AddressRequest'
        maritalStatus:
          type: string
        mothersName:
          type: string
        industry:
          type: string
          enum:
          - agriculture
          - mining
          - utilities
          - construction
          - manufacturing
          - chemicalManufacturing
          - merchantWholesale
          - automotive
          - retailFurnishing
          - retailElectronics
          - retailHome
          - retailFood
          - healthStores
          - gasoline
          - retailClothing
          - retailSporting
          - retailNonStore
          - transportation
          - publishing
          - finance
          - realEstate
          - rentalServices
          - professionalNonLegal
          - accounting
          - travel
          - educationalMedical
          - performingArts
          - recreationGambling
          - foodService
          - maintenance
          - laundry
          - religiousCharity
          - publicAdministration
        incomeSource:
          type: string
          enum:
          - salary
          - selfEmployed
          - inheritance
          - investments
          - retirement
          - rentalIncome
          - governmentBenefits
          - familySupport
        annualIncome:
          type: number
        occupation:
          type: string
          enum:
          - executive
          - sales
          - consulting
          - government
          - healthcare
          - financeAccounting
          - technology
          - scienceEngineering
          - foodServices
          - legalServices
          - manufacturing
          - other
        wealthSource:
          type: string
          enum:
          - salary
          - selfEmployed
          - inheritance
          - familySupport
          - investments
          - retirement
          - rentalIncome
          - governmentBenefits
          - businessSale
          - other
    PersonResponse:
      type: object
      description: Individual person information response including identity details and verification status.
      properties:
        firstName:
          type: string
        lastName:
          type: string
        dateOfBirth:
          type: string
          format: date
        placeOfBirth:
          type: string
        citizenship:
          type: string
        idNumber:
          type: string
        email:
          type: string
        phoneNumber:
          type: string
        profession:
          type: string
        gender:
          type: string
          enum:
          - MALE
          - FEMALE
          - OTHER
        maritalStatus:
          type: string
        mothersName:
          type: string
        address:
          $ref: '#/components/schemas/AddressEntity'
        industry:
          type: string
          enum:
          - agriculture
          - mining
          - utilities
          - construction
          - manufacturing
          - chemicalManufacturing
          - merchantWholesale
          - automotive
          - retailFurnishing
          - retailElectronics
          - retailHome
          - retailFood
          - healthStores
          - gasoline
          - retailClothing
          - retailSporting
          - retailNonStore
          - transportation
          - publishing
          - finance
          - realEstate
          - rentalServices
          - professionalNonLegal
          - accounting
          - travel
          - educationalMedical
          - performingArts
          - recreationGambling
          - foodService
          - maintenance
          - laundry
          - religiousCharity
          - publicAdministration
        incomeSource:
          type: string
          enum:
          - salary
          - selfEmployed
          - inheritance
          - investments
          - retirement
          - rentalIncome
          - governmentBenefits
          - familySupport
        annualIncome:
          type: number
        occupation:
          type: string
          enum:
          - executive
          - sales
          - consulting
          - government
          - healthcare
          - financeAccounting
          - technology
          - scienceEngineering
          - foodServices
          - legalServices
          - manufacturing
          - other
        wealthSource:
          type: string
          enum:
          - salary
          - selfEmployed
          - inheritance
          - familySupport
          - investments
          - retirement
          - rentalIncome
          - governmentBenefits
          - businessSale
          - other
    RelatedPersonResponse:
      type: object
      description: Related person record associated with a beneficiary including a unique identifier and full personal details.
      properties:
        id:
          type: string
          description: Unique identifier of the related person.
        person:
          $ref: '#/components/schemas/PersonResponse'
  securitySchemes:
    bearerAuth:
      type: http
      description: 'JWT Bearer token authentication. Include your access token in the Authorization header:


        `Authorization: Bearer YOUR_ACCESS_TOKEN`


        Tokens are obtained through the Caliza authentication flow and typically expire after 24 hours.

        Refresh your token before expiration to maintain uninterrupted access.

        '
      scheme: bearer
      bearerFormat: JWT
x-provenance:
  method: searched
  source: https://docs.caliza.com/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.caliza.com/reference/accepttermsandconditions.md
  - https://docs.caliza.com/reference/addrelatedpersondocument.md
  - https://docs.caliza.com/reference/approveverificationsandbox.md
  - https://docs.caliza.com/reference/createfakecryptodeposit.md
  - https://docs.caliza.com/reference/createfakepixindeposit.md
  - https://docs.caliza.com/reference/createfakepixindeposit_1.md
  - https://docs.caliza.com/reference/createfakespeiindeposit.md
  - https://docs.caliza.com/reference/createfakeusddeposit.md
  - https://docs.caliza.com/reference/createpayment.md
  - https://docs.caliza.com/reference/createpaymentwithdocuments.md
  - https://docs.caliza.com/reference/createrecipient.md
  - https://docs.caliza.com/reference/createrelatedperson.md
  - https://docs.caliza.com/reference/createsimulation.md
  - https://docs.caliza.com/reference/createsimulation_1.md
  - https://docs.caliza.com/reference/createtransaction.md
  - https://docs.caliza.com/reference/createtransaction_1.md
  - https://docs.caliza.com/reference/createverification.md
  - https://docs.caliza.com/reference/createvirtualaccount.md
  - https://docs.caliza.com/reference/deletebeneficiary.md
  - https://docs.caliza.com/reference/deleterecipient.md
  - https://docs.caliza.com/reference/deleterelatedperson.md
  - https://docs.caliza.com/reference/disablebeneficiary.md
  - https://docs.caliza.com/reference/enablebeneficiary.md
  - https://docs.caliza.com/reference/findorcreatewallet.md
  - https://docs.caliza.com/reference/getall.md
  - https://docs.caliza.com/reference/getalltransactions.md
  - https://docs.caliza.com/reference/getbeneficiary.md
  - https://docs.caliza.com/reference/getbeneficiarybalance.md
  - https://docs.caliza.com/reference/getbeneficiarydetailedbalance.md
  - https://docs.caliza.com/reference/getbeneficiarydetailedbalancebycurrencies.md
  - https://docs.caliza.com/reference/getcapabilitiesbyintegratorid.md
  - https://docs.caliza.com/reference/getdepositinfo.md
  - https://docs.caliza.com/reference/getdepositinstructions.md
  - https://docs.caliza.com/reference/getintegratorbalances.md
  - https://docs.caliza.com/reference/getintegratorwebhooks.md
  - https://docs.caliza.com/reference/getintegratorwebhooksecret.md
  - https://docs.caliza.com/reference/getme.md
  - https://docs.caliza.com/reference/getpaymentinstructions.md
  - https://docs.caliza.com/reference/getproof.md
  - https://docs.caliza.com/reference/getrecipient.md
  - https://docs.caliza.com/reference/getrecipients.md
  - https://docs.caliza.com/reference/getrelatedperson.md
  - https://docs.caliza.com/reference/getsimulationbyid.md
  - https://docs.caliza.com/reference/getsimulationbyidv2.md
  - https://docs.caliza.com/reference/gettermsandconditions.md
  - https://docs.caliza.com/reference/gettransactionbyid.md
  - https://docs.caliza.com/reference/gettransactionbyid_1.md
  - https://docs.caliza.com/reference/gettransactionbyidwithdocuments.md
  - https://docs.caliza.com/reference/gettransactionproofofpayment.md
  - https://docs.caliza.com/reference/getverificationstatus.md
  - https://docs.caliza.com/reference/issuedelegatetoken.md
  - https://docs.caliza.com/reference/issuemanualattestation.md
  - https://docs.caliza.com/reference/listrelatedpersons.md
  - https://docs.caliza.com/reference/listvirtualaccounts.md
  - https://docs.caliza.com/reference/payouts.md
  - https://docs.caliza.com/reference/savebeneficiary.md
  - https://docs.caliza.com/reference/searchvasps.md
  - https://docs.caliza.com/reference/simulatetravelruleclearance.md
  - https://docs.caliza.com/reference/startmicrotransfertest.md
  - https://docs.caliza.com/reference/submitproof.md
  - https://docs.caliza.com/reference/sweeppayouts.md
  - https://docs.caliza.com/reference/updatebeneficiary.md
  - https://docs.caliza.com/reference/updateintegratorwebhooksecret.md
  - https://docs.caliza.com/reference/updateme.md
  - https://docs.caliza.com/reference/updaterecipient.md
  - https://docs.caliza.com/reference/updaterelatedperson.md
  - https://docs.caliza.com/reference/updatewebhookconfig.md
  - https://docs.caliza.com/reference/uploaddocument.md
  merge:
    pages: 68
    deduped: 414
    conflicts_kept_first: 0