> ## Documentation Index > Fetch the complete documentation index at: https://docs.yorlet.com/llms.txt > Use this file to discover all available pages before exploring further. # Create an enquiry > Learn how to capture and qualify leads with the Yorlet API. export const APIBadge = () => { return
API
; }; This guide shows you how to capture a lead using the Enquiries API. Enquiries let you record prospective tenants from your own website, portal, or CRM, collect their qualification details, and move them through your pipeline towards an application. ## Prerequisites Before creating an enquiry, ensure you have: * The Leads product enabled on your account. * A [secret key](/development/api-keys). * A qualification configuration ID, if you want to collect qualification answers. Your secret key can perform any action on your account, so only ever use it from your own server. Never put it in browser JavaScript, a mobile app, or a public repository, and never send it to a lead. To collect details directly from a lead, send them a hosted qualification form or [embed the form](/development/integrations/leads/embed-a-qualification-form) on your website rather than calling the API from the browser. Those pages authenticate themselves with a short-lived key scoped to a single configuration or enquiry, so your secret key never leaves your server. If a secret key is ever exposed, [roll it](/development/api-keys) immediately. ## Permissions | Permission | Grants | | ------------------------------------------ | ---------------------------------------------------------------------------------- | | `leads.enquiries.read` | Retrieve and list enquiries | | `leads.enquiries.write` | Create and update enquiries, transition status, attach qualification, create links | | `leads.qualification_configurations.read` | Retrieve and list qualification configurations | | `leads.qualification_configurations.write` | Create and update qualification configurations | | `leads.qualification_routes.read` | Retrieve and list qualification routes | | `leads.qualification_routes.write` | Create and update qualification routes | ## Create an enquiry Every field is optional, so you can capture a lead from as little as an email address and fill in the rest later. ```bash Create an enquiry theme={"theme":"dracula"} curl https://api.yorlet.com/v1/leads/enquiries \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "email": "jane@example.com", "name": "Jane Doe", "phone": "+441234567890", "unit": "unit_lrhplff1u4ZhIPSU" }' ``` ```json Response theme={"theme":"dracula"} { "id": "le_pXm2Qk8sZ1vBnRtY", "object": "leads.enquiry", "created": 1712716800, "assignee": null, "email": "jane@example.com", "name": "Jane Doe", "phone": "+441234567890", "qualification": { "answers": null, "custom_answers": null, "reason": null, "score": null }, "qualification_configuration": null, "reviewed_at": null, "reviewed_by": null, "source": null, "status": "new", "unit": "unit_lrhplff1u4ZhIPSU", "metadata": {} } ``` ### Enquiry parameters | Parameter | Type | Description | | ----------------------------- | ------ | ------------------------------------------------------------------------------------- | | `email` | string | The lead's email address. Required to email them a qualification form or booking link | | `name` | string | The lead's full name | | `phone` | string | The lead's phone number | | `unit` | string | The ID of the unit the lead is interested in | | `assignee` | string | The ID of the user who owns the lead | | `qualification_configuration` | string | Attach a qualification configuration on creation | | `qualification` | object | Submit `answers` and `custom_answers` alongside the enquiry | | `portal` | object | Portal details when the enquiry came from a property portal | | `metadata` | object | Key-value pairs for storing additional information | An enquiry created without qualification answers starts as `new`. An enquiry created with answers starts as `pending`, because there is something for your team to review. ## Collect qualification answers A qualification configuration defines the questions you ask a lead. You can build one in the Dashboard, or with the Qualification Configurations API. Each configuration exposes a `hosted_qualification_url` that a lead can complete in their browser — submitting it creates the enquiry for you. To put that same form on your own website, [embed it with Yorlet.js](/development/integrations/leads/embed-a-qualification-form). To collect answers against an enquiry that already exists, choose one of the approaches below. Attach a configuration to the enquiry and let Yorlet host the form. Set `notification.type` to `email` to send the lead their link straight away. ```bash Attach a qualification configuration theme={"theme":"dracula"} curl https://api.yorlet.com/v1/leads/enquiries/le_pXm2Qk8sZ1vBnRtY/attach \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "qualification_configuration": "lqc_8dTvKp3wQmXsLbNe", "notification": { "type": "email" } }' ``` Retrieve the link at any time — it is created on first use and reused for the lifetime of the enquiry. ```bash Create a qualification link theme={"theme":"dracula"} curl https://api.yorlet.com/v1/leads/enquiries/le_pXm2Qk8sZ1vBnRtY/qualification_link \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "notification": { "type": "none" } }' ``` The response is a `leads.enquiry_qualification_link` object with the `enquiry` it belongs to and the `url` of the hosted form. Send that URL to the lead however you like — the hosted page handles its own authentication, so you never expose an API key to the lead. An enquiry can only have one qualification configuration. Attaching a second one returns an error, so use the qualification link action when a configuration is already attached. If you collect the answers in your own form, submit them with the update endpoint. Answers are merged with anything already recorded, so you can submit them a few at a time. ```bash Submit qualification answers theme={"theme":"dracula"} curl https://api.yorlet.com/v1/leads/enquiries/le_pXm2Qk8sZ1vBnRtY \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "qualification": { "answers": { "move_in_date": "1_month", "budget": 150000, "household_occupants": 2, "has_pets": false, "employment_status": "employed", "income_range": "40k_50k", "has_right_to_rent": true }, "custom_answers": [ { "id": "q_parking", "value": true } ] } }' ``` Each entry in `custom_answers` needs the `id` of a custom question on the attached configuration, and a `value` that can be a string, number, boolean, or array of strings. ### Standard answers | Parameter | Type | Description | | -------------------------- | ------- | ----------------------------------------------------------------------------------- | | `move_in_date` | string | `immediately`, `1_month`, `2_months`, `3_months`, or `flexible` | | `budget` | number | Monthly budget, in the smallest currency unit | | `household_occupants` | number | How many people will live there | | `household_has_children` | boolean | Whether the household includes children | | `has_pets` | boolean | Whether the lead has pets | | `pet_types` | array | The types of pets the lead has | | `pet_details` | string | Free-form detail about the pets | | `employment_status` | string | The lead's employment status | | `employer_name` | string | The lead's employer | | `income_range` | string | `under_20k`, `20k_30k`, `30k_40k`, `40k_50k`, `50k_75k`, `75k_100k`, or `over_100k` | | `is_smoker` | boolean | Whether the lead smokes | | `current_situation` | string | `renting`, `homeowner`, `living_with_family`, `relocating`, or `other` | | `reason_for_moving` | string | Why the lead is moving | | `current_landlord_name` | string | The lead's current landlord | | `current_landlord_contact` | string | Contact details for the current landlord | | `has_right_to_rent` | boolean | Whether the lead has the right to rent | | `has_guarantor` | boolean | Whether the lead can provide a guarantor | ## Read the score Once answers are submitted, Yorlet scores them against the attached configuration and writes a short explanation. Retrieve the enquiry to read both, expanding the configuration if you need its questions too. ```bash Retrieve an enquiry theme={"theme":"dracula"} curl "https://api.yorlet.com/v1/leads/enquiries/le_pXm2Qk8sZ1vBnRtY?expand[]=qualification_configuration" \ -H "Authorization: Bearer {{API_KEY}}" ``` ```json Response theme={"theme":"dracula"} { "id": "le_pXm2Qk8sZ1vBnRtY", "object": "leads.enquiry", "status": "pending", "qualification": { "score": 82, "reason": "Strong fit. Moving within a month, budget above the asking rent, and no pets.", "answers": { "move_in_date": "1_month", "budget": 150000 }, "custom_answers": [{ "id": "q_parking", "value": true }] } } ``` Scoring runs in the background, so `score` and `reason` are `null` for a short time after the first submission. ## Move the enquiry through your pipeline Use the status endpoint to progress a lead. Pass an optional `reason` to record why. ```bash Qualify an enquiry theme={"theme":"dracula"} curl https://api.yorlet.com/v1/leads/enquiries/le_pXm2Qk8sZ1vBnRtY/status \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "status": "qualified", "reason": "Affordability and move-in date both check out" }' ``` | Status | Meaning | | -------------- | ------------------------------------- | | `new` | Created without qualification answers | | `pending` | Answers submitted, awaiting review | | `contacted` | Your team has reached out | | `qualified` | Approved to progress | | `viewing` | A viewing is booked | | `application` | Moved into your application process | | `won` | The lead signed a tenancy | | `lost` | Closed without converting | | `disqualified` | Rejected during qualification | Transitions to `qualified` and `disqualified` record `reviewed_at` and `reviewed_by` on the enquiry. Moving to `qualified` also emails the lead their viewing booking link when the account has automatic booking links turned on. Booking a viewing advances the enquiry to `viewing` for you, so you do not need to set that status yourself. See [Book a viewing](/development/integrations/leads/book-a-viewing). ## List and filter enquiries ```bash List qualified enquiries theme={"theme":"dracula"} curl "https://api.yorlet.com/v1/leads/enquiries?status[]=qualified&status[]=viewing&expand[]=unit" \ -H "Authorization: Bearer {{API_KEY}}" ``` | Parameter | Type | Description | | ----------------------------- | --------------- | ----------------------------------------------------------------- | | `status` | string or array | Filter by one or more pipeline statuses | | `source` | string | Filter by the channel the enquiry came from | | `assignee` | string | Filter by owner, or pass `unassigned` for enquiries with no owner | | `qualification_configuration` | string | Filter by attached configuration | | `qualified` | boolean | Filter to enquiries that have been qualified | | `email` | string | Filter by the lead's email address | Enquiries are returned newest first, and `assignee`, `unit`, and `qualification_configuration` can each be expanded with `expand[]`. ## Route enquiries automatically Rather than attaching a configuration on every create call, use the Qualification Routes API to attach one whenever a matching enquiry arrives. Leave a condition empty to match anything, and give your most specific routes the lowest `priority`. ```bash Create a qualification route theme={"theme":"dracula"} curl https://api.yorlet.com/v1/leads/qualification_routes \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "name": "Portal leads", "qualification_configuration": "lqc_8dTvKp3wQmXsLbNe", "conditions": { "sources": ["portal"], "portal_types": ["rightmove"] }, "notification": { "type": "email" }, "priority": 10, "active": true }' ``` Routing is skipped for enquiries that already have a configuration attached or that arrive with their answers submitted.