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

# Merge entities in bulk from a spreadsheet

> Applies the `mergedIntoId` column of an entity import, merging each entity into the one its id names. Send the whole file in one request: chains and cycles are resolved across the entire edge set, so a partial batch resolves differently. Bad edges fail their own row and leave the rest to apply.



## OpenAPI

````yaml https://api.mentionlab.io/api/docs-json post /api/entities/import/merge
openapi: 3.0.0
info:
  title: MentionLab Public API v0.3.4-rc
  description: ''
  version: 0.3.4-rc
  contact: {}
servers:
  - url: https://api.mentionlab.io
security: []
tags: []
paths:
  /api/entities/import/merge:
    post:
      tags:
        - Entities
      summary: Merge entities in bulk from a spreadsheet
      description: >-
        Applies the `mergedIntoId` column of an entity import, merging each
        entity into the one its id names. Send the whole file in one request:
        chains and cycles are resolved across the entire edge set, so a partial
        batch resolves differently. Bad edges fail their own row and leave the
        rest to apply.
      operationId: EntitiesRefController_importMerges
      parameters:
        - name: x-project-id
          in: header
          description: Project ID to specify the project context
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportMergeEntitiesDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportMergeEntitiesResponse'
        '400':
          description: >-
            The request failed validation — the body, query or path parameters
            are malformed or out of range.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: The request is missing valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: >-
            The authenticated principal lacks the required permission, or access
            to the requested organisation/project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
components:
  schemas:
    ImportMergeEntitiesDto:
      type: object
      properties:
        edges:
          description: >-
            Every merge edge in the file, in one request. Chains and cycles are
            resolved across the whole set.
          example:
            - id: 019daf29-0000-7000-8000-0000000000b1
              mergedIntoId: 019daf29-0000-7000-8000-0000000000a1
          type: array
          items:
            $ref: '#/components/schemas/ImportMergeEdgeDto'
        dryRun:
          type: boolean
          description: Report what would happen without merging anything.
          example: true
      required:
        - edges
    ImportMergeEntitiesResponse:
      type: object
      properties:
        dryRun:
          type: boolean
          description: True when nothing was written.
          example: false
        merged:
          type: number
          description: Entities merged away.
          example: 42
        unchanged:
          type: number
          description: Edges that were already satisfied.
          example: 3
        failed:
          type: number
          description: Edges rejected.
          example: 1
        survivors:
          type: number
          description: >-
            Distinct survivors this batch resolved to, the number of merge
            operations performed.
          example: 7
        results:
          description: One entry per submitted edge, in submission order.
          type: array
          items:
            $ref: '#/components/schemas/ImportMergeEdgeResultResponse'
      required:
        - dryRun
        - merged
        - unchanged
        - failed
        - survivors
        - results
    ApiErrorResponse:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP status code of the error.
          example: 400
        message:
          type: string
          description: >-
            Human-readable description of the error. Validation failures return
            an array of per-field validation errors instead of a single string.
          example: Validation failed
        error:
          type: string
          description: Short name of the HTTP error.
          example: Bad Request
      required:
        - statusCode
    ImportMergeEdgeDto:
      type: object
      properties:
        id:
          type: string
          description: The entity to merge away.
          format: uuid
          example: 019daf29-0000-7000-8000-0000000000b1
        mergedIntoId:
          type: string
          description: The entity it should be merged into. Must be an id, never a name.
          format: uuid
          example: 019daf29-0000-7000-8000-0000000000a1
      required:
        - id
        - mergedIntoId
    ImportMergeEdgeResultResponse:
      type: object
      properties:
        index:
          type: number
          description: Zero-based index of the edge in the submitted batch.
          example: 0
        action:
          type: string
          enum:
            - merged
            - unchanged
            - failed
          example: merged
        resolvedParentId:
          type: string
          description: >-
            The survivor the entity actually ended up under. Differs from the
            requested mergedIntoId when the file described a chain, or when that
            parent was itself already merged, the graph is always flattened to
            its root.
          format: uuid
          example: 019daf29-0000-7000-8000-0000000000a1
        error:
          type: string
          enum:
            - self-reference
            - cycle
            - entity-not-found
            - parent-not-found
            - conflicting-parent
        detail:
          type: string
          description: Human-readable context for the failure.
          example: b1 → a1 closes a loop
      required:
        - index
        - action

````