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

# MergeLeadsAPI makes two lead identities one lead: the absorbed identity points
at the survivor,


> its contact evidence moves across, and the two dataset rows become one. There is deliberately no MCP tool: it is not reversible in practice and settles captures where the evidence contradicts itself, so a person decides holding both leads' evidence. A scoped API key is refused, since one lead's holder must never be able to fold another lead into it.




## OpenAPI

````yaml /api/openapi.json post /v1/datasets/{datasetSlug}/leads/{leadRef}/merge
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}/merge:
    post:
      summary: >
        MergeLeadsAPI makes two lead identities one lead: the absorbed identity
        points

        at the survivor,
      description: >
        its contact evidence moves across, and the two dataset rows become one.
        There is deliberately no MCP tool: it is not reversible in practice and
        settles captures where the evidence contradicts itself, so a person
        decides holding both leads' evidence. A scoped API key is refused, since
        one lead's holder must never be able to fold another lead into it.
      operationId: POST:mcp.MergeLeadsAPI
      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:
                absorb_lead_id:
                  title: >
                    AbsorbLeadID names the lead that stops being its own lead,
                    as a

                    canonical_lead_id UUID or a 22-character lead reference.
                    Required.
                  type: string
                overwrite_columns:
                  items:
                    type: string
                  title: >
                    OverwriteColumns names the columns where the absorbed lead's
                    value wins over one

                    the survivor already holds; everything else only fills a
                    blank.
                  type: array
              type: object
              required:
                - absorb_lead_id
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  absorbed_lead_id:
                    description: >
                      existing so the capture receipts referencing it stay
                      accurate.
                    title: >
                      AbsorbedLeadID is the identity that now points at the
                      survivor. It keeps
                    type: string
                  aliases_moved:
                    format: int64
                    type: integer
                  details_moved:
                    description: |
                      survivor.
                    format: int64
                    title: >
                      DetailsMoved is how many things the absorbed lead told us
                      moved onto the
                    type: integer
                  lead:
                    $ref: '#/components/schemas/dataset.CanonicalLead'
                  rows_combined:
                    format: int64
                    type: integer
                  state:
                    description: >
                      the two were already one lead — which is also what a retry
                      of an uncertain merge answers.
                    title: >
                      State is "merged" for the call that performed it and
                      "already_merged" when
                    type: string
                type: object
          description: Success response
        default:
          $ref: '#/components/responses/APIError'
components:
  schemas:
    dataset.CanonicalLead:
      properties:
        absorbed_lead_ids:
          items:
            type: string
          title: >
            AbsorbedLeadIDs are the identities merged INTO this one, most recent
            first.
          type: array
        aliases:
          items:
            $ref: '#/components/schemas/dataset.CanonicalLeadAlias'
          type: array
        canonical_lead_id:
          title: |
            CanonicalLeadID is the permanent identity, as a UUID.
          type: string
        captures:
          items:
            $ref: '#/components/schemas/dataset.CanonicalLeadCapture'
          type: array
        context_columns:
          description: >
            None of these columns is something the lead said: each is marked by
            the dataset's contract as bookkeeping, attribution, or a column the
            platform stamps itself, under whatever name the contract gave it.
          items:
            type: string
          title: >
            ContextColumns lists the row's columns that are never the lead's
            answers.
          type: array
        created_at:
          format: date-time
          type: string
        dataset_id:
          type: string
        dataset_slug:
          type: string
        details:
          description: >
            conversation since — one entry per question, the current answer with
            the earlier ones beneath it. Most recently stated first.
          items:
            $ref: '#/components/schemas/dataset.LeadDetail'
          title: |
            Details are what the lead has told us — on the form and in every
          type: array
        merged_at:
          format: date-time
          type: string
        merged_by:
          type: string
        merged_into:
          description: >
            lead it became. An absorbed identity keeps existing: the capture
            receipts that reference it stay accurate about what happened at the
            time.
          title: >
            MergedIntoReference is set on an identity that was absorbed, and
            names the
          type: string
        merged_into_reference:
          type: string
        reference:
          description: |
            Either form is accepted wherever a lead is addressed.
          title: >
            Reference is the same identity in 22 characters, for a link or an
            SMS.
          type: string
        refused_captures:
          description: >
            because this lead was one of the leads it could not choose between
            (resolution ambiguous or conflict). They name no lead of their own,
            so they are not in Captures; they are what a merge settles.
          items:
            $ref: '#/components/schemas/dataset.CanonicalLeadCapture'
          title: |
            RefusedCaptures are the submissions the resolver would not attribute
          type: array
        requested_lead_id:
          description: >
            CanonicalLeadID when the caller held an id that has since been
            absorbed — which keeps working on purpose, because ids travel in
            capture responses and outbound links.
          title: >
            RequestedLeadID is the identity the caller asked for. It differs
            from
          type: string
        row:
          additionalProperties:
            type: string
          description: >
            which is what an absorbed identity looks like after its values were
            combined into its survivor.
          title: >
            Row is the lead's dataset row. Absent when the identity holds no row
            —
          type: object
        submissions:
          description: >
            than the display list above. HasEvidence is false for a visit
            recorded before the capture stored its own click and time.
          items:
            $ref: '#/components/schemas/dataset.CanonicalLeadSubmission'
          title: >
            Submissions are the accepted visits, oldest first, including ones
            older
          type: array
        submissions_truncated:
          description: |
            not a complete history and must not be uploaded as if it were.
          title: >
            SubmissionsTruncated means the visit list hit the upload cap, so it
            is
          type: boolean
      title: |
        CanonicalLead is everything an operator needs to judge one lead.
      type: object
    dataset.CanonicalLeadAlias:
      properties:
        created_at:
          format: date-time
          type: string
        provenance:
          type: string
        shared:
          description: >
            too, in this dataset or another. A record kept by number or address
            — a text conversation, a consent record — belongs to both leads
            while it is.
          title: >
            Shared reports that another lead in the organization holds this
            value
          type: boolean
        type:
          title: |
            Type is email, phone, legacy_lid, legacy_id or conversion_id.
          type: string
        value:
          title: >
            Value is the normalized form the resolver matches on, not what was
            typed.
          type: string
      title: |
        CanonicalLeadAlias is one piece of contact evidence bound to a lead.
      type: object
    dataset.CanonicalLeadCapture:
      properties:
        candidate_lead_ids:
          description: >
            a resubmission keeps them beside the lead it landed on, a historical
            refused capture the ones it could not choose between. Either of them
            is what a merge is addressed with.
          items:
            type: string
          title: >
            CandidateLeadIDs are the leads the contact evidence named when it
            clashed:
          type: array
        captured_at:
          format: date-time
          title: >
            CapturedAt is when this visit was submitted. CreatedAt is the
            receipt.
          type: string
        conversion_id:
          type: string
        conversion_status:
          type: string
        created_at:
          format: date-time
          type: string
        dismissed:
          type: boolean
        disposition:
          $ref: '#/components/schemas/storage.CanonicalCaptureDisposition'
        email:
          type: string
        evidence:
          $ref: '#/components/schemas/storage.CanonicalCaptureEvidence'
        gbraid:
          type: string
        gclid:
          description: |
            the first of each, so a later visit is only visible here.
          title: >
            Click and contact values are this visit's own. The canonical row
            keeps
          type: string
        id:
          type: string
        is_test:
          type: boolean
        operation_key:
          type: string
        phone:
          type: string
        pipeline_id:
          description: >
            producer was one. A development runs one capture pipeline per page,
            language and variant, so this is what says WHERE the lead came in —
            the dataset row only remembers the most recent page.
          title: >
            PipelineID is the event pipeline that captured the submission, when
            the
          type: string
        producer:
          type: string
        resolution:
          title: >
            Resolution is created, matched, enriched, corrected, ambiguous,
            conflict or

            unresolved.
          type: string
        rows_affected:
          format: int64
          type: integer
        wbraid:
          type: string
      title: |
        CanonicalLeadCapture is one recorded capture against a lead.
      type: object
    dataset.LeadDetail:
      description: |
        earlier one, newest first.
      properties:
        definition:
          title: |
            Definition is the one-sentence question the key answers.
          type: string
        earlier:
          description: |
            lead has said it once.
          items:
            $ref: '#/components/schemas/dataset.LeadDetailObservation'
          title: >
            Earlier are the answers this one replaced, newest first. Empty when
            the
          type: array
        key:
          type: string
        label:
          type: string
        observed_at:
          format: date-time
          type: string
        quote:
          type: string
        source_kind:
          type: string
        source_ref:
          type: string
        value:
          description: >
            Encore's OpenAPI generator drops an embedded struct's fields, so the
            public spec described a detail with no value, and every typed client
            built from it (Maurice's) could not read one.
          title: |
            The current answer, spelled out field by field rather than embedded:
          type: string
      title: |
        LeadDetail is one question a lead answered: the current answer and every
      type: object
    dataset.CanonicalLeadSubmission:
      description: |
        visit's own lead, which stays its order-id namespace after a merge.
      properties:
        canonical_lead_id:
          type: string
        captured_at:
          format: date-time
          type: string
        created_at:
          format: date-time
          type: string
        dismissed:
          type: boolean
        email:
          type: string
        gbraid:
          type: string
        gclid:
          type: string
        has_evidence:
          type: boolean
        id:
          type: string
        is_test:
          type: boolean
        phone:
          type: string
        reference:
          type: string
        resolution:
          type: string
        wbraid:
          type: string
      title: >
        CanonicalLeadSubmission is one accepted visit of a lead. Reference is
        that
      type: object
    storage.CanonicalCaptureDisposition:
      properties:
        action:
          type: string
        actor_id:
          format: uuid
          type: string
        created_at:
          format: date-time
          type: string
        operation_key:
          type: string
        reason:
          type: string
        result_receipt_id:
          format: uuid
          type: string
        snapshot:
          type: string
        target_lead_id:
          format: uuid
          type: string
      type: object
    storage.CanonicalCaptureEvidence:
      properties:
        captured_at:
          format: date-time
          type: string
        execution_id:
          format: uuid
          type: string
        first_touch_columns:
          items:
            type: string
          type: array
        is_test:
          type: boolean
        normalized_capture:
          type: object
          nullable: true
        pipeline_id:
          format: uuid
          type: string
        producer_columns:
          items:
            $ref: '#/components/schemas/storage.DeclaredColumn'
          type: array
        record_form_answers:
          title: >
            RecordFormAnswers preserves the original producer decision; unknown
            history is

            false.
          type: boolean
        trusted_test:
          type: boolean
      type: object
    dataset.LeadDetailObservation:
      properties:
        observed_at:
          format: date-time
          type: string
        quote:
          description: |
            typed.
          title: >
            Quote is the lead's exact words. For a form answer it is the value
            they
          type: string
        source_kind:
          description: |
            email\_reply.
          title: >
            SourceKind is form, phone_call, widget_conversation, sms, whatsapp
            or
          type: string
        source_ref:
          description: >
            or inbound email the value came from — "row" for a form answer read
            from a row written before lead details existed.
          title: >
            SourceRef is the capture receipt, call, widget session, message
            session
          type: string
        value:
          type: string
      title: |
        LeadDetailObservation is one statement of one answer.
      type: object
    storage.DeclaredColumn:
      description: >
        stored contract the write path enforces and consumers read instead of
        probing. Type uses the same vocabulary as ColumnTypeOverrides
        (text|integer|float|date| boolean). Ordinary enforcement validates
        column names and required presence; budget-answer semantic roles
        validate the platform capture fields. General coercion against Type
        remains out of scope.
      properties:
        allowed_values:
          items:
            type: string
          type: array
        currency:
          description: >
            integer minor units (for example USD cents); it is presentation
            metadata.
          title: >
            Currency is an ISO 4217 code (three uppercase letters). Values
            represent
          type: string
        description:
          type: string
        integer:
          type: boolean
        minimum:
          type: number
        name:
          type: string
        required:
          type: boolean
        semantic_role:
          description: >
            field, or a rendering classification (internal, attribution,
            source\_url, source\_quote, source\_seen\_at). App-specific value
            rules belong in declared constraints. Consumers match the role
            instead of guessing column names.
          title: >
            SemanticRole identifies the canonical lead key, a platform
            budget-answer
          type: string
        type:
          type: string
      title: >
        DeclaredColumn is one column in a table-class dataset's declared schema
        — the
      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.