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

# Merge companies

> Manual duplicate resolution: move the source company's leads onto the target and union the source's table membership into the target, one transaction. The source row is not deleted: it stays; delete_company removes it when ready. Not gated on the duplicate flag. Re-running moves zero people; merging a row into itself is 422. When NOT: naming the real row without moving anything (make_company_primary); a per-table removal (detach_company_playtable).

Contract:
- MCP tool `merge_companies`, registry package `mcp.playtables/companies`, mount `playtables.people`.
- Operation `action`, response envelope `action`.
- Flags: none.



## OpenAPI

````yaml /api-reference/playtables/openapi.yaml post /api/companies/{sid}/merge
openapi: 3.0.3
info:
  title: 'GetSales public contract: gs.service.playtables'
  description: >-
    The data platform and the outreach engine: tables of people and companies,
    their enrichment columns, cells and runs, the data sources that feed them,
    sender profiles, the stoplist, the activity feed, the credit ledger, and the
    multichannel workflows with their per-person journeys and tasks.


    GENERATED. This document is projected from the Zod MCP tool registry in
    `product/mcp/gs.mcp` (one tool per public endpoint, 1:1). Do not edit it by
    hand; edit the tool definition and regenerate with `pnpm openapi:public`.


    Surface: the public `/api` contract of `gs.service.playtables`, 142
    operations. This is the only OpenAPI document the platform publishes.
    Internal (`/internal`) and health endpoints are deliberately absent: they
    are not part of any contract, they can change without notice, and the
    service source is their only description.


    Conventions:

    - Auth is a bearer JWT, optionally narrowed by the `Team-SID` header.

    - Every success body is an MCP envelope: `success: true` plus one typed
    `operation` shape (`search`, `get`, `create`, `update`, `delete`, `metrics`,
    `group_by`, `action`), and a `meta` block with `trace_id` for support.

    - Every failure is the same `McpError` envelope with a code from a fixed
    16-code taxonomy, so a client maps errors once.

    - Lists page with `page_size` (0 to 500, default 50) plus an opaque forward
    `cursor`; `page_size: 0` returns counts only.

    - On `GET` and `DELETE`, object-valued query parameters (`filter`, `sort`)
    travel as JSON text and array-valued ones repeat as `name[]=value`.

    - The MCP-only `_meta` field (usage analytics) never reaches the backend and
    is not part of this contract.
  version: '1.0'
  contact:
    name: GetSales
    url: https://getsales.io
    email: support@getsales.io
  license:
    name: Proprietary
    url: https://getsales.io/terms
servers:
  - url: https://beta.getsales.io/playtables/v1
    description: >-
      Production (the gateway path on the beta ring; the origin is provisioned
      per DEPLOY_MAP.md)
security:
  - BearerJwt: []
    TeamSid: []
tags:
  - name: activities
    description: >-
      Registry package `mcp.playtables/activities`, served on MCP mount
      `playtables.journeys`.
  - name: activity_objects
    description: >-
      Registry package `mcp.playtables/activity_objects`, served on MCP mount
      `playtables.people`.
  - name: companies
    description: >-
      Registry package `mcp.playtables/companies`, served on MCP mount
      `playtables.people`.
  - name: credit_ledger_entries
    description: >-
      Registry package `mcp.playtables/credit_ledger_entries`, served on MCP
      mount `id.billing`.
  - name: data_source_items
    description: >-
      Registry package `mcp.playtables/data_source_items`, served on MCP mount
      `playtables.sources`.
  - name: data_sources
    description: >-
      Registry package `mcp.playtables/data_sources`, served on MCP mount
      `playtables.sources`.
  - name: notes
    description: >-
      Registry package `mcp.playtables/notes`, served on MCP mount
      `playtables.pipeline`.
  - name: people
    description: >-
      Registry package `mcp.playtables/people`, served on MCP mount
      `playtables.people`.
  - name: pipeline_stages
    description: >-
      Registry package `mcp.playtables/pipeline_stages`, served on MCP mount
      `playtables.pipeline`.
  - name: plays
    description: >-
      Registry package `mcp.playtables/plays`, served on MCP mount
      `playtables.pipeline`.
  - name: playtable_field_values
    description: >-
      Registry package `mcp.playtables/playtable_field_values`, served on MCP
      mount `playtables.columns`.
  - name: playtable_fields
    description: >-
      Registry package `mcp.playtables/playtable_fields`, served on MCP mount
      `playtables.columns`.
  - name: playtable_runs
    description: >-
      Registry package `mcp.playtables/playtable_runs`, served on MCP mount
      `playtables.columns`.
  - name: playtable_views
    description: >-
      Registry package `mcp.playtables/playtable_views`, served on MCP mount
      `playtables.tables`.
  - name: playtables
    description: >-
      Registry package `mcp.playtables/playtables`, served on MCP mount
      `playtables.tables`.
  - name: result_pages
    description: >-
      Registry package `mcp.playtables/result_pages`, served on MCP mount
      `playtables.tables`.
  - name: sender_profiles
    description: >-
      Registry package `mcp.playtables/sender_profiles`, served on MCP mount
      `playtables.sources`.
  - name: stoplist_entries
    description: >-
      Registry package `mcp.playtables/stoplist_entries`, served on MCP mount
      `playtables.stoplist`.
  - name: tags
    description: >-
      Registry package `mcp.playtables/tags`, served on MCP mount
      `playtables.pipeline`.
  - name: workflow_attachments
    description: >-
      Registry package `mcp.playtables/workflow_attachments`, served on MCP
      mount `playtables.workflows`.
  - name: workflow_records
    description: >-
      Registry package `mcp.playtables/workflow_records`, served on MCP mount
      `playtables.journeys`.
  - name: workflow_sources
    description: >-
      Registry package `mcp.playtables/workflow_sources`, served on MCP mount
      `playtables.workflows`.
  - name: workflow_tasks
    description: >-
      Registry package `mcp.playtables/workflow_tasks`, served on MCP mount
      `playtables.journeys`.
  - name: workflow_versions
    description: >-
      Registry package `mcp.playtables/workflow_versions`, served on MCP mount
      `playtables.workflows`.
  - name: workflows
    description: >-
      Registry package `mcp.playtables/workflows`, served on MCP mount
      `playtables.workflows`.
paths:
  /api/companies/{sid}/merge:
    post:
      tags:
        - companies
      summary: Merge companies
      description: >-
        Manual duplicate resolution: move the source company's leads onto the
        target and union the source's table membership into the target, one
        transaction. The source row is not deleted: it stays; delete_company
        removes it when ready. Not gated on the duplicate flag. Re-running moves
        zero people; merging a row into itself is 422. When NOT: naming the real
        row without moving anything (make_company_primary); a per-table removal
        (detach_company_playtable).


        Contract:

        - MCP tool `merge_companies`, registry package
        `mcp.playtables/companies`, mount `playtables.people`.

        - Operation `action`, response envelope `action`.

        - Flags: none.
      operationId: merge_companies
      parameters:
        - name: sid
          in: path
          required: true
          description: The SOURCE (usually the flagged duplicate) - drained, never deleted.
          schema:
            type: string
            minLength: 18
            maxLength: 18
            pattern: ^cr_co_
            description: >-
              The SOURCE (usually the flagged duplicate) - drained, never
              deleted.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MergeCompaniesRequest'
      responses:
        '200':
          description: '`action` success envelope.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MergeCompaniesResponse'
        4XX:
          $ref: '#/components/responses/McpClientError'
        5XX:
          $ref: '#/components/responses/McpServerError'
components:
  schemas:
    MergeCompaniesRequest:
      type: object
      description: Request body of `merge_companies`.
      properties:
        into_sid:
          type: string
          minLength: 18
          maxLength: 18
          pattern: ^cr_co_
          description: >-
            The TARGET (the primary account) that receives the leads and the
            membership.
      required:
        - into_sid
    MergeCompaniesResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        operation:
          type: string
          enum:
            - action
        action:
          type: string
          description: kebab-case verb; matches the route segment.
        item:
          type: object
          nullable: true
          properties:
            sid:
              type: string
            team_sid:
              type: string
            playtable_sids:
              type: array
              items:
                type: string
              description: >-
                Member tables (pt_tb_…) - MULTI membership; service-managed
                (create/import union, detach / table-delete pull); may be empty.
                Filtering/counting on it is ES-served.
            data_source_sid:
              type: string
              nullable: true
            data_source_type:
              type: string
              nullable: true
            data_source_item_sid:
              type: string
              nullable: true
            ln_id:
              type: string
              nullable: true
              description: Numeric LinkedIn company id - strongest dedup key.
            ln_nickname:
              type: string
              nullable: true
              description: >-
                The company page vanity slug (acme-corp), lowercased; a page URL
                is reduced to it on write, never stored (SERVICE_CONVENTIONS
                §Y). Dedup key #2.
            context:
              type: object
              nullable: true
              properties:
                name:
                  type: string
                  nullable: true
                picture_url:
                  type: string
                  nullable: true
                  description: >-
                    The logo: a permanent copy over a wire link; null = the
                    reader falls back to the domain favicon.
                website:
                  type: string
                  nullable: true
                  description: >-
                    The full URL a source gave; domain on the row stays the
                    identifier.
                sources:
                  type: object
                  additionalProperties:
                    type: object
                    properties:
                      kind:
                        type: string
                        enum:
                          - data_source_item
                          - file_record
                          - enrichment_cell
                          - participant
                          - connection
                          - profile_read
                          - duplicate_record
                          - manual
                          - legacy_column
                        description: >-
                          Who said it. A manual word stands until reset;
                          profile_read, enrichment_cell, participant,
                          connection, data_source_item and duplicate_record (a
                          LinkedIn-shaped record another source brought) saw
                          LinkedIn and rank next, newest first; file_record (a
                          CSV or a webhook) and legacy_column (what the dropped
                          column held, backfilled) come last.
                      observed_at:
                        type: string
                        nullable: true
                        description: >-
                          When the source saw it (ISO 8601); null for a column
                          with no clock.
                    required:
                      - kind
                      - observed_at
                  description: Per resolved key, where it came from and when.
              required:
                - name
                - picture_url
                - website
                - sources
              description: >-
                DERIVED and read-only (CONTEXT_FIELDS_RESEARCH.md section 5):
                the name, the logo and the website a surface or a model shows
                next to the row, resolved at read from the observations ledger
                with the same precedence as a person's. The only place these
                words are: the row keeps identifiers (phase E, 2026-10-22).
            domain:
              type: string
              nullable: true
              description: >-
                Lowercased apex domain; derived from website when absent; dedup
                key #3.
            deal_size:
              type: number
              nullable: true
              description: >-
                Deal value attached to the account (decimal 15,2) - the one
                client-writable business column.
            status:
              type: string
              enum:
                - ok
                - failed_validation
                - duplicate
                - stoplisted
              description: >-
                Service-managed (import validation, stoplist); not
                client-writable.
            status_reason:
              type: string
              nullable: true
              description: >-
                Human-readable context for the current status (validation error,
                matched stoplist identifier); service-written together with
                status. A duplicate carries none: its pointer is
                duplicate_of_sid.
            duplicate_of_sid:
              type: string
              nullable: true
              description: >-
                While status is duplicate: the PRIMARY account (cr_co_…) this
                one is a copy of - one primary per group, re-derived on every
                recheck, swapped by make_company_primary. Null otherwise.
            duplicate_matched_kind:
              type: string
              nullable: true
              enum:
                - ln_id
                - ln_nickname
                - domain
              description: >-
                While status is duplicate: the identity column the late write
                collided on. Null otherwise.
            tag_sids:
              type: array
              nullable: true
              items:
                type: string
            external_refs:
              anyOf:
                - type: object
                  additionalProperties:
                    type: string
                - type: array
                  items: {}
                - {}
              description: >-
                Free-form CRM sync hook ({ hubspot_company_id: "902", … }); keys
                are integration-defined, stored as-is, round-tripped, never
                validated; PHP empty map serialises as [].
            last_enrich_at:
              type: string
              nullable: true
              description: >-
                ISO 8601 UTC; stamped when an enrichment cycle completes -
                drives enrichment scheduling.
            deleted_by:
              type: object
              nullable: true
              properties:
                actor_type:
                  type: string
                  enum:
                    - user
                    - support
                    - api_key
                    - system
                    - agent
                actor_sid:
                  type: string
                  nullable: true
                team_sid:
                  type: string
                actor_name:
                  type: string
                  nullable: true
                  description: >-
                    The OAuth client that acted ("Claude", "n8n"); null for a
                    user, an API key or a system job.
                oauth_client_sid:
                  type: string
                  nullable: true
                  description: The acting OAuth client (id_oc_*); null off the OAuth path.
                reason:
                  type: string
                  nullable: true
                  description: >-
                    Why a system actor wrote the row (snapshot_capture_job,
                    ...); null otherwise.
                permissions:
                  type: object
                  additionalProperties: {}
                  description: >-
                    Internal audit context: the grant set the actor held at
                    write time. Not a contract.
                cluster_id:
                  type: integer
                  nullable: true
                  description: 'Internal audit context: the cluster that served the write.'
                trace_id:
                  type: string
                  nullable: true
                  description: >-
                    Internal audit context: the trace id of the request that
                    wrote the row.
              required:
                - actor_type
                - actor_sid
                - team_sid
                - permissions
            created_at:
              type: string
            updated_at:
              type: string
            deleted_at:
              type: string
              nullable: true
            pipeline_stage_sid:
              type: string
              nullable: true
              description: >-
                The funnel stage the company is in (cr_ps_...): derived from its
                people unless pinned (pipeline_stages.md); null = no stage.
            pipeline_stage_source:
              type: string
              nullable: true
              enum:
                - derived
                - manual
              description: >-
                How the stage was set (CompanyPipelineStageSourceEnum): derived
                from the people, or pinned by a manual move;
                reset_pipeline_stages_derivation drops the pin. Null with no
                stage.
          required:
            - sid
            - team_sid
            - playtable_sids
            - data_source_sid
            - data_source_type
            - data_source_item_sid
            - ln_id
            - ln_nickname
            - context
            - domain
            - deal_size
            - status
            - status_reason
            - duplicate_of_sid
            - duplicate_matched_kind
            - tag_sids
            - external_refs
            - last_enrich_at
            - deleted_by
            - created_at
            - updated_at
            - deleted_at
            - pipeline_stage_sid
            - pipeline_stage_source
        result:
          type: object
          properties:
            source_sid:
              type: string
              description: The source that was drained (cr_co_…).
            moved_people_count:
              type: integer
              description: Leads repointed by THIS call; a re-run moves zero.
          required:
            - source_sid
            - moved_people_count
        meta:
          type: object
          properties:
            trace_id:
              type: string
              description: UUID v7; same 128-bit value as the X-Trace-Id header.
            span_id:
              type: string
              pattern: ^[0-9a-f]{16}$
              description: 16 hex chars, root span of this request.
            timestamp:
              type: string
              description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
            duration_ms:
              type: integer
              minimum: 0
              description: Server-side wall clock.
            team_sid:
              type: string
              nullable: true
              description: >-
                The team this call ran in (the token team, or the team_sid
                override). Null when unauthenticated; absent from pre-2026-08-20
                backends.
            actor_type:
              type: string
              nullable: true
              description: >-
                user | agent | api_key | system. Null when unauthenticated;
                absent from pre-2026-08-20 backends.
          required:
            - trace_id
            - span_id
            - timestamp
            - duration_ms
      required:
        - success
        - operation
        - action
        - item
        - result
        - meta
    McpError:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - validation_failed
                - nothing_to_update
                - not_found
                - relation_not_found
                - invalid_transition
                - limit_exceeded
                - payment_required
                - duplicate_rejected
                - conflict
                - delete_blocked
                - unauthorized
                - forbidden
                - rate_limited
                - internal_error
                - service_unavailable
                - not_implemented
            message:
              type: string
            recoverable:
              type: boolean
            suggestion:
              type: string
            field_errors:
              type: object
              additionalProperties:
                type: array
                items:
                  type: object
                  properties:
                    rule:
                      type: string
                    message:
                      type: string
                  required:
                    - rule
                    - message
            blockers:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    description: >-
                      Machine-readable blocker type (active_flow, pending_tasks,
                      …).
                  severity:
                    type: string
                    enum:
                      - hard
                      - soft
                    description: >-
                      hard = external action required; soft = acknowledge is
                      enough.
                  description:
                    type: string
                  entity_sid:
                    type: string
                    nullable: true
                  count:
                    type: integer
                  resolution:
                    type: string
                    description: 'Hard: tool name to call. Soft: code for acknowledge[].'
                  resolution_hint:
                    type: string
                required:
                  - type
                  - severity
                  - description
                  - entity_sid
                  - resolution
                  - resolution_hint
            context:
              type: object
              additionalProperties: {}
          required:
            - code
            - message
            - recoverable
        meta:
          type: object
          properties:
            trace_id:
              type: string
              description: UUID v7; same 128-bit value as the X-Trace-Id header.
            span_id:
              type: string
              pattern: ^[0-9a-f]{16}$
              description: 16 hex chars, root span of this request.
            timestamp:
              type: string
              description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
            duration_ms:
              type: integer
              minimum: 0
              description: Server-side wall clock.
            team_sid:
              type: string
              nullable: true
              description: >-
                The team this call ran in (the token team, or the team_sid
                override). Null when unauthenticated; absent from pre-2026-08-20
                backends.
            actor_type:
              type: string
              nullable: true
              description: >-
                user | agent | api_key | system. Null when unauthenticated;
                absent from pre-2026-08-20 backends.
          required:
            - trace_id
            - span_id
            - timestamp
            - duration_ms
      required:
        - success
        - error
  responses:
    McpClientError:
      description: >-
        MCP error envelope. `error.code` is one of validation_failed,
        nothing_to_update, not_found, relation_not_found, invalid_transition,
        limit_exceeded, payment_required, duplicate_rejected, conflict,
        delete_blocked, unauthorized, forbidden, rate_limited, not_implemented.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/McpError'
    McpServerError:
      description: >-
        MCP error envelope with `error.code` internal_error or
        service_unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/McpError'
  securitySchemes:
    BearerJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Access token issued by gs.service.id. Its `access_identity` claim
        carries `team_sid`, `actor_sid` and `actor_type`, and that team scope is
        authoritative.
    TeamSid:
      type: apiKey
      in: header
      name: Team-SID
      description: >-
        Team scope for tokens that do not carry one. Ignored when the token
        already names a team.

````

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