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

# Declares or replaces a lead source: a sheet, webhook or import source by name,


> or a LinkedIn or Meta ad account's lead forms by provider and account\_id. dry\_run checks the declaration and saves nothing. Mirrors erdo\_save\_lead\_source.




## OpenAPI

````yaml /api/openapi.json put /v1/provider-lead-sources
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/provider-lead-sources:
    put:
      summary: >
        Declares or replaces a lead source: a sheet, webhook or import source by
        name,
      description: >
        or a LinkedIn or Meta ad account's lead forms by provider and
        account\_id. dry\_run checks the declaration and saves nothing. Mirrors
        erdo\_save\_lead\_source.
      operationId: PUT:mcp.SetProviderLeadSourceAPI
      requestBody:
        content:
          application/json:
            schema:
              properties:
                account_id:
                  description: |
                    written with or without "act\_".
                  title: >
                    account_id is the provider's numeric ad account id; a Meta
                    account may be
                  type: string
                budget:
                  $ref: '#/components/schemas/eventpipeline.LeadSourceBudget'
                connection_id:
                  description: >
                    (integration id) for the provider; Pipedream connector
                    account ids are refused.
                  title: >
                    connection_id is the id of this organization's connected
                    integration
                  type: string
                create_only:
                  description: >
                    import source with this name exists, so adding a source
                    never replaces one. Refused for an ad platform declaration,
                    which is keyed by its ad account.
                  title: >
                    create_only refuses the save (already_exists) when a sheet,
                    webhook or
                  type: boolean
                dataset:
                  title: >
                    dataset is the slug of a lead dataset with lead identity
                    turned on.
                  type: string
                dry_run:
                  description: >
                    nothing. For a sheet it reads the tab; for a webhook it maps
                    sample; for a LinkedIn declaration it proves the dataset,
                    the connection's Lead Sync grant and every form's owner; for
                    a Meta declaration it proves the dataset, the connection's
                    leads\_retrieval grant on the ad account, every form's Page
                    and that each form's leads can be read.
                  title: >
                    dry_run checks the declaration and returns what it would
                    write, saving
                  type: boolean
                enabled:
                  description: >
                    Saving an existing sheet, webhook or import source without
                    enabled keeps its current state, so rotating a paused
                    webhook's secret leaves it paused.
                  title: >
                    enabled defaults to true. False keeps the declaration but
                    stops reading it.
                  type: boolean
                forms:
                  description: >
                    belong to account\_id; a Meta Instant Form must be on a Page
                    account\_id promotes, and only leads from that account's ads
                    are written.
                  items:
                    type: string
                  title: >
                    forms are the lead form ids to write responses from. A
                    LinkedIn form must
                  type: array
                if_updated_at:
                  description: >
                    read. The save is refused (aborted) when the source was
                    saved since, so two people editing one source cannot
                    overwrite each other's change. Refused for an ad platform
                    declaration.
                  title: >
                    if_updated_at is a sheet, webhook or import source's
                    updated_at as last
                  type: string
                mapping:
                  $ref: '#/components/schemas/eventpipeline.LeadSourceMapping'
                name:
                  description: >
                    digits and hyphens, unique in the organization. Saving the
                    same name again replaces that source.
                  title: >
                    name names a google_sheets, webhook or import source:
                    lower-case letters,
                  type: string
                provider:
                  description: >
                    "meta\_ads" (Meta Instant Forms), "google\_sheets",
                    "webhook" or "import".
                  title: >
                    provider is the kind of source: "linkedin_ads" (LinkedIn
                    Lead Gen Forms),
                  type: string
                rotate_secret:
                  description: |
                    working at once. Refused for any other provider.
                  title: >
                    rotate_secret issues a webhook source a new secret; the old
                    one stops
                  type: boolean
                sample:
                  description: >
                    ad platform declaration, which reads its fields from the
                    lead form.
                  title: >
                    sample is a webhook body to preview the mapping against.
                    Refused for an
                  type: object
                  nullable: true
                sheet_url:
                  description: >
                    (including #gid=). The tab must be open to anyone with the
                    link.
                  title: >
                    sheet_url is a google_sheets source's tab, as its address in
                    the browser
                  type: string
                suggest_columns:
                  description: >
                    wants the sheet's fields matched to (is\_broker, budget,
                    timeline, phone, name), each with what it records. The
                    preview suggests a field only for one of these, and leaves
                    every other field without a suggestion. Without it the lead
                    dataset's own columns are used.
                  items:
                    $ref: '#/components/schemas/eventpipeline.LeadSourceSuggestColumn'
                  title: >
                    suggest_columns, on a sheet's dry run, are the lead columns
                    the caller
                  type: array
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  account_id:
                    description: >
                      "act\_" prefix). Only responses this account owns are ever
                      written.
                    title: >
                      account_id is the provider's ad account id (a Meta account
                      without its
                    type: string
                  budget:
                    $ref: '#/components/schemas/eventpipeline.LeadSourceBudget'
                  connection_id:
                    description: |
                      responses are read through.
                    title: >
                      connection_id is the organization's connected integration
                      account the
                    type: string
                  created_at:
                    title: >
                      created_at is when the declaration was first saved (RFC
                      3339).
                    type: string
                  dataset:
                    title: >
                      dataset is the slug of the lead dataset responses are
                      written into.
                    type: string
                  enabled:
                    title: |
                      enabled is whether the platform is reading this source.
                    type: boolean
                  forms:
                    items:
                      type: string
                    title: |
                      forms are the lead form ids whose responses are written.
                    type: array
                  id:
                    title: >
                      id is the declaration's id. A webhook source's address
                      carries it.
                    type: string
                  last_delivery_at:
                    description: |
                      including one that matched an existing lead (RFC 3339).
                    title: >
                      last_delivery_at is when the source last received a
                      non-history response,
                    type: string
                  last_error:
                    title: >
                      last_error is why the last read did not finish, or empty
                      when it did.
                    type: string
                  last_run_at:
                    description: |
                      empty when it never has.
                    title: >
                      last_run_at is when the platform last read this source
                      (RFC 3339), or
                    type: string
                  mapping:
                    $ref: '#/components/schemas/eventpipeline.LeadSourceMapping'
                  name:
                    description: >
                      ("brickell-meta-forms-spreadsheet"); empty for an ad
                      platform declaration.
                    title: >
                      name is how people refer to a sheet, webhook or import
                      source
                    type: string
                  preview:
                    $ref: '#/components/schemas/eventpipeline.LeadSourcePreview'
                  provider:
                    description: |
                      "google\_sheets", "webhook" or "import".
                    title: >
                      provider is the kind of source: "linkedin_ads",
                      "meta_ads",
                    type: string
                  read_via:
                    description: >
                      sheet's open link. It stops working if link sharing is
                      turned off.
                    title: >
                      read_via says how a sheet source reads its tab: "link",
                      through the
                    type: string
                  sheet_url:
                    title: |
                      sheet_url is a sheet source's tab.
                    type: string
                  synced_through:
                    description: >
                      handled through (RFC 3339), or empty before the first
                      complete sync.
                    title: >
                      synced_through is the submission time every earlier
                      response has been
                    type: string
                  updated_at:
                    description: >
                      microsecond). For a sheet, webhook or import source, send
                      it back as if\_updated\_at to save only an unchanged
                      source. Saving a LinkedIn or Meta declaration refuses
                      if\_updated\_at; deleting one still accepts it and deletes
                      only an unchanged declaration.
                    title: >
                      updated_at is when the declaration was last saved (RFC
                      3339, to the
                    type: string
                  webhook_secret:
                    description: >
                      returned once, when the source is created or the secret
                      rotated, and is never stored.
                    title: >
                      webhook_secret is sent in the X-Erdo-Lead-Source-Secret
                      header. It is
                    type: string
                  webhook_url:
                    title: >
                      webhook_url is where a webhook source's tool posts each
                      lead.
                    type: string
                type: object
          description: Success response
        default:
          $ref: '#/components/responses/APIError'
components:
  schemas:
    eventpipeline.LeadSourceBudget:
      description: >
        of its options means. A form asks the budget in its own words
        ("US$550K–1M"), and the canonical budget columns hold a range in minor
        units, so the meaning has to be declared: it is never read out of the
        option text. Each lead's chosen option is turned into the landing kit's
        budget keys (ds\_storage.BudgetRangeKey and friends), and ingestion
        writes the canonical answer from those exactly as it does for a page
        (stampBudget). See docs/dataset-declarations.md.
      properties:
        currency:
          title: |
            Currency is the ISO 4217 code every range is in ("USD").
          type: string
        options:
          additionalProperties:
            type: string
          description: >
            units of Currency (cents for USD), or to "prefer\_not\_to\_say". An
            option left out records no budget for the people who chose it.
          title: >
            Options maps each option key of the question to "<min>:<max>" or
            "<min>:" in

            whole minor
          type: object
        question:
          title: >
            Question is the form question's key, as the form lists it
            ("budget_response").
          type: string
      title: >
        LeadSourceBudget says which question on an ad platform's lead form asks
        the

        budget and what each
      type: object
    eventpipeline.LeadSourceMapping:
      properties:
        columns:
          additionalProperties:
            type: string
          description: >
            (or by the format) are never read, unless keep\_other\_fields is
            set.
          title: >
            columns maps an incoming field to a lead column. Fields not named
            here
          type: object
        consent:
          allOf:
            - $ref: '#/components/schemas/eventpipeline.LeadSourceConsent'
          description: >
            or a notice beside the submit button ("disclosure"), with the exact
            wording shown. When the mapping reads a consent column, the column
            is each person's answer and this says how it was asked: a yes gets
            this method and wording, a no stays no, a blank stays blank. When it
            reads none, everyone who submitted agreed this way and every lead is
            recorded as agreed, which holds for a box only when ticking it was
            required. Without it nothing is recorded where a row has no answer
            and the lead is not texted. A webhook posts consent per lead
            instead.
          title: >
            consent is how the source's form asked about calls and texts: an
            opt-in box

            (method "checkbox")
        default_country:
          description: |
            code belongs to ("US").
          title: |
            default_country is the ISO country a phone written without a country
          type: string
        format:
          description: >
            "meta\_lead\_export", which maps the exporter's standard fields
            itself.
          title: |
            format is "columns" (the mapping alone) or a preset such as
          type: string
        ignore:
          description: >
            not read: Meta's "company\_name", say, when the company is not
            wanted. Meta's "id" cannot be ignored, it identifies the lead; and
            email and phone cannot both be, a lead is somebody Erdo can reach. A
            field the sheet does not have is added when columns maps another
            field to its column.
          items:
            type: string
          title: >
            ignore lists fields the format reads by itself that this source
            should
          type: array
        keep_other_fields:
          description: >
            the lead, under the field's own name made into a column name ("Are
            you a broker?" becomes are\_you\_a\_broker). Only a webhook may set
            it: the tool posting to it sends exactly what its author chose,
            whereas a sheet carries the sales desk's own notes beside the leads.
            A field whose column the platform writes itself, or that a mapped
            field already fills, is skipped.
          title: >
            keep_other_fields writes every posted field the mapping does not
            name to
          type: boolean
        lead_source:
          description: >
            meta\_lead\_form, linkedin\_lead\_gen\_form or imported\_list. It is
            never free text, because the follow-up engine has a sentence for
            each value. It is optional when what\_people\_did says it instead,
            and the meta\_lead\_export format implies meta\_lead\_form.
          title: |
            lead_source is what the person did, from the platform's vocabulary:
          type: string
        row_id:
          description: |
            the source. A row is written once per id.
          items:
            type: string
          title: >
            row_id is the field, or the fields together, that identify one lead
            in
          type: array
        submitted_at:
          title: |
            submitted_at is the field that says when the person got in touch.
          type: string
        values:
          additionalProperties:
            additionalProperties:
              type: string
            type: object
          description: >
            by the answer as the source writes it: is\_broker {"Yes, I'm an
            agent": "true"}. A form asks its questions in its own words, and a
            list reading the column reads the dataset's values, not the form's.
            An answer the map does not name is kept as written and reported
            (unmappedValues), never guessed. The lookup ignores case and
            surrounding spaces.
          title: >
            values maps answers to the values a lead column holds, by column,
            then
          type: object
        what_people_did:
          description: >
            before this source sent them ("Filled in the contact form on our
            partner portal"). It is stamped on each lead the source creates
            (import\_source\_description), where the follow-up reads it as the
            development's account of how the person got in touch. Required for a
            webhook, which is for custom integrations, and for a sheet or a file
            without a lead\_source.
          title: |
            what_people_did is the development's own words for what someone did
          type: string
      title: |
        LeadSourceMapping is a declared source's column mapping.
      type: object
    eventpipeline.LeadSourceSuggestColumn:
      properties:
        description:
          description: |
            agent rather than a buyer: true or false").
          title: |
            description is what it records ("whether the person is a broker or
          type: string
        name:
          title: |
            name is the lead column ("is_broker").
          type: string
      title: >
        LeadSourceSuggestColumn is a lead column a sheet's fields may be matched
        to.
      type: object
    eventpipeline.LeadSourcePreview:
      properties:
        already_written:
          format: int64
          title: |
            already_written is how many the ledger has already dealt with.
          type: integer
        existing_columns:
          description: |
            a surface can say a suggestion matches one.
          items:
            type: string
          title: >
            existing_columns are the lead dataset's own columns a source may
            write, so
          type: array
        format_columns:
          additionalProperties:
            type: string
          description: >
            one lead column each is read as when it is read: Meta's
            company\_name as company, campaign\_name as ad\_campaign\_name. A
            surface offers such a field only that column or nothing.
          title: >
            format_columns are the fields the format itself knows, by field, and
            the
          type: object
        header:
          description: |
            body's keys.
          items:
            type: string
          title: >
            header is the fields the source offers: a sheet's header row, a
            sample
          type: array
        history:
          description: >
            before the source was declared. No alert, no follow-up until
            started.
          format: int64
          title: >
            history is how many would be written as history: leads who got in
            touch
          type: integer
        missing_fields:
          items:
            type: string
          title: |
            missing_fields are fields the mapping needs and the header lacks.
          type: array
        new:
          format: int64
          title: |
            new is how many would be written as leads getting in touch now.
          type: integer
        not_read:
          items:
            type: string
          title: >
            not_read are the fields the mapping leaves out, which are never
            written.
          type: array
        read_columns:
          additionalProperties:
            type: string
          description: >
            column each becomes: what was named in columns and what the format
            reads by itself (Meta's company\_name as company), so a person sees
            every field a lead gets from the source.
          title: >
            read_columns are the fields the mapping reads, by field, and the
            lead
          type: object
        rows:
          format: int64
          title: |
            rows is how many rows the source holds now.
          type: integer
        sample:
          description: >
            A sheet is rarely in date order, so its first rows are not its
            latest.
          items:
            type: object
          title: |
            sample is the newest leads as they would be written, newest first.
          type: array
        skipped:
          additionalProperties:
            format: int64
            type: integer
          title: |
            skipped counts rows that would not be written, by reason.
          type: object
        suggested_columns:
          additionalProperties:
            type: string
          description: |
            person to confirm.
          title: >
            suggested_columns proposes a lead column for each field not read,
            for a
          type: object
        suggested_values:
          additionalProperties:
            additionalProperties:
              type: string
            type: object
          description: >
            answers, the value each answer is stored as in its lead column, by
            field then answer: "are\_you\_a\_broker?" {"Yes, I'm an agent":
            "true"}. Saved as the mapping's values once a person confirms them.
          title: |
            suggested_values proposes, for a field holding a small fixed set of
          type: object
        test:
          format: int64
          title: |
            test is how many the source marks as test submissions.
          type: integer
      title: |
        LeadSourcePreview is a dry run's account of what a source would write.
      type: object
    eventpipeline.LeadSourceConsent:
      properties:
        method:
          description: |
            or "disclosure" (they submitted next to a consent notice).
          title: >
            method is "checkbox" (they ticked a required opt-in box: express
            consent)
          type: string
        text:
          description: |
            the record of what they agreed to.
          title: >
            text is the consent wording the form showed, exactly, when it is
            known:
          type: string
      title: >
        LeadSourceConsent is the consent a source's form collected from
        everyone.
      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.