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
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
| Field | Type | Required | Description |
|---|---|---|---|
Authorization | Bearer <secret> | Required | Your website secret, shown once when the integration was created or the secret regenerated. Keep it on your server only. |
Content-Type | application/json | Required | Any other content type is refused with 415 UNSUPPORTED_MEDIA_TYPE. |
Idempotency-Key | string | Optional | If you send it, it must equal event_id exactly, or the request is refused with 422. |
Body
{
"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
| Field | Type | Required | Description |
|---|---|---|---|
event_id | string, 1–128 | Required | Your 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_at | ISO 8601 date-time | Optional | When the buyer submitted the form. Must include a time zone, e.g. 2026-10-08T10:15:00+05:30. |
test | boolean | Optional | true runs every check without creating a lead or notifying anyone, and works while the integration is a draft. Default false. |
lead | object | Required | The buyer who enquired. |
lead.name | string, 1–160 | Required | The buyer’s name. No control characters. |
lead.phone | string, up to 40 | Phone or email | The buyer’s phone number, e.g. +91 98765 43210. Send a phone, an email, or both. |
lead.email | string, up to 254 | Phone or email | The buyer’s email address. Saved in lowercase. |
lead.message | string, up to 2000 | Optional | What the buyer wrote in the form. |
context | object | Optional | What the buyer asked about. Send listing_id or project_id, not both (422 CONTEXT_CONFLICT). |
context.listing_id | string, up to 64 | Optional | An EstateCue listing ID from this workspace. Links the lead to that listing. An unknown ID is refused with 422 CONTEXT_NOT_FOUND. |
context.project_id | string, up to 64 | Optional | An EstateCue project ID from this workspace. Links the lead to that project. |
context.external_reference | string, up to 120 | Optional | Your 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 accepted | Refused with 422. Send the listing_id of the property’s listing instead. |
source | object | Optional | Where the enquiry came from. Saved on the lead for reporting. |
source.page_url | http(s) URL, up to 1000 | Optional | The page the form was on. Saved without its query string. |
source.referrer | http(s) URL, up to 500 | Optional | The page the buyer came from. |
source.utm_source | string, up to 200 | Optional | UTM source from the landing URL, e.g. google. |
source.utm_medium | string, up to 200 | Optional | UTM medium, e.g. cpc. |
source.utm_campaign | string, up to 200 | Optional | UTM campaign name. |
source.utm_content | string, up to 200 | Optional | UTM content, e.g. the ad variant. |
source.utm_term | string, up to 200 | Optional | UTM term, e.g. the search keyword. |
consent | object | Optional | Recorded exactly as sent. EstateCue never infers consent you didn’t send. |
consent.contact_consent | boolean | Optional | Whether the buyer agreed to be contacted. |
consent.consent_text_version | string, up to 40 | Optional | Which version of your consent wording the buyer saw, e.g. v2. |
consent.consented_at | ISO 8601 date-time | Optional | When 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
{
"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)
| Field | Type | Required | Description |
|---|---|---|---|
event_id | string | Always | The event_id you sent. |
status | "created" | "attached" | "duplicate" | Always | created: 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_id | string | Always | The EstateCue lead the enquiry is on. |
lead_reference | string | null | Always | The reference your team sees on the lead, e.g. LD-00123. |
context_linked | object | null | Always | { "type": "listing" | "project", "id": "…" } when the lead was linked to what the buyer asked about; otherwise null. |
replayed | boolean | Always | true when you retried an event_id that was already processed. The body is the original answer and nothing new was saved. |
trace_id | string | Always | Quote this when you contact EstateCue support. |
Test response fields (200, when you send "test": true)
| Field | Type | Required | Description |
|---|---|---|---|
event_id | string | Always | The event_id you sent. |
status | "test_ok" | Always | Every check passed. No lead was created and no one was notified. |
would | "create" | "attach" | "duplicate" | Always | What the same enquiry would do if sent for real. A test never returns a lead ID. |
context_linked | object | null | Always | The listing or project the lead would be linked to. |
replayed | boolean | Always | Always false for a test. |
trace_id | string | Always | Quote 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
| Field | Type | Required | Description |
|---|---|---|---|
detail.code | string | Always | A stable, machine-readable code. See the status codes below. |
detail.message | string | Always | What went wrong, in words you can log. |
detail.retryable | boolean | Always | true: retry later with the same request. false: fix the request first; resending it unchanged fails again. |
detail.errors[] | array | Sometimes | For 422: one entry per problem, each with path (e.g. lead.phone), code (e.g. invalid_phone) and message. |
trace_id | string | Always | Quote this when you contact EstateCue support. |
Retry-After (header) | seconds | Sometimes | On 429, 503 and some 409 answers: wait this long before retrying. |
Status codes
| HTTP | Code | Meaning | What to do |
|---|---|---|---|
201 | status: created | A new lead was created. | Done. |
200 | status: attached / duplicate | Added to an existing lead, or a repeat of a moment ago. | Done. |
200 | status: test_ok | A test passed. Nothing was saved. | Send real enquiries without "test". |
400 | MALFORMED_JSON | The body isn’t valid JSON. | Fix the body. |
401 | INTEGRATION_AUTH_INVALID | The secret is missing or wrong. | Check the Authorization header. |
403 | INTEGRATION_NOT_ACTIVE | The integration is still a draft. | Activate it in EstateCue, or send "test": true. |
403 | INTEGRATION_DISABLED | The integration is paused in EstateCue. | Ask the workspace owner to activate it, then resend. |
403 | WORKSPACE_NOT_ELIGIBLE | The workspace isn’t accepting new leads. | Contact the workspace owner. |
409 | IDEMPOTENCY_CONFLICT | The event_id was used before with a different body. | Use a new event_id for a new enquiry. |
409 | EVENT_IN_PROGRESS | The same enquiry is still being processed. | Retry after Retry-After with the same event_id. |
413 | PAYLOAD_TOO_LARGE | The body is over the 64 KB limit. | Shorten the message or remove extra data. |
415 | UNSUPPORTED_MEDIA_TYPE | The body wasn’t sent as JSON. | Send Content-Type: application/json. |
422 | PAYLOAD_INVALID | A field failed validation, or an unknown field was sent. | Read detail.errors and fix those fields. |
422 | CONTEXT_NOT_FOUND | The listing or project ID isn’t in this workspace. | Check the ID, or leave context out. |
422 | CONTEXT_CONFLICT | Both listing_id and project_id were sent. | Send only one. |
429 | RATE_LIMITED | Too many requests from this website or IP address. | Retry after Retry-After with the same event_id. |
500 | INTERNAL_ERROR | An unexpected problem in EstateCue. | Retry with the same event_id. |
503 | DEPENDENCY_UNAVAILABLE | A temporary problem in EstateCue. | Retry after Retry-After with the same event_id. |
503 | INTEGRATION_UNAVAILABLE | Website 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.
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
}'{
"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 --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"}}'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
// 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.
}