Create Lead

POST

/public/v1/leads

curl --request POST \
  --url https://api.aymaragents.com/public/v1/leads \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "conversationId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "customerName": "example", "customerEmail": "example", "customerPhone": "example", "intent": "unknown", "quality": "unknown", "stageId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "budget": { "min": 1, "max": 1 }, "zones": [], "rooms": 1, "assignedOperatorId": "example", "notes": "example" }'

• Producción

Create a lead for the current tenant, source='api' always (SPEC_API_PUBLICA.md §2.1).

conversationId given: resolves AC-5 (:func:find_linked_customer) exactly like the internal POST /leads – 404 + zero persistence if it does not belong to this tenant. conversationId omitted: customerId auto-links from customerPhone/customerEmail against this tenant’s LIVE customers (LM-2, :func:find_live_customer_by_contact) – never creates a customer. stageId given must resolve to a real stage of THIS tenant’s pipeline (404 otherwise); omitted falls back to the tenant’s default-entry stage for 'new' (:meth:LeadPipelineStageService.resolve_stage_id_for_legacy_write), same default the internal endpoint uses. assignedOperatorId, when given, must resolve to a real user of THIS tenant (404 otherwise) – isolation rule, 2026-08-01.

Idempotency-Key (API-3, D-API-4) is optional: a repeat with the SAME header and SAME body replays the original response without creating a second lead; the SAME header with a DIFFERENT body -> 422 IDEMPOTENCY_KEY_REUSE_MISMATCH.

---

Permiso necesario: tenant:leads.manage

Authorizations

• ApiKeyAuth

Request Body^required

Media typeapplication/json

PublicLeadCreateRequest

POST /public/v1/leads body.

source is NEVER accepted here – the route always stamps 'api' server-side (SPEC_API_PUBLICA.md §2.1), so it is not even a field on this model (sending it is a 422 under extra='forbid', never a silently-ignored override attempt). manualOrigin/legacy stage string are deliberately excluded too (curated surface, stageId is the one canonical field on this contract – see PublicLeadOut).

conversationId (optional): when given, the SAME AC-5/BK-21b resolution the internal POST /leads uses applies (resolves customerId from the conversation’s linked identity). WITHOUT it, customerId auto-links from customerPhone/customerEmail against this tenant’s LIVE customers (LM-2) – never invents/creates a customer.

object

conversationId

Any of:

string

string format: uuid

null

null

customerName

required

Customername

string

customerEmail

Any of:

string

string

null

null

customerPhone

Any of:

string

string

>= 1 characters <= 20 characters

null

null

intent

Intent

string

default: unknown

quality

Quality

string

default: unknown

stageId

Any of:

string

string format: uuid

null

null

budget

Any of:

PublicLeadBudgetIn

PublicLeadBudgetIn

Budget bounds for the create body.

object

min

Any of:

integer

integer

null

null

max

Any of:

integer

integer

null

null

null

null

zones

Zones

Array<string>

default:

rooms

Any of:

integer

integer

null

null

assignedOperatorId

Any of:

string

string

null

null

notes

Any of:

string

string

null

null

Responses

201

Successful Response

Media typeapplication/json

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

Example^generated

{
  "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"
}

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": {}
    }
  ]
}