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

# Merge duplicate contacts

> Fuses 2 to 20 contacts into one survivor (one person = one contact with many destinations). Destinations move to the survivor; a missing or foreign id answers 404 and merges nothing (no partial merge). Not idempotent: retrying after success answers 404 (sources already deleted), so the client must not blindly retry.



## OpenAPI

````yaml /openapi.yaml post /v1/contacts/merge
openapi: 3.1.0
info:
  title: CBPay API
  version: '2.308'
  description: >
    CBPay is a multi-currency payment platform: fiat payouts and collections

    across Latin America, internal transfers, on-chain funding and

    withdrawals, and KYC screening. Every account holds independent

    virtual balances — USD (the principal currency), USDT, USDC, USDCE, BTC,
    GOLD, SILVER and PLATINUM (grams of fine metal), plus BOB, MXN, ARS, CLP
    (local fiat; BOB/MXN/ARS use two decimals, CLP uses zero decimals) —
    convertible on demand with swaps.

    Payouts and service fees can be paid from any of the seven platform
    settlement balances

    (`PUT /v1/settlement` or per-payout `settlement_asset`), and payins

    can auto-convert to the asset of your choice (`default_payin_asset`).


    All amounts are decimal strings in each currency's precision (2 decimals

    for USD/BOB/MXN/ARS, 0 for CLP, 6 for USDT/USDC/USDCE/GOLD/SILVER/PLATINUM,
    and 8 for BTC). Errors always return

    `{"error": "<code>", "message": "<detail>"}`.

    Breaking change (2026-11-13): BOB, MXN, ARS and CLP settlement assets and
    BANK_* mirrors are Banking-only. Platform fiat settlement is rejected with
    HTTP 400; existing fiat defaults migrate automatically to USDT (legacy
    accounts keep USDT; new accounts default to USD). Use Banking for fiat
    operations.
servers:
  - url: https://api.qbank.cl/platform
    description: Live (production, real money)
  - url: https://cryptobank.qbank.cl/platform
    description: Test (sandbox, simulated money — pk_test_ keys)
security:
  - bearerAuth: []
tags:
  - name: Support
    description: Support tickets and organization queue
  - name: Receipts
    description: >-
      Branded PDF receipt per operation, with a public signed-QR authenticity
      check, receipt_url on final-state responses/webhooks and automatic email
      delivery on final states. A pending payout before debit does not expose
      receipt_url.
  - name: Authentication
    description: Register and log in account members. Sessions last 24 hours.
  - name: Account
    description: Profile, members and API keys of the calling account.
  - name: Balances
    description: Balances, movement history and FX rates.
  - name: Payouts
    description: >-
      Fiat dispersals debited from the settlement balance of your choice (USD is
      the principal balance).
  - name: Payins
    description: >-
      Fiat top-ups (QR, transfers, dedicated accounts, pull collections, cards,
      checkout links) credited automatically — in USD, or auto-converted to the
      settlement asset of your choice.
  - name: Checkout
    description: >-
      Universal checkout links (`POST /v1/payins` with `method: "checkout"`) and
      the public payment-page endpoints — multi-country fiat, crypto with an
      ephemeral wallet per link and direct CBPay payment, settled in the asset
      of your choice.
  - name: Stored cards
    description: >-
      Cards saved with the payer's explicit consent during a 3-D Secure payment
      (COF). List, revoke and charge them on demand (MIT) without asking for the
      card again.
  - name: Subscriptions
    description: >-
      Recurring charges on a stored card managed by the platform scheduler —
      daily, weekly, monthly or yearly, with pause/resume/cancel and automatic
      dunning.
  - name: Transfers
    description: >-
      Free internal transfers between CBPay accounts (person or company, any
      combination).
  - name: Contacts
    description: >-
      Per-account address book of beneficiaries (CBPay, bank and crypto
      destinations) with phone matching and auto-save on every send.
  - name: Swaps
    description: >-
      Instant conversion between the account's USD (default), USDT, USDC, BTC,
      GOLD, SILVER and PLATINUM balances at the account's quoted rate.
  - name: Crypto
    description: On-chain funding and withdrawals (TRON, Ethereum and Bitcoin).
  - name: Segregated wallets
    description: >-
      On-chain wallets with their own balance (companies unlimited; persons 1
      per network+asset pair) — create, import, send, export the private key and
      auto-forward. The balance lives on-chain, never in the ledger.
  - name: Signature proofs
    description: >-
      Cryptographic message signing with wallets (EIP-191 ETH/EVM, TIP-191 TRON)
      — create, list, get and revoke signature proofs with public verification.
  - name: Wallet links
    description: >-
      Link external wallets (custody=client) to your account by signing a nonce
      challenge — create challenges, verify signatures, list and revoke links.
  - name: QR Crypto POS
    description: >-
      Amount-bearing crypto QR charges for processors with physical POS
      terminals (company accounts): verified merchants, exclusive address + QR
      per charge, early payment detection, per-merchant reconciliation and
      refunds over the crypto withdrawal rail.
  - name: KYC / KYB
    description: >-
      Identity verification: KYC for persons, KYB for companies — your own
      onboarding and third-party verifications for company accounts.
  - name: AML/CFT screening
    description: >-
      Standalone AML/CFT screening of persons and companies against sanctions,
      PEP and adverse media lists, with rescreening, continuous monitoring and a
      downloadable PDF report.
  - name: Wallet screening
    description: >-
      AML/CFT risk assessment of blockchain addresses (sanctions, illicit-fund
      exposure) with a per-scan fee, plus free automatic protection on
      withdrawals and deposits.
  - name: Qscore
    description: >-
      API-first credit bureau. Issues complete credit reports with a 1-999 score
      (bands A-E, or SC when there is no data), reads the latest score of a
      subject and manages ARCO disputes. Chile first, with a country-agnostic
      design. Every issued report carries a public verification code.
  - name: Analytics
  - name: Webhooks
    description: Subscriptions to receive signed event notifications.
  - name: Status
    description: Service availability.
  - name: Banking
    description: >-
      Real bank accounts: receive, hold and send money over international
      banking rails.
  - name: Cards
    description: >-
      Virtual and physical cards that spend Just-In-Time from any of the seven
      spending assets (USD, USDT, USDC, BTC, GOLD, SILVER or PLATINUM), with
      per-card spending limits.
  - name: Security (OTP)
    description: >-
      One-time verification codes over SMS/WhatsApp/email protecting sensitive
      actions, plus self-service 2FA preferences. Applies to user sessions only
      — API keys are exempt.
  - name: Passkeys
    description: >-
      Passwordless sign-in with the device's biometrics (Face ID, Touch ID,
      Windows Hello, security keys) via WebAuthn, authenticator apps (TOTP) with
      backup codes, and session/device management.
  - name: Social login
    description: >-
      Passwordless sign up and sign in with Google, Apple, Microsoft and
      Facebook via token exchange. The front end obtains the provider
      credential; the API verifies it and issues the CBPay session.
  - name: Real-time events
    description: >-
      Server-Sent Events stream with everything that happens in the account (or
      across the organization for admins), replay with `Last-Event-ID`, optional
      initial snapshot and a 90-day queryable history.
  - name: Trust Center
    description: >-
      Public Trust Center metadata and tokenized NDA-gated compliance document
      access.
  - name: Contracts
    description: Pre-filled Grupo CB framework agreements for verified company accounts.
  - name: Referrer portal
    description: >-
      Read-only portal for referrers (account credential of the payout account):
      profile, referred clients, accrued commissions and the trilingual
      statement (JSON/PDF/XLSX).
paths:
  /v1/contacts/merge:
    post:
      tags:
        - Contacts
      summary: Merge duplicate contacts
      description: >-
        Fuses 2 to 20 contacts into one survivor (one person = one contact with
        many destinations). Destinations move to the survivor; a missing or
        foreign id answers 404 and merges nothing (no partial merge). Not
        idempotent: retrying after success answers 404 (sources already
        deleted), so the client must not blindly retry.
      operationId: mergeContacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - contact_ids
              properties:
                contact_ids:
                  type: array
                  minItems: 2
                  maxItems: 20
                  items:
                    type: string
                    format: uuid
                  description: Distinct contacts of your account book to fuse.
                surviving_contact_id:
                  type: string
                  format: uuid
                  description: >-
                    The contact that survives (must be one of contact_ids;
                    defaults to the first).
                display_name:
                  type: string
                  description: Optional override for the surviving display name.
                alias:
                  type: string
                  description: Optional override for the surviving alias.
            example:
              contact_ids:
                - 3f8a1b2c-4d5e-6f70-8a9b-0c1d2e3f4a5b
                - 9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f
              surviving_contact_id: 3f8a1b2c-4d5e-6f70-8a9b-0c1d2e3f4a5b
      responses:
        '200':
          description: Merged contact with all destinations.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Contact'
                  - type: object
                    properties:
                      merged_contact_ids:
                        type: array
                        items:
                          type: string
                          format: uuid
                        description: Source contacts that were deleted by the merge.
              example:
                contact_id: 3f8a1b2c-4d5e-6f70-8a9b-0c1d2e3f4a5b
                display_name: Carlos Soto
                phone: '+56987654321'
                has_cbpay: true
                source: import
                favorite: true
                destinations:
                  - destination_id: aa11bb22-cc33-44dd-8899-aabbccddeeff
                    type: payout
                    country: CL
                    currency: CLP
                    method: bank_transfer
                  - destination_id: bb22c3d4-5e6f-7a80-9b0c-1d2e3f4a5b6c
                    type: crypto
                    chain: tron
                    address: TVJ6njG5Fyrq6XwYok3xPQx8kR7HQx6vXk
                merged_contact_ids:
                  - 9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f
                created_at: '2026-07-07T12:00:00Z'
                updated_at: '2026-11-13T12:00:00Z'
        '400':
          description: invalid_payload / batch_too_large / invalid_characters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: invalid_payload
                message: contact_ids must include at least 2 distinct contacts
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: An inherited phone/email belongs to another contact of your book.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: duplicate
                message: duplicate
components:
  schemas:
    Contact:
      type: object
      properties:
        contact_id:
          type: string
          format: uuid
        display_name:
          type: string
        alias:
          type: string
        phone:
          type: string
          description: E.164.
        email:
          type: string
        has_cbpay:
          type: boolean
          description: True when the phone matches an active account of your operator.
        cbpay_account_id:
          type: string
          format: uuid
          description: Linked account (present when has_cbpay is true).
        source:
          type: string
          enum:
            - manual
            - import
            - transfer
            - payout
            - crypto
        favorite:
          type: boolean
        destinations:
          type: array
          description: >-
            Present on the detail endpoint and on contact lists when
            `expand=destinations`. Optional `dest_type` and `dest_country`
            filters apply only to this expanded field.
          items:
            $ref: '#/components/schemas/ContactDestination'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        error:
          type: string
          description: Machine-readable error code (snake_case).
          example: insufficient_funds
        message:
          type: string
          description: Human-readable explanation.
    ContactDestination:
      type: object
      properties:
        destination_id:
          type: string
          format: uuid
        type:
          type: string
          enum:
            - cbpay
            - payout
            - crypto
        country:
          type: string
        currency:
          type: string
        method:
          type: string
        chain:
          type: string
        address:
          type: string
        details:
          type: object
          description: Full payout beneficiary for payout destinations.
        label:
          type: string
        last_used_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
  responses:
    Unauthorized:
      description: Missing or invalid credential (`unauthorized`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: unauthorized
            message: invalid or missing credentials
    NotFound:
      description: Resource not found (`not_found`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: not_found
            message: resource not found
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        Session JWT (from register/login) or API key (`pk_...`).
        `X-API-Key: <token>` is accepted as an alternative header.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.