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

# RecordLeadNextActionAPI records a person's hold, close or start on one lead.
A hold or close


> replaces the lead's open suggestion and withdraws any card it filed; a start has the follow-up engine work the lead now, and with reset starts it over. There is deliberately no MCP tool: it is the sales desk's call about a person it is talking to. A scoped API key is refused.




## OpenAPI

````yaml /api/openapi.json post /v1/datasets/{datasetSlug}/leads/{leadRef}/next-actions
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:
    post:
      summary: >
        RecordLeadNextActionAPI records a person's hold, close or start on one
        lead.

        A hold or close
      description: >
        replaces the lead's open suggestion and withdraws any card it filed; a
        start has the follow-up engine work the lead now, and with reset starts
        it over. There is deliberately no MCP tool: it is the sales desk's call
        about a person it is talking to. A scoped API key is refused.
      operationId: POST:mcp.RecordLeadNextActionAPI
      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:
                decided_by_external_ref:
                  title: >
                    DecidedByExternalRef is YOUR OWN handle for the person who
                    held or closed

                    this lead — a member id, a slug, whatever your records use.
                    Erdo stores it

                    verbatim beside the account your API key belongs to, and
                    never interprets it.

                    It exists because one organization API key usually serves a
                    whole sales desk,

                    so without it every hold and close is attributed to the
                    key's owner.

                    ATTRIBUTION, NEVER AUTHENTICATION: anything holding the key
                    can send any value,

                    Erdo verifies nothing, and it must never be presented as
                    proof of who acted.

                    At most 200 characters.
                  type: string
                kind:
                  title: >
                    Kind is hold (the desk is handling this lead), close (stop
                    working it) or

                    start (have the follow-up engine work this lead). The engine
                    only reaches leads

                    captured after it was switched on, and never test traffic,
                    by itself; start is

                    how a person brings one of those in. Start answers
                    FailedPrecondition when the

                    engine is switched off, or when it already has the lead and
                    reset is not set.

                    Required.
                  type: string
                note:
                  title: |
                    Note says why, in the desk's words. At most 2000 characters.
                  type: string
                reset:
                  title: >
                    Reset, with kind start, starts the lead over: open decisions
                    are withdrawn and

                    the engine reads the lead afresh from now — its earlier
                    decisions, the desk's

                    refusals, the timeline and anything the lead said in a
                    conversation before now

                    are not read, and the lead is treated as just captured.
                    Nothing is deleted,

                    and opt-outs (STOP, do-not-call) still apply.
                  type: boolean
                until:
                  format: date-time
                  title: >
                    Until ends a hold, RFC 3339. Defaults to seven days; at most
                    180 days. The lead

                    is also reopened when it writes back.
                  type: string
              type: object
              required:
                - kind
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  accompanying_email:
                    $ref: '#/components/schemas/leadaction.AccompanyingEmailState'
                  action_input:
                    type: object
                  action_kind:
                    type: string
                  approval_request_id:
                    type: string
                  call_outcome:
                    $ref: '#/components/schemas/leadaction.CallOutcome'
                  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:
                    $ref: '#/components/schemas/leadaction.DeliveryFailure'
                  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:
                    $ref: '#/components/schemas/leadaction.HandoffAlertState'
                  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
                type: object
          description: Success response
        default:
          $ref: '#/components/responses/APIError'
components:
  schemas:
    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.