> ## 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.

# Update person

> Partial attribute edit: identity fields, phones, channel statuses, company link, tags, external_refs. An identifier edit that collides with another live row persists and flags the edited row status duplicate, naming the primary in duplicate_of_sid (never a 409; make_person_primary swaps the roles). tag_sids is full-replace. status and playtable_sid are service-managed. Profile content is field values, not here. At least one field, else 422 nothing_to_update.

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



## OpenAPI

````yaml /api-reference/playtables/openapi.yaml patch /api/people/{sid}
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/people/{sid}:
    patch:
      tags:
        - people
      summary: Update person
      description: >-
        Partial attribute edit: identity fields, phones, channel statuses,
        company link, tags, external_refs. An identifier edit that collides with
        another live row persists and flags the edited row status duplicate,
        naming the primary in duplicate_of_sid (never a 409; make_person_primary
        swaps the roles). tag_sids is full-replace. status and playtable_sid are
        service-managed. Profile content is field values, not here. At least one
        field, else 422 nothing_to_update.


        Contract:

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

        - Operation `update`, response envelope `update`.

        - Flags: none.
      operationId: update_person
      parameters:
        - name: sid
          in: path
          required: true
          description: Person sid (cr_pp_…).
          schema:
            type: string
            minLength: 18
            maxLength: 18
            pattern: ^cr_pp_
            description: Person sid (cr_pp_…).
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePersonRequest'
      responses:
        '200':
          description: '`update` success envelope.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdatePersonResponse'
        4XX:
          $ref: '#/components/responses/McpClientError'
        5XX:
          $ref: '#/components/responses/McpServerError'
components:
  schemas:
    UpdatePersonRequest:
      type: object
      description: Request body of `update_person`.
      properties:
        full_name:
          type: string
          nullable: true
          minLength: 1
          maxLength: 255
          description: >-
            New display name (1..255): a manual observation that outranks every
            source until reset; null records a manual none (no name shown).
            Never a column write.
        avatar_url:
          type: string
          nullable: true
          maxLength: 2048
          format: uri
          description: >-
            New profile photo URL (max 2048): a manual observation; null records
            a manual none.
        ln_member_id:
          type: string
          nullable: true
          maxLength: 255
          description: >-
            Identity edit - re-runs the duplicate flag (a collision flags this
            row, never a 409).
        ln_id:
          type: string
          nullable: true
          maxLength: 255
          pattern: ^\S*$
          description: >-
            Raw LinkedIn profile URN (ACoAA...), no spaces; identity edit,
            re-runs the duplicate flag.
        sn_id:
          type: string
          nullable: true
          maxLength: 255
          pattern: ^\S*$
          description: >-
            Raw Sales Navigator URN (ACwAA...), no spaces; identity edit,
            re-runs the duplicate flag.
        recruiter_id:
          type: string
          nullable: true
          maxLength: 255
          pattern: ^\S*$
          description: >-
            Raw Recruiter URN (AEMAA...), no spaces; identity edit, re-runs the
            duplicate flag.
        ln_nickname:
          type: string
          nullable: true
          maxLength: 255
          pattern: ^\S*$
          description: >-
            Vanity slug or profile URL (reduced to its axis on write); re-runs
            the duplicate flag.
        work_email:
          type: string
          nullable: true
          format: email
          description: >-
            Identity edit - re-runs the duplicate flag (a collision flags this
            row, never a 409); stored lowercased.
        personal_email:
          type: string
          nullable: true
          format: email
          description: Identity edit - re-runs the duplicate flag; stored lowercased.
        work_phone_number:
          type: string
          nullable: true
          maxLength: 255
          description: >-
            Plain string, E.164 preferred; identity edit on the E.164 twin,
            re-runs the duplicate flag.
        personal_phone_number:
          type: string
          nullable: true
          maxLength: 255
          description: >-
            Plain string, E.164 preferred; identity edit on the E.164 twin,
            re-runs the duplicate flag.
        linkedin_status:
          type: string
          enum:
            - need_enrichment
            - enrichment_failed
            - no_data
            - blocked
            - ok
          description: >-
            Channel status override (need_enrichment | enrichment_failed |
            no_data | blocked | ok).
        email_status:
          type: string
          nullable: true
          enum:
            - need_search
            - no_data
            - bounced
            - ok
            - catch_all
            - unverified
          description: >-
            need_search | no_data | bounced | ok; null = channel not
            initialized.
        phone_status:
          type: string
          nullable: true
          enum:
            - need_search
            - no_data
            - ok
          description: need_search | no_data | ok; null = channel not initialized.
        company_sid:
          type: string
          nullable: true
          minLength: 18
          maxLength: 18
          pattern: ^cr_co_
          description: >-
            Must exist; the person's company then resolves from the account.
            null unlinks the company.
        company_name:
          type: string
          nullable: true
          maxLength: 255
          description: >-
            A manual observation of a name that is not an account, read when no
            company_sid links the row; null records a manual none.
        company_ln_id:
          type: string
          nullable: true
          maxLength: 255
          description: >-
            A manual observation of the company LinkedIn id, read when no
            company_sid links the row; null records a manual none.
        tag_sids:
          type: array
          nullable: true
          items:
            type: string
            minLength: 18
            maxLength: 18
            pattern: ^cr_tg_
          description: Full-replace of the tag array.
        external_refs:
          type: object
          nullable: true
          additionalProperties:
            type: string
          description: >-
            Free-form CRM sync map, full-replace; keys integration-defined,
            stored as-is.
    UpdatePersonResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        operation:
          type: string
          enum:
            - update
        item:
          type: object
          properties:
            sid:
              type: string
            team_sid:
              type: string
            playtable_sid:
              type: string
              description: >-
                pt_tb_… - the SINGLE playtable membership; service-managed,
                changes only via move (create on_duplicate:move / run type
                move).
            data_source_sid:
              type: string
              nullable: true
            data_source_item_sid:
              type: string
              nullable: true
            company_sid:
              type: string
              nullable: true
            context:
              type: object
              nullable: true
              properties:
                name:
                  type: string
                  nullable: true
                first_name:
                  type: string
                  nullable: true
                  description: >-
                    The source's own first name when it gave one, else the first
                    word of name.
                picture_url:
                  type: string
                  nullable: true
                  description: >-
                    A permanent copy over a wire link, the wire link that lasts
                    longest, an expired one counts as none.
                role:
                  type: string
                  nullable: true
                  description: >-
                    The title at the company (the Sales Navigator wire's
                    position, the enrichment's).
                headline:
                  type: string
                  nullable: true
                  description: >-
                    The profile line (the regular and Recruiter wires, the inbox
                    participant, the enrichment).
                company:
                  type: object
                  nullable: true
                  properties:
                    sid:
                      type: string
                      nullable: true
                      description: >-
                        cr_co_… when the person is linked to an account (the
                        account's own resolved context follows); null = a name
                        that is not an account, an import whose company column
                        resolved to none.
                    name:
                      type: string
                      nullable: true
                    domain:
                      type: string
                      nullable: true
                    picture_url:
                      type: string
                      nullable: true
                    ln_id:
                      type: string
                      nullable: true
                      description: >-
                        The company's LinkedIn id: the linked account's own,
                        else the person's company id as a source or an edit gave
                        it.
                  required:
                    - sid
                    - name
                    - domain
                    - picture_url
                    - ln_id
                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
                - first_name
                - picture_url
                - role
                - headline
                - company
                - sources
              description: >-
                DERIVED and read-only (CONTEXT_FIELDS_RESEARCH.md section 5):
                the name, first name, picture, role, headline and company a
                surface or a model shows next to the row, resolved at read from
                the observations ledger: a manual word until reset, then the
                newest LinkedIn-derived observation, then any other. The only
                place these words are: the row keeps identifiers (phase E,
                2026-10-22). Null only on an event payload.
            ln_member_id:
              type: string
              nullable: true
            ln_id:
              type: string
              nullable: true
            sn_id:
              type: string
              nullable: true
            recruiter_id:
              type: string
              nullable: true
            work_email:
              type: string
              nullable: true
            personal_email:
              type: string
              nullable: true
            work_phone_number:
              type: string
              nullable: true
            personal_phone_number:
              type: string
              nullable: true
            status:
              type: string
              enum:
                - ok
                - failed_validation
                - no_contact_data
                - duplicate
                - stoplisted
              description: >-
                Service-managed row validity (import validation, stoplist,
                duplicate detection) - not client-writable.
            duplicate_of_sid:
              type: string
              nullable: true
              description: >-
                While status is duplicate: the PRIMARY row (cr_pp_…) this one is
                a copy of - one primary per group, re-derived on every recheck,
                swapped by make_person_primary. Null otherwise.
            duplicate_matched_kind:
              type: string
              nullable: true
              enum:
                - ln_member_id
                - ln_id
                - sn_id
                - recruiter_id
                - email
                - ln_nickname
                - phone
              description: >-
                While status is duplicate: the identifier the check matched on.
                Null otherwise.
            linkedin_status:
              type: string
              enum:
                - need_enrichment
                - enrichment_failed
                - no_data
                - blocked
                - ok
            email_status:
              type: string
              nullable: true
              enum:
                - need_search
                - no_data
                - bounced
                - ok
                - catch_all
                - unverified
            phone_status:
              type: string
              nullable: true
              enum:
                - need_search
                - no_data
                - ok
            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 map (hubspot_contact_id, …) - keys
                integration-defined, round-tripped as-is; PHP empty map
                serialises as [].
            last_enrich_at:
              type: string
              nullable: true
            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 person is in (cr_ps_...), derived from
                activity or moved by hand (pipeline_stages.md); null = no stage.
          required:
            - sid
            - team_sid
            - playtable_sid
            - data_source_sid
            - data_source_item_sid
            - company_sid
            - context
            - ln_member_id
            - ln_id
            - sn_id
            - recruiter_id
            - work_email
            - personal_email
            - work_phone_number
            - personal_phone_number
            - status
            - duplicate_of_sid
            - duplicate_matched_kind
            - linkedin_status
            - email_status
            - phone_status
            - tag_sids
            - external_refs
            - last_enrich_at
            - created_at
            - updated_at
            - deleted_at
            - pipeline_stage_sid
        updated_fields:
          type: array
          items:
            type: string
        previous_values:
          type: object
          additionalProperties: {}
        kept_fields:
          type: array
          items:
            type: string
          description: >-
            The fields this write did not change because the person's own value
            stands on them (stamped person); read the item for what landed.
        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
        - item
        - updated_fields
        - previous_values
        - 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.