[{"data":1,"prerenderedAt":398},["ShallowReactive",2],{"page:\u002Fleads":3,"schema:ExternalLead":302,"operations":361},{"id":4,"title":5,"body":6,"description":292,"extension":293,"meta":294,"navigation":295,"operation":296,"path":297,"rawbody":298,"seo":299,"stem":300,"__hash__":301},"docs\u002Fleads.md","Leads",{"type":7,"value":8,"toc":282},"minimark",[9,27,32,35,39,46,200,206,217,221,227,253,256,260,271,275,278],[10,11,12,13,17,18,21,22,26],"p",{},"A lead is a contact the agency works with: someone looking to buy or rent (",[14,15,16],"code",{},"demandante","), an owner (",[14,19,20],{},"propietario","), or a partner such as another agency, a bank or a service provider. Leads carry contact details and, for people searching, ",[23,24,25],"strong",{},"search preferences"," that Vestta uses to match them against the property catalogue.",[28,29,31],"h2",{"id":30},"endpoints","Endpoints",[33,34],"api-endpoints",{"tag":5},[28,36,38],{"id":37},"choosing-an-endpoint","Choosing an endpoint",[10,40,41,42,45],{},"The two ",[14,43,44],{},"POST"," endpoints both create a lead, from different payloads and with different rules. Reading the differences once saves surprises later:",[47,48,49,71],"table",{},[50,51,52],"thead",{},[53,54,55,58,65],"tr",{},[56,57],"th",{},[56,59,60],{},[61,62,64],"a",{"href":63},"\u002Fleads\u002Fingest","Ingest a rental lead",[56,66,67],{},[61,68,70],{"href":69},"\u002Fleads\u002Finquiries","Create an inquiry",[72,73,74,86,111,129,145,162,176,186],"tbody",{},[53,75,76,80,83],{},[77,78,79],"td",{},"Payload",[77,81,82],{},"Compact rental-form format",[77,84,85],{},"Full lead: contact details and structured search preferences",[53,87,88,91,96],{},[77,89,90],{},"Lead type",[77,92,93,94],{},"Always ",[14,95,16],{},[77,97,98,99,102,103,106,107,110],{},"From ",[14,100,101],{},"type"," (",[14,104,105],{},"buyer",", ",[14,108,109],{},"owner","…)",[53,112,113,116,123],{},[77,114,115],{},"Search preferences",[77,117,118,119,122],{},"Derived: rent an apartment or house, maximum rent from ",[14,120,121],{},"budget",", minimum bedrooms, one location",[77,124,125,126],{},"Exactly what you send in ",[14,127,128],{},"search_preferences",[53,130,131,134,139],{},[77,132,133],{},"Urgency",[77,135,136],{},[14,137,138],{},"alta-urgencia",[77,140,141,144],{},[14,142,143],{},"poca-urgencia"," unless you send it",[53,146,147,150,156],{},[77,148,149],{},"Phone already in the workspace",[77,151,152,153],{},"Nothing is created; still returns ",[14,154,155],{},"200",[77,157,158,159],{},"Completes the existing lead if it has no name; otherwise ",[14,160,161],{},"409",[53,163,164,167,170],{},[77,165,166],{},"Returns the lead ID",[77,168,169],{},"No",[77,171,172,173],{},"Yes, ",[14,174,175],{},"lead_id",[53,177,178,181,183],{},[77,179,180],{},"Follow-up scheduling",[77,182,169],{},[77,184,185],{},"Yes",[53,187,188,191,196],{},[77,189,190],{},"Scope",[77,192,193],{},[14,194,195],{},"leads:ingest",[77,197,198],{},[14,199,195],{},[10,201,202,205],{},[23,203,204],{},"Use Create an inquiry for new integrations",": you control the lead type and preferences, you get the ID back, and duplicates are reported explicitly. Ingest a rental lead exists for rental landing pages that already send its compact format.",[10,207,208,212,213,216],{},[61,209,211],{"href":210},"\u002Fleads\u002Flist","List leads"," is read-only and needs the separate ",[14,214,215],{},"leads:read"," scope.",[28,218,220],{"id":219},"what-happens-after-a-lead-is-created","What happens after a lead is created",[10,222,223,224,226],{},"Both ",[14,225,44],{}," endpoints respond as soon as the lead is stored. Then, in the background, Vestta:",[228,229,230,237,243],"ol",{},[231,232,233,236],"li",{},[23,234,235],{},"Matches"," the lead against the property catalogue, using its search preferences.",[231,238,239,242],{},[23,240,241],{},"Contacts the lead on WhatsApp",", if the workspace has WhatsApp connected: one approved template message, sent once per lead, after which the Vestta assistant can carry on the conversation when the lead replies.",[231,244,245,246,249,250,252],{},"For inquiries only, ",[23,247,248],{},"schedules follow-ups",". For people searching, every 30 days if they want to rent and every 90 days if they want to buy or take over a business, based on the operations in ",[14,251,128],{},"; for other lead types, according to the workspace's follow-up rules.",[10,254,255],{},"None of this changes the response. If WhatsApp is not connected, the lead is still created.",[28,257,259],{"id":258},"phone-numbers","Phone numbers",[10,261,262,263,266,267,270],{},"The primary phone identifies a lead within a workspace: two leads cannot share it. Send numbers in international format, such as ",[14,264,265],{},"+34600111222",". Numbers without a prefix are read as Spanish, and numbers that are not valid phone numbers are rejected with ",[14,268,269],{},"422",".",[28,272,274],{"id":273},"the-lead-object","The lead object",[10,276,277],{},"List leads returns lead objects with these fields. Fields without a value are omitted.",[279,280],"api-model",{"name":281},"ExternalLead",{"title":283,"searchDepth":284,"depth":284,"links":285},"",3,[286,288,289,290,291],{"id":30,"depth":287,"text":31},2,{"id":37,"depth":287,"text":38},{"id":219,"depth":287,"text":220},{"id":258,"depth":287,"text":259},{"id":273,"depth":287,"text":274},"Read the leads of a Vestta workspace and send new leads from your forms and services.","md",{},true,null,"\u002Fleads","---\ntitle: Leads\ndescription: Read the leads of a Vestta workspace and send new leads from your forms and services.\n---\n\nA lead is a contact the agency works with: someone looking to buy or rent (`demandante`), an owner (`propietario`), or a partner such as another agency, a bank or a service provider. Leads carry contact details and, for people searching, **search preferences** that Vestta uses to match them against the property catalogue.\n\n## Endpoints\n\n:api-endpoints{tag=\"Leads\"}\n\n## Choosing an endpoint\n\nThe two `POST` endpoints both create a lead, from different payloads and with different rules. Reading the differences once saves surprises later:\n\n| | [Ingest a rental lead](\u002Fleads\u002Fingest) | [Create an inquiry](\u002Fleads\u002Finquiries) |\n| --- | --- | --- |\n| Payload | Compact rental-form format | Full lead: contact details and structured search preferences |\n| Lead type | Always `demandante` | From `type` (`buyer`, `owner`…) |\n| Search preferences | Derived: rent an apartment or house, maximum rent from `budget`, minimum bedrooms, one location | Exactly what you send in `search_preferences` |\n| Urgency | `alta-urgencia` | `poca-urgencia` unless you send it |\n| Phone already in the workspace | Nothing is created; still returns `200` | Completes the existing lead if it has no name; otherwise `409` |\n| Returns the lead ID | No | Yes, `lead_id` |\n| Follow-up scheduling | No | Yes |\n| Scope | `leads:ingest` | `leads:ingest` |\n\n**Use Create an inquiry for new integrations**: you control the lead type and preferences, you get the ID back, and duplicates are reported explicitly. Ingest a rental lead exists for rental landing pages that already send its compact format.\n\n[List leads](\u002Fleads\u002Flist) is read-only and needs the separate `leads:read` scope.\n\n## What happens after a lead is created\n\nBoth `POST` endpoints respond as soon as the lead is stored. Then, in the background, Vestta:\n\n1. **Matches** the lead against the property catalogue, using its search preferences.\n2. **Contacts the lead on WhatsApp**, if the workspace has WhatsApp connected: one approved template message, sent once per lead, after which the Vestta assistant can carry on the conversation when the lead replies.\n3. For inquiries only, **schedules follow-ups**. For people searching, every 30 days if they want to rent and every 90 days if they want to buy or take over a business, based on the operations in `search_preferences`; for other lead types, according to the workspace's follow-up rules.\n\nNone of this changes the response. If WhatsApp is not connected, the lead is still created.\n\n## Phone numbers\n\nThe primary phone identifies a lead within a workspace: two leads cannot share it. Send numbers in international format, such as `+34600111222`. Numbers without a prefix are read as Spanish, and numbers that are not valid phone numbers are rejected with `422`.\n\n## The lead object\n\nList leads returns lead objects with these fields. Fields without a value are omitted.\n\n:api-model{name=\"ExternalLead\"}\n",{"title":5,"description":292},"leads","YDZiZ2OUdIRkCu8PGygLhfyM75-7V231iIg8zo6dYh4",{"name":281,"fields":303},[304,310,314,317,321,325,329,333,336,339,342,345,349,353,357],{"name":305,"type":306,"required":295,"nullable":307,"description":308,"constraints":309},"id","integer",false,"Numeric lead ID.",[],{"name":311,"type":312,"required":307,"nullable":295,"constraints":313},"name","string",[],{"name":101,"type":312,"required":307,"nullable":295,"description":315,"constraints":316},"`demandante` (looking for a property), `propietario` (owner), `agencia-inmobiliaria`, `entidad-bancaria` or `proveedor-servicios`.",[],{"name":318,"type":312,"required":307,"nullable":295,"description":319,"constraints":320},"status","Pipeline status, e.g. `new`, `searching_property`, `active_negotiation`, `closed` or `inactive`.",[],{"name":322,"type":323,"required":307,"nullable":295,"constraints":324},"active","boolean",[],{"name":326,"type":312,"required":307,"nullable":295,"description":327,"constraints":328},"source","Where the lead came from, e.g. `web`, `manual`, or the `source` sent on ingestion.",[],{"name":330,"type":312,"required":307,"nullable":295,"description":331,"constraints":332},"phone_number_1","Primary phone in E.164 format.",[],{"name":334,"type":312,"required":307,"nullable":295,"constraints":335},"phone_number_2",[],{"name":337,"type":312,"required":307,"nullable":295,"constraints":338},"landline_phone",[],{"name":340,"type":312,"required":307,"nullable":295,"constraints":341},"personal_email",[],{"name":343,"type":312,"required":307,"nullable":295,"constraints":344},"professional_email",[],{"name":346,"type":312,"required":307,"nullable":295,"description":347,"constraints":348},"preferred_language","`es`, `gb`, `fr`, `ge` or `it`.",[],{"name":128,"type":350,"required":307,"nullable":307,"description":351,"constraints":352},"any","What the lead is looking for (same shape as `search_preferences` in Create an inquiry), without internal notes.",[],{"name":354,"type":312,"required":307,"nullable":295,"description":355,"constraints":356},"created_at","ISO 8601 timestamp with UTC offset. Leads are ordered by this field, newest first.",[],{"name":358,"type":312,"required":307,"nullable":295,"description":359,"constraints":360},"updated_at","ISO 8601 timestamp with UTC offset.",[],[362,367,371,375,384,391],{"id":363,"method":364,"path":297,"fullPath":365,"summary":211,"tag":5,"scopes":366,"docsPath":210},"listLeads","GET","\u002Fv1\u002Fext\u002Fleads",[215],{"id":368,"method":44,"path":63,"fullPath":369,"summary":64,"tag":5,"scopes":370,"docsPath":63},"ingestRentalLead","\u002Fv1\u002Fext\u002Fleads\u002Fingest",[195],{"id":372,"method":44,"path":69,"fullPath":373,"summary":70,"tag":5,"scopes":374,"docsPath":69},"createLeadInquiry","\u002Fv1\u002Fext\u002Fleads\u002Finquiries",[195],{"id":376,"method":364,"path":377,"fullPath":378,"summary":379,"tag":380,"scopes":381,"docsPath":383},"listProperties","\u002Fproperties","\u002Fv1\u002Fext\u002Fproperties","List properties","Properties",[382],"properties:read","\u002Fproperties\u002Flist",{"id":385,"method":364,"path":386,"fullPath":387,"summary":388,"tag":380,"scopes":389,"docsPath":390},"getProperty","\u002Fproperties\u002F{property_id}","\u002Fv1\u002Fext\u002Fproperties\u002F{property_id}","Retrieve a property",[382],"\u002Fproperties\u002Fretrieve",{"id":392,"method":364,"path":393,"fullPath":394,"summary":395,"tag":396,"scopes":397,"docsPath":393},"getApiKeyContext","\u002Fme","\u002Fv1\u002Fext\u002Fme","Retrieve key context","Authentication",[],1791110048514]