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

# Write playtable field value

> Write a cell by natural key (column sid + row sid), not by cell sid: the way to fill an EMPTY cell, which has no row and no sid until written (update_playtable_field_value needs one). Same semantics as update: the cell finalizes as done (value null = a manual clear), error_msg clears, a formula cell is pinned, the first write over a system value snapshots it for reset. Works on an existing cell too. 404 on another team's column, 422 when the row is outside its table, 409 while the cell runs.

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



## OpenAPI

````yaml /api-reference/playtables/openapi.yaml post /api/playtable-field-values/write
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/playtable-field-values/write:
    post:
      tags:
        - playtable_field_values
      summary: Write playtable field value
      description: >-
        Write a cell by natural key (column sid + row sid), not by cell sid: the
        way to fill an EMPTY cell, which has no row and no sid until written
        (update_playtable_field_value needs one). Same semantics as update: the
        cell finalizes as done (value null = a manual clear), error_msg clears,
        a formula cell is pinned, the first write over a system value snapshots
        it for reset. Works on an existing cell too. 404 on another team's
        column, 422 when the row is outside its table, 409 while the cell runs.


        Contract:

        - MCP tool `write_playtable_field_value`, registry package
        `mcp.playtables/playtable_field_values`, mount `playtables.columns`.

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

        - Flags: none.
      operationId: write_playtable_field_value
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WritePlaytableFieldValueRequest'
      responses:
        '200':
          description: '`update` success envelope.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WritePlaytableFieldValueResponse'
        4XX:
          $ref: '#/components/responses/McpClientError'
        5XX:
          $ref: '#/components/responses/McpServerError'
components:
  schemas:
    WritePlaytableFieldValueRequest:
      type: object
      description: Request body of `write_playtable_field_value`.
      properties:
        playtable_field_sid:
          type: string
          minLength: 18
          maxLength: 18
          pattern: ^pt_fd_
          description: >-
            The column (pt_fd_…); the table and the object type derive from it.
            Unknown or another team's: 404.
        object_sid:
          type: string
          minLength: 18
          maxLength: 18
          pattern: ^cr_(pp|co)_
          description: >-
            The row: a person (cr_pp_…) or a company (cr_co_…) that belongs to
            the column's table (422 otherwise).
        value:
          type: string
          nullable: true
          maxLength: 65535
          description: >-
            The value to write, canonical string (max 65535). The key is
            required: null clears the cell, which stays done with value null,
            never empty.
      required:
        - playtable_field_sid
        - object_sid
        - value
    WritePlaytableFieldValueResponse:
      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
            object_type:
              type: string
              enum:
                - people
                - company
            object_sid:
              type: string
            playtable_field_sid:
              type: string
            value:
              type: string
              nullable: true
            is_value_from_formula:
              type: boolean
            original_value:
              type: string
              nullable: true
              description: >-
                The system-produced value the FIRST manual overwrite
                snapshotted, what reset restores; null unless is_overwritten.
                The list surface nulls it like meta: read it on get, update,
                write and reset.
            is_overwritten:
              type: boolean
              description: >-
                The current value is a manual write over a system-produced one:
                the edited marker, and the one state reset accepts.
            is_not_valid:
              type: boolean
              description: >-
                A manually written value that could not be converted to the
                column's type (text in a number column), stored raw and flagged;
                system writers coerce or null instead.
            status:
              type: string
              enum:
                - empty
                - queued
                - running
                - done
                - error
                - run_condition_not_met
            cost:
              type: number
              nullable: true
            provider_sid:
              type: string
              nullable: true
            meta:
              type: object
              nullable: true
              properties:
                run_sid:
                  type: string
                  nullable: true
                steps:
                  type: array
                  items:
                    type: object
                    properties:
                      step_index:
                        type: number
                      tool_sid:
                        type: string
                      status:
                        type: string
                        enum:
                          - success
                          - failed
                          - skipped
                      cost:
                        type: number
                      error:
                        type: string
                        nullable: true
                      finished_at:
                        type: string
                        nullable: true
                      verdict:
                        type: string
                        nullable: true
                      email:
                        type: string
                        nullable: true
                    required:
                      - step_index
                      - tool_sid
                      - status
                      - cost
                      - error
                      - finished_at
              required:
                - run_sid
                - steps
            error_msg:
              type: string
              nullable: true
            finished_at:
              type: string
              nullable: true
            created_at:
              type: string
            updated_at:
              type: string
          required:
            - sid
            - team_sid
            - playtable_sid
            - object_type
            - object_sid
            - playtable_field_sid
            - value
            - is_value_from_formula
            - original_value
            - is_overwritten
            - is_not_valid
            - status
            - cost
            - provider_sid
            - meta
            - error_msg
            - finished_at
            - created_at
            - updated_at
        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.