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

# Edit a pending approval before deciding (your own key)

> Changes what a pending approval will send, as the app's Approvals page does before you approve: an email's subject or HTML body (`messages`, for one recipient's message or every message), recipients taken off (`exclude`) or put back (`include`) and attachments removed (`remove_attachments`, ids from GET); a custom step's `message`, `data` or table `rows`. The same checks as the app: an email keeps at least one recipient (reject it instead), and an address can't be both sent to and taken off (422 with the app's code). Returns the approval as edited, its HTML included. Only a person edits, with their own key, an approval assigned to them (or any, when they build in Agent Studio); 409 once it is decided. The run sends what was saved when it is approved. Over MCP: first show the person what will be sent (GET the approval: recipients, subject, the email as text) with its `app_url`, where the email shows rendered, and act only on their explicit go-ahead for these approvals. Every approval carries `app_url`, its page in the app, where an email shows rendered as it will be sent: end any answer about an approval with that link so the person can review it there.



## OpenAPI

````yaml /api/statisfy-api.openapi.json patch /v1/approvals/{approval_id}
openapi: 3.1.0
info:
  description: >-
    The agent-first Statisfy API. Authenticate with an API key (`Authorization:
    Bearer stfy_live_…`), then call `GET /v1/meta/capabilities` to discover
    every operation and its schemas.
  title: Statisfy API
  version: 1.0.0
servers:
  - url: https://api.statisfy.com
    description: Production
security: []
paths:
  /v1/approvals/{approval_id}:
    patch:
      tags:
        - approvals
      summary: Edit a pending approval before deciding (your own key)
      description: >-
        Changes what a pending approval will send, as the app's Approvals page
        does before you approve: an email's subject or HTML body (`messages`,
        for one recipient's message or every message), recipients taken off
        (`exclude`) or put back (`include`) and attachments removed
        (`remove_attachments`, ids from GET); a custom step's `message`, `data`
        or table `rows`. The same checks as the app: an email keeps at least one
        recipient (reject it instead), and an address can't be both sent to and
        taken off (422 with the app's code). Returns the approval as edited, its
        HTML included. Only a person edits, with their own key, an approval
        assigned to them (or any, when they build in Agent Studio); 409 once it
        is decided. The run sends what was saved when it is approved. Over MCP:
        first show the person what will be sent (GET the approval: recipients,
        subject, the email as text) with its `app_url`, where the email shows
        rendered, and act only on their explicit go-ahead for these approvals.
        Every approval carries `app_url`, its page in the app, where an email
        shows rendered as it will be sent: end any answer about an approval with
        that link so the person can review it there.
      operationId: approvals_update
      parameters:
        - description: The approval's id, from GET /v1/approvals
          in: path
          name: approval_id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                data:
                  anyOf:
                    - additionalProperties: true
                      type: object
                    - type: 'null'
                  default: null
                  description: A custom approval step's new data
                  title: Data
                exclude:
                  anyOf:
                    - items:
                        maxLength: 320
                        minLength: 3
                        type: string
                      maxItems: 500
                      type: array
                    - type: 'null'
                  default: null
                  description: Recipients to take off the email (To, Cc or Bcc)
                  title: Exclude
                include:
                  anyOf:
                    - items:
                        maxLength: 320
                        minLength: 3
                        type: string
                      maxItems: 500
                      type: array
                    - type: 'null'
                  default: null
                  description: Recipients taken off earlier to put back
                  title: Include
                message:
                  anyOf:
                    - maxLength: 100000
                      type: string
                    - type: 'null'
                  default: null
                  description: A custom approval step's new message
                  title: Message
                messages:
                  anyOf:
                    - items:
                        $ref: '#/components/schemas/MessageEdit'
                      maxItems: 100
                      type: array
                    - type: 'null'
                  default: null
                  description: An email's new subject or body, per recipient or for all
                  title: Messages
                remove_attachments:
                  anyOf:
                    - items:
                        type: string
                      maxItems: 50
                      type: array
                    - type: 'null'
                  default: null
                  description: Attachment ids to take off the email
                  title: Remove Attachments
                rows:
                  anyOf:
                    - items:
                        additionalProperties: true
                        type: object
                      maxItems: 5000
                      type: array
                    - type: 'null'
                  default: null
                  description: A custom approval step's new table rows
                  title: Rows
              type: object
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovalDetail'
          description: Successful Response
      security:
        - HTTPBearer: []
components:
  schemas:
    MessageEdit:
      additionalProperties: false
      properties:
        html:
          anyOf:
            - maxLength: 1000000
              type: string
            - type: 'null'
          default: null
          description: The new HTML body (read the current one with `include_html=true`)
          title: Html
        subject:
          anyOf:
            - maxLength: 998
              type: string
            - type: 'null'
          default: null
          title: Subject
        to:
          anyOf:
            - maxLength: 320
              minLength: 3
              type: string
            - type: 'null'
          default: null
          description: >-
            The recipient whose message to change (an email sent to each
            recipient separately); omit to change every message
          title: To
      title: MessageEdit
      type: object
    ApprovalDetail:
      properties:
        app_url:
          description: >-
            The approval on the app's Approvals page, where an email shows as it
            will be sent. When you tell someone about this approval, end your
            answer with this link so they can review it there
          title: App Url
          type: string
        approved_by:
          anyOf:
            - $ref: '#/components/schemas/ApprovalPerson'
            - type: 'null'
        approver:
          anyOf:
            - $ref: '#/components/schemas/ApprovalPerson'
            - type: 'null'
          description: The user it is assigned to
        content:
          anyOf:
            - $ref: '#/components/schemas/ApprovalContent'
            - type: 'null'
          description: What approving lets through; none for a survey
        decided_at:
          anyOf:
            - type: string
            - type: 'null'
          description: When it was approved or rejected
          title: Decided At
        flow:
          $ref: '#/components/schemas/ApprovalFlow'
        id:
          title: Id
          type: string
        kind:
          anyOf:
            - enum:
                - email
                - survey
                - basic
              type: string
            - type: 'null'
          description: >-
            What the step asks to let through: an email, a survey, or a custom
            approval
          title: Kind
        playground:
          description: >-
            A run started from the flow editor's Playground: deciding it only
            records the decision, and the run continues (or stops) only in the
            editor that started it, if it is still open
          title: Playground
          type: boolean
        recipients:
          description: Who an email or survey goes to
          items:
            type: string
          title: Recipients
          type: array
        record:
          anyOf:
            - $ref: '#/components/schemas/ApprovalRecord'
            - type: 'null'
          description: The record the run acted on
        rejected_by:
          anyOf:
            - $ref: '#/components/schemas/ApprovalPerson'
            - type: 'null'
        requested_at:
          anyOf:
            - type: string
            - type: 'null'
          description: When the run paused for it
          title: Requested At
        run_id:
          anyOf:
            - type: string
            - type: 'null'
          description: The flow run waiting on it; null for a Playground run (`playground`)
          title: Run Id
        status:
          enum:
            - pending
            - approved
            - rejected
          title: Status
          type: string
        step_id:
          description: The approval step in the flow
          title: Step Id
          type: string
        title:
          anyOf:
            - type: string
            - type: 'null'
          description: An email's subject, or the step's own title
          title: Title
      required:
        - id
        - status
        - kind
        - title
        - recipients
        - flow
        - run_id
        - playground
        - step_id
        - record
        - approver
        - approved_by
        - rejected_by
        - requested_at
        - decided_at
        - app_url
        - content
      title: ApprovalDetail
      type: object
    ApprovalPerson:
      properties:
        id:
          description: A user's id, as GET /v1/objects/user/records gives it
          title: Id
          type: string
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
      required:
        - id
        - name
      title: ApprovalPerson
      type: object
    ApprovalContent:
      properties:
        basic:
          anyOf:
            - $ref: '#/components/schemas/ApprovalBasic'
            - type: 'null'
        email:
          anyOf:
            - $ref: '#/components/schemas/ApprovalEmail'
            - type: 'null'
      title: ApprovalContent
      type: object
    ApprovalFlow:
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
      required:
        - id
        - name
      title: ApprovalFlow
      type: object
    ApprovalRecord:
      properties:
        id:
          title: Id
          type: string
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        type:
          description: >-
            The kind of record the run acted on: account, contact, opportunity,
            task, activity…
          title: Type
          type: string
      required:
        - type
        - id
        - name
      title: ApprovalRecord
      type: object
    ApprovalBasic:
      properties:
        data:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Data
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
        rows:
          items:
            additionalProperties: true
            type: object
          title: Rows
          type: array
      required:
        - message
        - data
        - rows
      title: ApprovalBasic
      type: object
    ApprovalEmail:
      properties:
        attachments:
          items:
            $ref: '#/components/schemas/ApprovalAttachment'
          title: Attachments
          type: array
        excluded:
          description: Recipients the approver took off
          items:
            $ref: '#/components/schemas/ApprovalRecipient'
          title: Excluded
          type: array
        messages:
          description: >-
            The emails approving sends: one per recipient, or one to every
            recipient
          items:
            $ref: '#/components/schemas/ApprovalEmailMessage'
          title: Messages
          type: array
        sender:
          $ref: '#/components/schemas/ApprovalSender'
      required:
        - sender
        - messages
        - excluded
        - attachments
      title: ApprovalEmail
      type: object
    ApprovalAttachment:
      properties:
        filename:
          anyOf:
            - type: string
            - type: 'null'
          title: Filename
        id:
          description: Read the file with GET /v1/approvals/{approval_id}/attachments/{id}
          title: Id
          type: string
        mime_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Mime Type
        size_bytes:
          anyOf:
            - type: integer
            - type: 'null'
          title: Size Bytes
      required:
        - id
        - filename
        - mime_type
        - size_bytes
      title: ApprovalAttachment
      type: object
    ApprovalRecipient:
      properties:
        contact_id:
          anyOf:
            - type: string
            - type: 'null'
          description: The contact, when the address is one
          title: Contact Id
        email:
          title: Email
          type: string
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
      required:
        - email
        - name
        - contact_id
      title: ApprovalRecipient
      type: object
    ApprovalEmailMessage:
      properties:
        bcc:
          items:
            type: string
          title: Bcc
          type: array
        cc:
          items:
            type: string
          title: Cc
          type: array
        edited:
          description: The approver changed the subject or body
          title: Edited
          type: boolean
        html:
          anyOf:
            - type: string
            - type: 'null'
          description: The HTML body, with `include_html=true`
          title: Html
        subject:
          anyOf:
            - type: string
            - type: 'null'
          title: Subject
        text:
          anyOf:
            - type: string
            - type: 'null'
          description: 'The body as plain text (the app''s page shows it rendered: `app_url`)'
          title: Text
        to:
          items:
            $ref: '#/components/schemas/ApprovalRecipient'
          title: To
          type: array
      required:
        - to
        - cc
        - bcc
        - subject
        - text
        - edited
      title: ApprovalEmailMessage
      type: object
    ApprovalSender:
      properties:
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
      required:
        - name
        - email
      title: ApprovalSender
      type: object
  securitySchemes:
    HTTPBearer:
      scheme: bearer
      type: http
      description: >-
        An API key, sent as `Authorization: Bearer stfy_live_…`. See
        [Authentication](/rest-api/authentication) for how to get one and which
        scopes it needs.

````

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