List Leads

GET

/public/v1/leads

curl --request GET \
  --url 'https://api.aymaragents.com/public/v1/leads?limit=50' \
  --header 'X-API-Key: <X-API-Key>'

• Producción

List the tenant’s leads (SPEC_API_PUBLICA.md §2.1).

Same filter/pagination semantics as the internal GET /leads for the shared filters; dateFrom/dateTo is public-API-only (backs a third-party CRM’s incremental sync, case 1 of the spec’s “casos de uso reales”).

---

Permiso necesario: tenant:leads.read

Authorizations

• ApiKeyAuth

Parameters

Query Parameters

quality

Any of:

string

string

null

null

stageId

Any of:

string

string format: uuid

null

null

source

Any of:

string

string

null

null

customerId

Any of:

string

string format: uuid

null

null

customerPhone

Any of:

string

string

null

null

dateFrom

Any of:

string

string format: date-time

null

null

dateTo

Any of:

string

string format: date-time

null

null

cursor

Any of:

string

string

null

null

limit

Limit

integer

default: 50 >= 1 <= 200

Responses

200

Successful Response

Media typeapplication/json

PublicLeadsResponse

Paginated lead list (GET /public/v1/leads) – same envelope shape as the internal LeadsResponse (PAGIN-1).

object

items

required

Items

Array<object>

PublicLeadOut

Lead shape returned by the public list/get/create/update endpoints.

Curated subset of the internal LeadOut (schemas/leads.py): drops originChannelId/originChannelName (MCH-7 internal attribution, meaningless to a third- party integration) and the legacy stage string mirror (stageId is the single canonical field on this NEW contract – no legacy bridge to preserve here, unlike the internal shape which still serves pre-KAN consumers).

object

id

required

Id

string

customerId

Any of:

string

string

null

null

conversationId

Any of:

string

string

null

null

customerName

required

Customername

string

customerEmail

Any of:

string

string

null

null

customerPhone

Any of:

string

string

null

null

intent

required

Intent

string

quality

required

Quality

string

stageId

required

Stageid

string

budget

Any of:

PublicLeadBudgetOut

PublicLeadBudgetOut

Budget range in EUR.

Either bound may be null.

object

min

Any of:

integer

integer

null

null

max

Any of:

integer

integer

null

null

null

null

zones

required

Zones

Array<string>

rooms

Any of:

integer

integer

null

null

assignedOperatorId

Any of:

string

string

null

null

source

required

Source

string

notes

Any of:

string

string

null

null

createdAt

required

Createdat

string

updatedAt

required

Updatedat

string

total

required

Total

integer

cursor

Any of:

string

string

null

null

pagination

required

OffsetPaginationMeta

12-api-contract.md §3.2 offset/limit pagination metadata, verbatim shape.

object

page

required

Page

integer

pageSize

required

Pagesize

integer

totalItems

required

Totalitems

integer

totalPages

required

Totalpages

integer

hasNext

required

Hasnext

boolean

hasPrev

required

Hasprev

boolean

Example^generated

{
  "items": [
    {
      "id": "example",
      "customerId": "example",
      "conversationId": "example",
      "customerName": "example",
      "customerEmail": "example",
      "customerPhone": "example",
      "intent": "example",
      "quality": "example",
      "stageId": "example",
      "budget": {
        "min": 1,
        "max": 1
      },
      "zones": [
        "example"
      ],
      "rooms": 1,
      "assignedOperatorId": "example",
      "source": "example",
      "notes": "example",
      "createdAt": "example",
      "updatedAt": "example"
    }
  ],
  "total": 1,
  "cursor": "example",
  "pagination": {
    "page": 1,
    "pageSize": 1,
    "totalItems": 1,
    "totalPages": 1,
    "hasNext": true,
    "hasPrev": true
  }
}

422

Validation Error

Media typeapplication/json

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

input

Input

ctx

Context

object

Example^generated

{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example",
      "input": "example",
      "ctx": {}
    }
  ]
}