> ## 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. # Import entities from a spreadsheet (create and update) > Creates or updates a batch of rows in one transaction, matching each by `id` or by name; omitted fields are left unchanged and aliases are only ever added. Use dryRun to preview the per-row outcome, and POST /entities/import/merge afterwards for the mergedIntoId column. ## OpenAPI ````yaml https://api.mentionlab.io/api/docs-json post /api/entities/import 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: post: tags: - Entities summary: Import entities from a spreadsheet (create and update) description: >- Creates or updates a batch of rows in one transaction, matching each by `id` or by name; omitted fields are left unchanged and aliases are only ever added. Use dryRun to preview the per-row outcome, and POST /entities/import/merge afterwards for the mergedIntoId column. operationId: EntitiesRefController_importEntities 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/ImportEntitiesDto' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ImportEntitiesResponse' '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: ImportEntitiesDto: type: object properties: rows: description: >- The rows to upsert, in file order. The response carries one result per row at the same index. example: - name: Samsung isCompetitor: true group: Tech Companies type: array items: $ref: '#/components/schemas/ImportEntityRowDto' dryRun: type: boolean description: Report what would happen without writing anything. example: false required: - rows ImportEntitiesResponse: type: object properties: dryRun: type: boolean description: True when nothing was written. example: false created: type: number example: 3 updated: type: number example: 118 unchanged: type: number example: 12 failed: type: number example: 1 results: description: One entry per submitted row, in submission order. type: array items: $ref: '#/components/schemas/ImportEntityRowResultResponse' required: - dryRun - created - updated - unchanged - failed - 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 ImportEntityRowDto: type: object properties: id: type: string description: >- Entity id from the entities export. Authoritative when present; a different `name` renames the entity. format: uuid example: 019daf29-0000-7000-8000-0000000000a1 name: type: string description: >- Entity name. Required when `id` is absent, and then also the match key. example: Samsung type: type: string description: Type/category. Defaults to brand on creation. enum: - brand - person - company - other aliases: description: >- Aliases to add. Never removes one; an alias already owned by another entity is left alone. example: - Samsung Electronics type: array items: type: string domains: description: >- Complete set of domains for this entity, normalised to registrable root domains. Unlike aliases this REPLACES the entity's set, so a domain the list omits is unmapped, and an empty array clears them all. The exported cell already carries the full set, which is what makes a round trip lossless. Absent leaves them untouched, and a blank spreadsheet cell parses to absent rather than to an empty array, so a stale export cannot wipe them by omission. example: - hubspot.com - hubspot.fr type: array items: type: string group: type: string description: >- Name of the top-level group to place the entity in. Must already exist; an unknown name fails the row. example: Tech Companies division: type: string description: >- Name of the division to place the entity in, inside `group` when both are given. Must already exist. example: EMEA isOwned: type: boolean description: Mark entity as owned by the project example: false isCompetitor: type: boolean description: Mark entity as a competitor example: true isBlacklisted: type: boolean description: >- Mark entity as blacklisted (excludes it from analysis but preserves history) example: false isPrimary: type: boolean description: >- Mark the entity as the project's primary brand. At most one row per request may set this true. example: false ImportEntityRowResultResponse: type: object properties: index: type: number description: Zero-based index of the row in the submitted batch. example: 0 action: type: string enum: - created - updated - unchanged - failed entityId: type: string description: The entity this row resolved to. Absent on failure. format: uuid error: type: string enum: - no-identity - name-has-no-slug - entity-not-found - duplicate-identity - ambiguous-name - entity-is-merged - group-not-found - multiple-primary - slug-conflict detail: type: string description: >- Human-readable context for the failure: the conflicting name, the unknown group, or the other row index. example: no group named "Competitors UE" required: - index - action ````