Lead forms

هذه الصفحة بالإنجليزية عمدًا: أسماء الحقول والأوامر يجب أن تُقرأ تمامًا كما يعرضها المنتج وواجهة البرمجة.

POST /api/v1/leads takes an enquiry from any form on the company’s website. The platform fixes nothing about your forms: it only asks for what it needs to protect the company and the visitor.

Post from the browser, never through a host’s server

Enquiries are posted directly from the visitor’s browser to the API. Do not route them through your hosting provider’s server code: the platform reads the visitor’s address and the spam check from that request, and personal data then never passes through a third party. A server posting on its own behalf uses a server key with write:leads instead.

What every enquiry needs

• The publishable key in X-Api-Key, sent from one of its origins.
• consent: true and the consent_version the visitor saw, from the company’s privacy notice.
• A spam-check token in challenge, from the company’s Turnstile widget on your page.
• The hidden website field, left empty: it catches bots.
• At least an email or a phone.

The fields

• service: what the visitor asks for, a key from GET /api/v1/services, the company’s own list, which it edits in its admin. A key the list does not have yet is still accepted and kept, so no enquiry is lost while the website and the admin disagree.
• form: which form sent it, named as you like (lowercase letters, digits, - and _), such as footer-contact. The company’s inbox filters by it.
• page: the address of the page the form was on, on one of the key’s origins (another address is not kept). Its query, fragment and any credentials are dropped.
• listing: the slug of the listing asked about, in any language. An unknown slug is ignored.
• details: the form’s own questions and answers, such as dates, guests or a budget: up to 20 keys of lowercase letters, digits and _, each a text (500 characters at most), a number, true or false, or a list of them. Staff see them on the lead, encrypted at rest. Never ask for identity documents, card numbers or passwords, in any spelling: such keys are refused. Contact details go in email and phone, never in details.
• name, email, phone, message, language.

const response = await fetch("https://<company host>/api/v1/leads", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-Api-Key": "pk_..." },
  body: JSON.stringify({
    service: "holiday-home-stay",
    form: "holiday-home-enquiry",
    page: window.location.href,
    listing: "marina-holiday-home",
    name: form.name.value,
    email: form.email.value,
    message: form.message.value,
    details: { check_in: form.checkIn.value, check_out: form.checkOut.value, guests: Number(form.guests.value) },
    consent: form.consent.checked,
    consent_version: "2026-09",
    challenge: turnstileToken,
    website: "",
  }),
});
if (response.status === 201) {
  const { reference } = await response.json();
}

The services, for a form’s choices:

const { results } = await (await fetch("https://<company host>/api/v1/services")).json();
const options = results.map((service) => ({ value: service.key, label: service.name[locale] }));

Owners offering a property

A service whose kind is listing_request (such as selling-a-property or property-management) is for owners who want to sell, let or have a property managed; put those services on the website’s page for owners. The company can turn such a request into a draft listing, filled from these answers when the form sends them in details:

• purpose: sale, lease or holiday_home;
• area: an area’s slug from GET /api/v1/areas, in any language; property_type: a property type’s value from GET /api/v1/filters;
• bedrooms and bathrooms (whole numbers, 0 for a studio), size_sqm, price (the owner’s expectation) and price_period (night, month, year or total).

Other answers, such as the building or when it is free, stay on the request for staff. Do not ask owners for photos or documents in the form: staff collect them when the owner signs.

await fetch("https://<company host>/api/v1/leads", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-Api-Key": "pk_..." },
  body: JSON.stringify({
    service: "selling-a-property",
    form: "list-your-property",
    page: window.location.href,
    name: form.name.value,
    phone: form.phone.value,
    details: {
      purpose: "sale",
      area: form.area.value,
      property_type: form.propertyType.value,
      bedrooms: Number(form.bedrooms.value),
      price: Number(form.price.value),
      building: form.building.value,
    },
    consent: form.consent.checked,
    consent_version: "2026-09",
    challenge: turnstileToken,
    website: "",
  }),
});

After the post

The answer is 201 with the lead’s reference. The platform sends no email about enquiries; the company sees each one in its admin and is notified there. If the company wants an email for each enquiry, the website sends it from its own mail service. The lead.created webhook tells other systems.