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

# UndoLeadNextActionAPI takes back an approval that has not been carried out and
returns the


> decision to a person. Approving sends nothing: a decision waits in \`approved\` for the delivery step, and this is the window to change one's mind. Undo and delivery claim the row atomically, so whichever runs first wins, and an action already gone out answers FailedPrecondition. There is deliberately no MCP tool, as with the hold and close. A scoped API key is refused.




## OpenAPI

````yaml /api/openapi.json post /v1/datasets/{datasetSlug}/leads/{leadRef}/next-actions/undo
openapi: 3.0.0
info:
  title: Erdo API
  description: >-
    Erdo's REST API: query and write datasets, run agents, manage threads,
    integrations, pages, evals, workstreams, experiments, and bounded outreach.
    Authenticate with a Bearer API key (erdo_api_...) or scoped token
    (erdo_token_...).
  version: '2026-11-21'
servers:
  - url: https://api.erdo.ai
    description: Production
security:
  - bearerAuth: []
paths:
  /v1/datasets/{datasetSlug}/leads/{leadRef}/next-actions/undo:
    post:
      summary: >
        UndoLeadNextActionAPI takes back an approval that has not been carried
        out and

        returns the
      description: >
        decision to a person. Approving sends nothing: a decision waits in
        \`approved\` for the delivery step, and this is the window to change
        one's mind. Undo and delivery claim the row atomically, so whichever
        runs first wins, and an action already gone out answers
        FailedPrecondition. There is deliberately no MCP tool, as with the hold
        and close. A scoped API key is refused.
      operationId: POST:mcp.UndoLeadNextActionAPI
      parameters:
        - allowEmptyValue: true
          explode: false
          in: path
          name: datasetSlug
          required: true
          schema:
            type: string
          style: simple
        - allowEmptyValue: true
          explode: false
          in: path
          name: leadRef
          required: true
          schema:
            type: string
          style: simple
      requestBody:
        content:
          application/json:
            schema:
              properties:
                action_id:
                  title: >
                    ActionID names the exact decision to take back, as the list
                    and history

                    endpoints report it. Omit to take back the lead's current
                    decision.
                  type: string
                note:
                  title: >
                    Note says why, in the desk's words. It is carried onto the
                    refiled card. At most

                    2000 characters.
                  type: string
                undone_by_external_ref:
                  title: >
                    UndoneByExternalRef is YOUR OWN handle for the person taking
                    the approval back.

                    It is a separate field from the one a decision carries
                    because taking an

                    approval back is a second act by a second person, and the
                    decision keeps both.

                    Stored verbatim, never interpreted. ATTRIBUTION, NEVER
                    AUTHENTICATION — see

                    decided_by_external_ref on the record endpoint. At most 200
                    characters.
                  type: string
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  card_refiled:
                    description: >
                      now. False means the approval is undone — the action will
                      not be carried out — but the new card has still to be
                      filed, which the next sweep does.
                    title: >
                      CardRefiled says whether the action is in front of a
                      person again right
                    type: boolean
                  next_action:
                    $ref: '#/components/schemas/leadaction.NextAction'
                  undone_at:
                    format: date-time
                    title: |
                      UndoneAt is when they took it back.
                    type: string
                  undone_by:
                    title: |
                      UndoneBy is the person who took the approval back.
                    type: string
                type: object
          description: Success response
        default:
          $ref: '#/components/responses/APIError'
components:
  schemas:
    leadaction.NextAction:
      properties:
        accompanying_email:
          allOf:
            - $ref: '#/components/schemas/leadaction.AccompanyingEmailState'
          description: >
            its gated action. Null on every decision that carries none — which
            is every email, wait, close and handoff, and every decision written
            before accompanying emails existed.
          title: >
            AccompanyingEmail is the email this decision sent, or still owes,
            beside
        action_input:
          type: object
        action_kind:
          type: string
        approval_request_id:
          type: string
        call_outcome:
          allOf:
            - $ref: '#/components/schemas/leadaction.CallOutcome'
          description: >
            ring-out — read from the call record ExecutionRef names. A call
            decision is filed before anybody knows whether it will be answered,
            so nothing on the decision itself can say; without this a card read
            "called" beside the lead's "never answered us" from decision time,
            which is the opposite of what happened when they picked up. Null on
            everything but a call that was placed, and when the call record
            could not be read.
          title: |
            CallOutcome is how a call this decision placed ended — answered, a
        canonical_lead_id:
          type: string
        created_by:
          type: string
        dataset_id:
          type: string
        decided_at:
          format: date-time
          type: string
        decided_by:
          type: string
        decided_by_external_ref:
          description: >
            person who decided this action and the person who took it back:
            opaque strings Erdo stores verbatim and never interprets. An app on
            \`/v1\` authenticates a whole team with ONE organization API key, so
            DecidedBy is the same Erdo account for every decision; only the
            caller can say which of its users acted.


            Attribution, never authentication. Anything holding the key can
            write any value here, so Erdo must never branch on it, authorize by
            it or resolve it against an Erdo identity, and it must never be
            presented as proof of who acted. Empty means the caller offered no
            name.
          title: >
            DecidedByExternalRef and UndoneByExternalRef are the CALLING
            PRODUCT's own

            handles for the
          type: string
        delivery_failure:
          allOf:
            - $ref: '#/components/schemas/leadaction.DeliveryFailure'
          description: >
            sent — status stays executed, execution\_ref names it — and the
            provider then reported it failed or undelivered. Read from messaging
            by execution\_ref when the list is read (attachDeliveryFailures),
            never stored here. Null otherwise.
          title: >
            DeliveryFailure is set when this decision's text or WhatsApp message
            was
        due_at:
          format: date-time
          type: string
        error:
          type: string
        evaluated_at:
          format: date-time
          type: string
        executed_at:
          format: date-time
          type: string
        execution_ref:
          type: string
        facts:
          $ref: '#/components/schemas/leadaction.LeadFacts'
        handoff_alert:
          allOf:
            - $ref: '#/components/schemas/leadaction.HandoffAlertState'
          description: >
            for every decision that owes none: non-handoffs, handoffs filed
            while the playbook named nobody to tell, and decisions written
            before migration 012.


            OPERATOR-ONLY, and the one field on this struct that is: it
            describes Erdo emailing the development's staff, not anything done
            about a LEAD. A surface serving a client audience must neither list
            it nor offer its ref to the email viewer.
          title: >
            HandoffAlert is the email that told the development's own desk this
            handoff is

            waiting. Null
        id:
          type: string
        lead_reference:
          type: string
        mode:
          type: string
        model:
          type: string
        playbook_revision:
          format: int64
          type: integer
        policy_digest:
          description: >
            is what says whether the decision is stale — not the revision
            number. The revision bumps on every save, so a decision at revision
            9 may have been decided under exactly the rules revision 10 carries;
            comparing it with LeadPlaybook.PolicyDigest answers the question the
            revision only hints at. Empty on every decision written before
            digests existed and on one a person recorded by hand. See policy.go
            for the two halves it is made of.
          title: >
            PolicyDigest identifies the playbook this decision was made under,
            and it
          type: string
        priority:
          type: string
        priority_reason:
          type: string
        rationale:
          type: string
        resumed_at:
          description: >
            handed the lead back to the engine (POST .../next-actions/resume).
            The revisit time is set to the same moment, so the engine decides
            for the lead on its next pass. Absent on every decision that was
            never resumed — a hold whose time simply ran out has none.
          format: date-time
          title: >
            ResumedAt is when somebody at the desk ended this hold or close
            early and
          type: string
        resumed_by:
          title: |
            ResumedBy is the Erdo account that resumed it.
          type: string
        resumed_by_external_ref:
          description: >
            who resumed it. Opaque, unverified, stored verbatim — attribution,
            never authority, exactly as DecidedByExternalRef.
          title: >
            ResumedByExternalRef is the calling product's own handle for the
            person
          type: string
        revisit_at:
          format: date-time
          type: string
        rule:
          type: string
        source:
          type: string
        stage:
          type: string
        status:
          type: string
        undone_by_external_ref:
          type: string
      title: |
        NextAction is a stored suggestion as the API returns it.
      type: object
    leadaction.AccompanyingEmailState:
      description: >
        out beside a gated decision: whether it went, when, in what words, and
        why it did not if it did not.


        It joins the row's own columns (the authoritative state) with the draft
        stored in action\_input, so a caller does not have to read two things
        and work out which one is true.
      properties:
        body_markdown:
          type: string
        error:
          title: |
            Error is why it has not gone, in the words a person reads.
          type: string
        execution_ref:
          title: |
            ExecutionRef is the mailer's id for the email that went.
          type: string
        sent_at:
          format: date-time
          type: string
        status:
          title: >
            Status is pending, sending, sent, failed or skipped. See the
            constants.
          type: string
        subject:
          type: string
        to:
          type: string
      title: >
        AccompanyingEmailState is what a surface needs to render the email that
        went
      type: object
    leadaction.CallOutcome:
      properties:
        dial_outcome:
          description: >
            it: answered | voicemail | no\_answer | busy | failed | canceled. It
            is the field to read for "did they pick up": Status reads
            "completed" for a call a voicemail box answered exactly as for one a
            person did. Empty on a call still in flight and on calls recorded
            before agent calls carried one.
          title: >
            DialOutcome is what became of the lead's leg, when the call record
            states
          type: string
        duration_seconds:
          format: int64
          type: integer
        status:
          description: >
            connected — to a person or to a voicemail box, see DialOutcome —
            "no-answer", "busy", "failed" and so on otherwise, and a ringing or
            in-progress status while the call has not ended.
          title: |
            Status is the call record's status: "completed" for a call that
          type: string
      title: >
        CallOutcome is how one placed call ended, in the call record's own
        words.
      type: object
    leadaction.DeliveryFailure:
      description: |
        and could not deliver.
      properties:
        class:
          description: >
            code: recipient (the number cannot be reached on the channel),
            sender (our number cannot deliver right now), message (this message
            could not go) or unknown.
          title: >
            Class is whose problem it was, as the messaging service classified
            the
          type: string
        error_code:
          title: |
            ErrorCode is the provider's code (Twilio's), for looking it up.
          type: string
        failed_at:
          format: date-time
          type: string
      title: >
        DeliveryFailure is what the provider reported about a message the engine
        sent
      type: object
    leadaction.LeadFacts:
      description: >
        read nothing.


        A decision now carries only Language, the language the lead wrote in,
        which is the engine's own reading. What the lead stated is read from the
        lead's details instead. The other fields are filled only on decisions
        made before the engine read details.
      properties:
        bedrooms:
          $ref: '#/components/schemas/leadaction.LeadFact'
        broker:
          $ref: '#/components/schemas/leadaction.LeadFact'
        budget:
          $ref: '#/components/schemas/leadaction.LeadFact'
        financing:
          $ref: '#/components/schemas/leadaction.LeadFact'
        language:
          $ref: '#/components/schemas/leadaction.LeadFact'
        purpose:
          $ref: '#/components/schemas/leadaction.LeadFact'
        timeline:
          $ref: '#/components/schemas/leadaction.LeadFact'
      title: >
        LeadFacts is what an evaluation read about the lead. A nil field means
        it
      type: object
    leadaction.HandoffAlertState:
      description: >
        waiting: whether it went, when, the message to open, and why not if it
        did not. The alert is the only MESSAGE a handoff produces (carrying a
        handoff out records "accepted" and sends nothing), so a surface showing
        what a handoff SENT reads this, not the row's execution ref. It reads
        only the row's own columns because buildHandoffAlert composes the alert
        at send time; the message itself is read back from the email service by
        ExecutionRef.
      properties:
        error:
          description: |
            a person reads.
          title: >
            Error is why it has not gone, or which recipients it missed, in the
            words
          type: string
        execution_ref:
          description: >
            it. One alert is one message per recipient and this is the first
            copy that sent; every copy carries the same words, so it opens what
            the desk read. Empty on an alert that has not gone, and on one sent
            before the id was recorded (migration 013) — in which case there is
            nothing to open and a surface must not pretend otherwise.
          title: >
            ExecutionRef is the email service's id for the alert, which is what
            opens
          type: string
        sent_at:
          format: date-time
          type: string
        status:
          description: |
            constants in handoff\_alert.go.
          title: |
            Status is pending, sending, sent or failed. See the HandoffAlert*
          type: string
      title: >
        HandoffAlertState is what a surface needs to render the alert that told
        the desk

        a handoff is
      type: object
    leadaction.LeadFact:
      description: |
        read it from, so a person can check the reading against the row.
      properties:
        source_column:
          type: string
        value:
          type: string
      title: >
        LeadFact is one thing the evaluation read about the lead and the column
        it
      type: object
  responses:
    APIError:
      content:
        application/json:
          schema:
            externalDocs:
              url: https://pkg.go.dev/encore.dev/beta/errs#Error
            properties:
              code:
                description: Error code
                example: not_found
                externalDocs:
                  url: https://pkg.go.dev/encore.dev/beta/errs#ErrCode
                type: string
              details:
                description: Error details
                type: object
              message:
                description: Error message
                type: string
            title: APIError
            type: object
      description: Error response
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An Erdo API key (erdo_api_...) or scoped token (erdo_token_...).

````

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