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

# Separate one contact into two

> Splits the source contact into two contacts based on a field split and child-record assignment plan. Admin/Superadmin only. Validates phone format, email format, and uniqueness; rejects splits that would violate the per-org phone uniqueness invariant.



## OpenAPI

````yaml /api-reference/openapi.yaml post /api/contacts/{id}/separate
openapi: 3.0.3
info:
  title: Tether Relay and Tether API
  version: 1.0.0
  description: >-
    Route-derived OpenAPI contract generated from tether-relay backend sources.
    Regenerate with scripts/sync-openapi-from-backend.mjs.
servers:
  - url: https://your-instance.example.com
    description: Production
  - url: http://localhost:2212
    description: Local API service
security: []
tags:
  - name: AI
  - name: Applications
  - name: Approval
  - name: Auth
  - name: Automations
  - name: Calls
  - name: Campaigns
  - name: Contact Analytics
  - name: Contact Metrics
  - name: Contact Notes
  - name: Contacts
  - name: Conversation Monitor
  - name: Conversations
  - name: Departments
  - name: Email
  - name: Escalation Dashboard
  - name: Event Logs
  - name: Google Sheets
  - name: Marketplace
  - name: Messages
  - name: Notification Sounds
  - name: Notifications
  - name: Org Snapshots
  - name: Organizations
  - name: Outreach
  - name: Outreach Metrics
  - name: Outreach Sources
  - name: Pipelines
  - name: Processes
  - name: Prompts
  - name: Reminders
  - name: Sms
  - name: Templates
  - name: Traces
  - name: Training
  - name: Upload
  - name: User Snapshots
  - name: Users
  - name: Vertical
  - name: Webchats
  - name: Webhook
paths:
  /api/contacts/{id}/separate:
    post:
      tags:
        - Contacts
      summary: Separate one contact into two
      description: >-
        Splits the source contact into two contacts based on a field split and
        child-record assignment plan. Admin/Superadmin only. Validates phone
        format, email format, and uniqueness; rejects splits that would violate
        the per-org phone uniqueness invariant.
      operationId: post_contact_separate
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SeparateContactRequest'
      responses:
        '200':
          description: Contact separated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SeparateContactResponseEnvelope'
        '400':
          description: Invalid payload or precondition error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyErrorResponse'
        '403':
          description: Caller is not admin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyErrorResponse'
        '404':
          description: Contact not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    SeparateContactRequest:
      type: object
      properties:
        fieldSplit:
          allOf:
            - $ref: '#/components/schemas/SeparateContactFieldSplit'
          description: >-
            How each contact field (name, phone, email, documents, misc, etc.)
            is divided between the original and the newly-created contact.
        childRecordAssignment:
          allOf:
            - $ref: '#/components/schemas/SeparateContactChildRecordAssignment'
          description: >-
            Per-record-type maps assigning each
            conversation/application/note/reminder/training-snapshot id to
            either `original` or `new`.
        messageDividers:
          type: array
          items:
            $ref: '#/components/schemas/SeparateContactMessageDivider'
          description: >-
            Optional per-conversation message-split points indicating where to
            cut the message timeline between the two contacts.
        newConversationMeta:
          type: array
          items:
            $ref: '#/components/schemas/SeparateContactNewConversationMeta'
          description: >-
            Optional metadata (e.g. channel, assignees) for any brand-new
            conversations created on the separated contact.
      required:
        - fieldSplit
        - childRecordAssignment
      additionalProperties: true
      example:
        fieldSplit:
          firstName:
            original: Jane
            new: Janet
          lastName:
            original: Doe
            new: Doe
          status: original
          pipelineId: original
          pipelineStage: original
          assignees: original
          outreachConfigId: original
        childRecordAssignment:
          conversations:
            64f0a1b2c3d4e5f6a7b8c9e0: new
          applications: {}
          contactNotes: {}
          reminders: {}
          trainingSnapshots: {}
    SeparateContactResponseEnvelope:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        data:
          type: object
          properties:
            originalContactId:
              type: string
            newContactId:
              type: string
            summary:
              type: object
              properties:
                conversationsMoved:
                  type: integer
                applicationsMoved:
                  type: integer
                notesMoved:
                  type: integer
                remindersMoved:
                  type: integer
                trainingSnapshotsMoved:
                  type: integer
                messagesReassigned:
                  type: integer
              additionalProperties: true
          required:
            - originalContactId
            - newContactId
          additionalProperties: true
      required:
        - success
        - data
      additionalProperties: true
      example:
        success: true
        data:
          originalContactId: 64f0a1b2c3d4e5f6a7b8c9d0
          newContactId: 64f0a1b2c3d4e5f6a7b8ca20
          summary:
            conversationsMoved: 1
            applicationsMoved: 0
            notesMoved: 0
            remindersMoved: 0
            trainingSnapshotsMoved: 0
            messagesReassigned: 4
    LegacyErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        data: {}
      additionalProperties: true
      example:
        error: Attachment not found
        message: Attachment not found
    SeparateContactFieldSplit:
      type: object
      properties:
        firstName:
          $ref: '#/components/schemas/SeparationFieldOriginalNewString'
        lastName:
          $ref: '#/components/schemas/SeparationFieldOriginalNewString'
        email:
          $ref: '#/components/schemas/SeparationFieldOriginalNewStringOptional'
        phoneNumber:
          $ref: '#/components/schemas/SeparationFieldOriginalNewStringOptional'
        dateOfBirth:
          $ref: '#/components/schemas/SeparationFieldOriginalNewStringOptional'
        documents:
          $ref: '#/components/schemas/SeparationFieldDocuments'
        misc:
          $ref: '#/components/schemas/SeparationFieldMisc'
        status:
          $ref: '#/components/schemas/SeparationTarget'
        pipelineId:
          $ref: '#/components/schemas/SeparationTarget'
        pipelineStage:
          $ref: '#/components/schemas/SeparationTarget'
        assignees:
          $ref: '#/components/schemas/SeparationTarget'
        outreachConfigId:
          $ref: '#/components/schemas/SeparationTarget'
      required:
        - firstName
        - lastName
        - status
        - pipelineId
        - pipelineStage
        - assignees
        - outreachConfigId
      additionalProperties: true
      example:
        firstName:
          original: Jane
          new: Janet
        lastName:
          original: Doe
          new: Doe
        phoneNumber:
          original: '+14165550100'
          new: '+14165550199'
        status: original
        pipelineId: original
        pipelineStage: original
        assignees: original
        outreachConfigId: original
    SeparateContactChildRecordAssignment:
      type: object
      properties:
        conversations:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/SeparationTarget'
        applications:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/SeparationTarget'
        contactNotes:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/SeparationTarget'
        reminders:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/SeparationTarget'
        trainingSnapshots:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/SeparationTarget'
      required:
        - conversations
        - applications
        - contactNotes
        - reminders
        - trainingSnapshots
      additionalProperties: false
      example:
        conversations:
          64f0a1b2c3d4e5f6a7b8c9e0: original
        applications:
          64f0a1b2c3d4e5f6a7b8c9f0: new
        contactNotes: {}
        reminders: {}
        trainingSnapshots: {}
    SeparateContactMessageDivider:
      type: object
      properties:
        conversationId:
          type: string
        dividerMessageId:
          type: string
        direction:
          type: string
          enum:
            - before_to_original
            - before_to_new
      required:
        - conversationId
        - dividerMessageId
        - direction
      additionalProperties: false
      example:
        conversationId: 64f0a1b2c3d4e5f6a7b8c9e0
        dividerMessageId: 64f0a1b2c3d4e5f6a7b8c9f6
        direction: before_to_original
    SeparateContactNewConversationMeta:
      type: object
      properties:
        conversationId:
          type: string
        assignees:
          type: array
          items:
            type: string
        status:
          type: string
      required:
        - conversationId
      additionalProperties: true
      example:
        conversationId: 64f0a1b2c3d4e5f6a7b8c9e1
        assignees:
          - 64f0a1b2c3d4e5f6a7b8c9d4
        status: New Lead
    SeparationFieldOriginalNewString:
      type: object
      properties:
        original:
          type: string
        new:
          type: string
      required:
        - original
        - new
      additionalProperties: false
      example:
        original: Jane
        new: Janet
    SeparationFieldOriginalNewStringOptional:
      type: object
      properties:
        original:
          type: string
          nullable: true
        new:
          type: string
          nullable: true
      additionalProperties: false
      example:
        original: jane.doe@example.com
        new: janet.doe@example.com
    SeparationFieldDocuments:
      type: object
      properties:
        original:
          type: array
          items:
            type: string
        new:
          type: array
          items:
            type: string
      additionalProperties: false
      example:
        original:
          - 64f0a1b2c3d4e5f6a7b8ca10
        new:
          - 64f0a1b2c3d4e5f6a7b8ca11
    SeparationFieldMisc:
      type: object
      properties:
        original:
          type: object
          additionalProperties: true
        new:
          type: object
          additionalProperties: true
      additionalProperties: false
      example:
        original:
          creditScore: 720
        new:
          creditScore: 685
    SeparationTarget:
      type: string
      enum:
        - original
        - new
      example: original
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````