Skip to content
Leads & Requirements

Website Lead Capture: developer guide

Pilot: every request and response field, status codes, retries and mock requests for sending enquiries to EstateCue.

Website Integration is in a pilot with selected workspaces. If the workspace owner doesn’t see it under Settings › Integrations, they can contact us to join the pilot.

This guide is for whoever maintains the website. Your website’s server sends each enquiry to EstateCue as JSON over HTTPS. Never call the endpoint from browser JavaScript or put the secret key in a page: it must stay on your server.

Request

HTTP
POST https://api.estatecue.com/api/integrations/v1/website/leads
Authorization: Bearer <your-secret-key>
Content-Type: application/json
Idempotency-Key: <same value as event_id>   (optional)

The workspace owner can copy the exact endpoint from Settings › Website Integration. A request body can be up to 64 KB. By default each website can send up to 60 enquiries a minute and 2,000 a day.

Headers

FieldTypeRequiredDescription
AuthorizationBearer <secret>RequiredYour website secret, shown once when the integration was created or the secret regenerated. Keep it on your server only.
Content-Typeapplication/jsonRequiredAny other content type is refused with 415 UNSUPPORTED_MEDIA_TYPE.
Idempotency-KeystringOptionalIf you send it, it must equal event_id exactly, or the request is refused with 422.

Body

JSON
{
  "event_id": "enq-2026-10-08-000123",
  "submitted_at": "2026-10-08T15:42:10+05:30",
  "lead": {
    "name": "Ravi Kumar",
    "phone": "+919876543210",
    "email": "ravi@example.com",
    "message": "Is the 3 BHK still available?"
  },
  "context": { "listing_id": "<estatecue-listing-id>" },
  "source": {
    "page_url": "https://www.yourwebsite.in/properties/green-valley",
    "referrer": "https://www.google.com/",
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "green-valley-launch"
  },
  "consent": {
    "contact_consent": true,
    "consent_text_version": "2026-09",
    "consented_at": "2026-10-08T15:42:05+05:30"
  }
}

Body fields

FieldTypeRequiredDescription
event_idstring, 1–128RequiredYour unique ID for this enquiry, from A–Z a–z 0–9 . _ : -. Reuse it only to retry the same enquiry: a retry never creates a second lead, and the same ID with a different body is refused with 409.
submitted_atISO 8601 date-timeOptionalWhen the buyer submitted the form. Must include a time zone, e.g. 2026-10-08T10:15:00+05:30.
testbooleanOptionaltrue runs every check without creating a lead or notifying anyone, and works while the integration is a draft. Default false.
leadobjectRequiredThe buyer who enquired.
lead.namestring, 1–160RequiredThe buyer’s name. No control characters.
lead.phonestring, up to 40Phone or emailThe buyer’s phone number, e.g. +91 98765 43210. Send a phone, an email, or both.
lead.emailstring, up to 254Phone or emailThe buyer’s email address. Saved in lowercase.
lead.messagestring, up to 2000OptionalWhat the buyer wrote in the form.
contextobjectOptionalWhat the buyer asked about. Send listing_id or project_id, not both (422 CONTEXT_CONFLICT).
context.listing_idstring, up to 64OptionalAn EstateCue listing ID from this workspace. Links the lead to that listing. An unknown ID is refused with 422 CONTEXT_NOT_FOUND.
context.project_idstring, up to 64OptionalAn EstateCue project ID from this workspace. Links the lead to that project.
context.external_referencestring, up to 120OptionalYour own reference for the page or property, e.g. your CMS ID. Saved with the enquiry for your team; not used for linking.
context.property_id—Not acceptedRefused with 422. Send the listing_id of the property’s listing instead.
sourceobjectOptionalWhere the enquiry came from. Saved on the lead for reporting.
source.page_urlhttp(s) URL, up to 1000OptionalThe page the form was on. Saved without its query string.
source.referrerhttp(s) URL, up to 500OptionalThe page the buyer came from.
source.utm_sourcestring, up to 200OptionalUTM source from the landing URL, e.g. google.
source.utm_mediumstring, up to 200OptionalUTM medium, e.g. cpc.
source.utm_campaignstring, up to 200OptionalUTM campaign name.
source.utm_contentstring, up to 200OptionalUTM content, e.g. the ad variant.
source.utm_termstring, up to 200OptionalUTM term, e.g. the search keyword.
consentobjectOptionalRecorded exactly as sent. EstateCue never infers consent you didn’t send.
consent.contact_consentbooleanOptionalWhether the buyer agreed to be contacted.
consent.consent_text_versionstring, up to 40OptionalWhich version of your consent wording the buyer saw, e.g. v2.
consent.consented_atISO 8601 date-timeOptionalWhen the buyer agreed. Must include a time zone.
  • Unknown fields are rejected, and a value over its limit is rejected rather than cut short.
  • Dates and times must include a UTC offset, such as +05:30.

Test without creating a lead

Add "test": true to the body to run every check without creating a lead or notifying anyone. Tests work while the integration is still a draft; real enquiries are accepted once the owner activates it.

Responses

JSON, 201 Created
{
  "event_id": "enq-2026-10-08-000123",
  "status": "created",
  "lead_id": "5f0c2c1e-…",
  "lead_reference": "LD-00123",
  "context_linked": { "type": "listing", "id": "<estatecue-listing-id>" },
  "replayed": false,
  "trace_id": "…"
}

Success response fields (201 created, 200 attached or duplicate)

FieldTypeRequiredDescription
event_idstringAlwaysThe event_id you sent.
status"created" | "attached" | "duplicate"Alwayscreated: a new lead (HTTP 201). attached: added to the buyer’s existing lead (200). duplicate: the same buyer enquired moments ago, so nothing new was saved (200).
lead_idstringAlwaysThe EstateCue lead the enquiry is on.
lead_referencestring | nullAlwaysThe reference your team sees on the lead, e.g. LD-00123.
context_linkedobject | nullAlways{ "type": "listing" | "project", "id": "…" } when the lead was linked to what the buyer asked about; otherwise null.
replayedbooleanAlwaystrue when you retried an event_id that was already processed. The body is the original answer and nothing new was saved.
trace_idstringAlwaysQuote this when you contact EstateCue support.

Test response fields (200, when you send "test": true)

FieldTypeRequiredDescription
event_idstringAlwaysThe event_id you sent.
status"test_ok"AlwaysEvery check passed. No lead was created and no one was notified.
would"create" | "attach" | "duplicate"AlwaysWhat the same enquiry would do if sent for real. A test never returns a lead ID.
context_linkedobject | nullAlwaysThe listing or project the lead would be linked to.
replayedbooleanAlwaysAlways false for a test.
trace_idstringAlwaysQuote this when you contact EstateCue support.

Sending the same event_id again returns the original response with "replayed": true. It never creates a second lead.

Errors and retries

An error returns a detail object with code, message, retryable and, for field problems, an errors list naming each field. Quote the trace_id if you contact support.

Error response fields

FieldTypeRequiredDescription
detail.codestringAlwaysA stable, machine-readable code. See the status codes below.
detail.messagestringAlwaysWhat went wrong, in words you can log.
detail.retryablebooleanAlwaystrue: retry later with the same request. false: fix the request first; resending it unchanged fails again.
detail.errors[]arraySometimesFor 422: one entry per problem, each with path (e.g. lead.phone), code (e.g. invalid_phone) and message.
trace_idstringAlwaysQuote this when you contact EstateCue support.
Retry-After (header)secondsSometimesOn 429, 503 and some 409 answers: wait this long before retrying.

Status codes

HTTPCodeMeaningWhat to do
201status: createdA new lead was created.Done.
200status: attached / duplicateAdded to an existing lead, or a repeat of a moment ago.Done.
200status: test_okA test passed. Nothing was saved.Send real enquiries without "test".
400MALFORMED_JSONThe body isn’t valid JSON.Fix the body.
401INTEGRATION_AUTH_INVALIDThe secret is missing or wrong.Check the Authorization header.
403INTEGRATION_NOT_ACTIVEThe integration is still a draft.Activate it in EstateCue, or send "test": true.
403INTEGRATION_DISABLEDThe integration is paused in EstateCue.Ask the workspace owner to activate it, then resend.
403WORKSPACE_NOT_ELIGIBLEThe workspace isn’t accepting new leads.Contact the workspace owner.
409IDEMPOTENCY_CONFLICTThe event_id was used before with a different body.Use a new event_id for a new enquiry.
409EVENT_IN_PROGRESSThe same enquiry is still being processed.Retry after Retry-After with the same event_id.
413PAYLOAD_TOO_LARGEThe body is over the 64 KB limit.Shorten the message or remove extra data.
415UNSUPPORTED_MEDIA_TYPEThe body wasn’t sent as JSON.Send Content-Type: application/json.
422PAYLOAD_INVALIDA field failed validation, or an unknown field was sent.Read detail.errors and fix those fields.
422CONTEXT_NOT_FOUNDThe listing or project ID isn’t in this workspace.Check the ID, or leave context out.
422CONTEXT_CONFLICTBoth listing_id and project_id were sent.Send only one.
429RATE_LIMITEDToo many requests from this website or IP address.Retry after Retry-After with the same event_id.
500INTERNAL_ERRORAn unexpected problem in EstateCue.Retry with the same event_id.
503DEPENDENCY_UNAVAILABLEA temporary problem in EstateCue.Retry after Retry-After with the same event_id.
503INTEGRATION_UNAVAILABLEWebsite enquiries are switched off for maintenance.Keep the enquiry and retry after Retry-After.
  • Fix the request, don’t retry: every 4xx except 409 EVENT_IN_PROGRESS and 429 RATE_LIMITED.
  • Retry later with the same event_id: 409 EVENT_IN_PROGRESS, 429 RATE_LIMITED, 500 INTERNAL_ERROR, 503 DEPENDENCY_UNAVAILABLE and 503 INTEGRATION_UNAVAILABLE. When a Retry-After header is set, wait that many seconds.

Mock requests and responses

Each scenario shows the exact request and the answer to expect, so you can build and unit-test your form handler before going live. To try the real endpoint safely, send the test enquiry: with "test": true it runs every check and never creates a lead.

Send this first. It runs every check against the real endpoint and never creates a lead.

Mock request
curl --request POST 'https://api.estatecue.com/api/integrations/v1/website/leads' \
  --header 'Authorization: Bearer <your-website-secret>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: test-2026-10-08-0001' \
  --data '{
  "event_id": "test-2026-10-08-0001",
  "submitted_at": "2026-10-08T10:15:00+05:30",
  "lead": {
    "name": "Ravi Sharma",
    "phone": "+91 98765 43210",
    "email": "ravi.sharma@example.com",
    "message": "Is the 3 BHK still available? I would like to visit this weekend."
  },
  "context": {
    "listing_id": "3f6c1a8e-5b2d-4c1e-9a7f-2d8e6b1c4a90"
  },
  "source": {
    "page_url": "https://www.yourwebsite.in/properties/green-valley-3bhk",
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "kokapet-3bhk"
  },
  "consent": {
    "contact_consent": true,
    "consent_text_version": "v2",
    "consented_at": "2026-10-08T10:15:00+05:30"
  },
  "test": true
}'
Mock response: 200 OK
{
  "event_id": "test-2026-10-08-0001",
  "status": "test_ok",
  "would": "create",
  "context_linked": {
    "type": "listing",
    "id": "3f6c1a8e-5b2d-4c1e-9a7f-2d8e6b1c4a90"
  },
  "replayed": false,
  "trace_id": "req_7c9e2a41b3d8"
}

Code examples

cURL
curl --request POST 'https://api.estatecue.com/api/integrations/v1/website/leads' \
  --header 'Authorization: Bearer <your-secret-key>' \
  --header 'Content-Type: application/json' \
  --data '{"event_id":"enq-test-1","test":true,"lead":{"name":"Test Buyer","email":"test@example.com"}}'
Node.js 18+
import { randomUUID } from 'node:crypto';

// Runs on your server. Keep the key in an environment variable.
export async function sendEnquiry(form) {
  const eventId = form.eventId || randomUUID(); // save it with the enquiry so a retry reuses it
  const response = await fetch('https://api.estatecue.com/api/integrations/v1/website/leads', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.ESTATECUE_WEBSITE_SECRET,
      'Content-Type': 'application/json',
      'Idempotency-Key': eventId,
    },
    body: JSON.stringify({
      event_id: eventId,
      lead: { name: form.name, phone: form.phone, email: form.email, message: form.message },
      context: form.listingId ? { listing_id: form.listingId } : undefined,
      source: { page_url: form.pageUrl },
    }),
  });
  const result = await response.json();
  if (!response.ok && result.detail && result.detail.retryable) {
    // Queue the enquiry and retry later with the same eventId.
  }
  return result;
}
PHP (also works in WordPress)
<?php
// Runs on your server. Keep the key out of your code, for example in an environment variable.
$eventId = bin2hex(random_bytes(16)); // save it with the enquiry so a retry reuses it
$payload = [
    'event_id' => $eventId,
    'lead' => [
        'name' => $_POST['name'],
        'phone' => $_POST['phone'] ?? null,
        'email' => $_POST['email'] ?? null,
        'message' => $_POST['message'] ?? null,
    ],
    'context' => ['listing_id' => 'ESTATECUE_LISTING_ID'],
    'source' => ['page_url' => $_POST['page_url'] ?? null], // a hidden field with the page's URL
];

$ch = curl_init('https://api.estatecue.com/api/integrations/v1/website/leads');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('ESTATECUE_WEBSITE_SECRET'),
        'Content-Type: application/json',
        'Idempotency-Key: ' . $eventId,
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);
$result = json_decode((string) curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status === 0 || !empty($result['detail']['retryable'])) {
    // Save the enquiry and $eventId, and retry later with the same event_id.
}
Still stuck?

Talk to a real person

Tell us what you were trying to do and what happened. We usually reply within one business day.