Create an enquiry

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

Every field is optional, so you can capture a lead from as little as an email address and fill in the rest later.

Create an enquiry

curl https://api.yorlet.com/v1/leads/enquiries \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
        "email": "[email protected]",
        "name": "Jane Doe",
        "phone": "+441234567890",
        "unit": "unit_lrhplff1u4ZhIPSU"
      }'

Response

{
  "id": "le_pXm2Qk8sZ1vBnRtY",
  "object": "leads.enquiry",
  "created": 1712716800,
  "assignee": null,
  "email": "[email protected]",
  "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. To collect answers against an enquiry that already exists, choose one of the approaches below.

Send a hosted form
Submit answers yourself

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.

Attach a qualification configuration

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.

Create a qualification link

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.

Submit qualification answers

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.

Retrieve an enquiry

curl "https://api.yorlet.com/v1/leads/enquiries/le_pXm2Qk8sZ1vBnRtY?expand[]=qualification_configuration" \
  -H "Authorization: Bearer {{API_KEY}}"

Response

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

Qualify an enquiry

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.

List and filter enquiries

List qualified enquiries

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.

Create a qualification route

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.

Developer tools

Essentials

Integrations

Platforms

Create an enquiry

Prerequisites

Permissions